Conectar-se a um aplicativo de API do Databricks usando autenticação de token

Você pode chamar um aplicativo do Databricks que expõe uma API HTTP (por exemplo, um aplicativo FastAPI ou Gradio) usando a autenticação de token de portador OAuth 2.0. Esse método funciona em seu ambiente de desenvolvimento local, aplicativos externos e outros aplicativos Azure Databricks.

Requirements

Para se conectar a um aplicativo do Databricks usando a autenticação de token, você deve atender aos seguintes requisitos:

• O aplicativo deve expor pelo menos um endpoint de API acessível usando a rota /api/.
• Você deve ter permissão CAN USE no aplicativo. Consulte Configurar permissões para um aplicativo do Databricks.
• Você deve ser capaz de gerar um token de acesso Azure Databricks usando um dos métodos de autenticação com suporte.

Métodos de autenticação

Escolha o método de autenticação que corresponde ao cenário de conexão:

Desenvolvimento local

Para se conectar do seu ambiente de desenvolvimento local, use a CLI ou os SDKs do Databricks com suas credenciais de usuário.

1. Faça logon com a CLI:

   databricks auth login --host https://<workspace-url> --profile my-env
   

   Azure Databricks recomenda usar OAuth autenticação de usuário para máquina (U2M).

2. Gere um token de acesso:

   CLI

   databricks auth token --profile my-env
   

   Python

   from databricks.sdk.core import Config
   config = Config(profile="my-env")
   token = config.oauth_token().access_token
   

Aplicativos externos

Para acesso programático de aplicativos externos, use a autenticação da entidade de serviço com credenciais de máquina para máquina (M2M). Consulte Autorize o acesso da entidade de serviço no Azure Databricks com OAuth.

1. Crie um princípio de serviço e obtenha o ID e o segredo do cliente. Confira Entidades de serviço.

2. Gere um token de acesso usando o SDK do Databricks:

   from databricks.sdk import WorkspaceClient
   import requests
   
   # Option 1: Explicit credentials
   wc = WorkspaceClient(
       host="https://<workspace-url>",
       client_id="<service-principal-client-id>",
       client_secret="<service-principal-client-secret>"
   )
   
   # Option 2: Environment variables
   # Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
   wc = WorkspaceClient()
   
   # Generate Bearer token
   headers = wc.config.authenticate()
   

De outros aplicativos do Databricks

Quando você se conecta de um aplicativo do Databricks a outro, o aplicativo manipula a autenticação automaticamente usando sua entidade de serviço atribuída.

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

De um bloco de anotações Azure Databricks

Para chamar a API de um aplicativo a partir de um notebook do Azure Databricks, você deve substituir o token interno do notebook por um token OAuth com escopo para a audiência desejada e, em seguida, usar esse token para consultar o aplicativo.

1. Obtenha a ID do cliente OAuth do aplicativo. Recupere a ID usando o SDK do Azure Databricks:

   from databricks.sdk import WorkspaceClient
   
   w = WorkspaceClient()
   app_client_id = w.apps.get("<app-name>").oauth2_app_client_id
   

2. Troque o token de notebook por um token de acesso com escopo voltado para o público.

   import requests
   
   url = "https://<workspace-url>/oidc/v1/token"
   notebook_token = (
       dbutils.notebook.entry_point.getDbutils()
       .notebook().getContext().apiToken().get()
   )
   
   data = {
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "subject_token": notebook_token,
       "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "all-apis",
       "audience": app_client_id,
   }
   
   response = requests.post(url=url, data=data)
   audience_token = response.json()["access_token"]
   

3. Use o audience_token como Bearer token para chamar seu aplicativo. Para obter exemplos, consulte Enviar solicitações para o aplicativo.

Especificar escopos OAuth para autorização do usuário

Se o aplicativo usar a autorização do usuário, o token de acesso deverá incluir escopos que sejam um superconjunto dos escopos configurados para o aplicativo. Se o token não tiver os escopos necessários, as solicitações poderão falhar com erros 401 ou 403.

Um token gerado usando a CLI do Databricks inclui o all-apis escopo por padrão, o que atende aos requisitos de autorização do usuário para qualquer aplicativo:

databricks auth token --profile my-env

Para solicitar escopos específicos, em vez de all-apis, você pode solicitar manualmente um token de acesso com escopos explícitos usando um fluxo OAuth personalizado. Por exemplo, a solicitação a seguir solicita explicitamente um token de acesso com os escopos sql, file.files e dashboards.genie:

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

Para obter instruções completas, consulte Gerar manualmente tokens de acesso OAuth U2M.

Enviar solicitações para o aplicativo

Ao chamar os endpoints da API do aplicativo, inclua o Bearer token no cabeçalho de Autorização e substitua <your-endpoint> pelo endpoint real da API do aplicativo.

CURL

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Python com solicitações

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

Python com o SDK

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

Considerações de segurança

Ao se conectar a aplicativos do seu ambiente local, siga estas práticas recomendadas de segurança:

• Nunca insira diretamente tokens de acesso no código-fonte. Use variáveis de ambiente ou repositórios de credenciais seguras.
• Atualize os tokens regularmente para minimizar os riscos de segurança se eles estiverem comprometidos.
• Evite registrar tokens de acesso ou dados confidenciais nos logs do seu aplicativo.

Resolução de problemas

Se você encontrar problemas ao se conectar ao seu aplicativo de um computador local, experimente essas soluções.

Falhas de autenticação (401 erros)

Verifique o seguinte:

• Seu token é válido (executar databricks auth token --profile my-env)
• Seu perfil está configurado corretamente com databricks auth login
• O token não expirou
• Seu token inclui os escopos OAuth necessários. Os escopos do token devem ser um superconjunto dos escopos configurados para o aplicativo na autorização do usuário.

Permissão negada (403 erros)

Verifique o seguinte:

• Você tem CAN USE permissão para o aplicativo
• Seu token inclui os escopos OAuth necessários. Escopos insuficientes podem causar 403 erros mesmo com permissões válidas.

Aplicativo não encontrado (404 erros)

Verifique o seguinte:

• A ID e a URL do workspace estão corretas
• O aplicativo é implantado e em execução
• O caminho do ponto de extremidade existe no aplicativo

Problemas de conectividade de rede

Verifique o seguinte:

• Sua rede permite conexões HTTPS de saída
• O *.databricksapps.com domínio é acessível da sua rede

Além disso, verifique se sua organização usa um proxy que requer configuração.

Recursos adicionais

Para obter mais informações, consulte os seguintes recursos:

• Livro de receitas: conectar-se do computador local
• Guia: conectar-se a partir de aplicativos externos
• Livro de receitas: conectar-se de outros aplicativos
• Configurar permissões para um aplicativo do Databricks
• Configurar seu workspace e ambiente de desenvolvimento do Databricks Apps
• Autenticação para a CLI do Databricks
• Autenticação unificada do Databricks