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

Você pode chamar um aplicativo Databricks que expõe uma API HTTP (por exemplo, um aplicativo FastAPI ou Gradio) usando a autenticação de token OAuth 2.0 Bearer. Este método funciona a partir do seu ambiente de desenvolvimento local, aplicações externas e outras aplicações do Azure Databricks.

Requerimentos

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

• A aplicação deve expor pelo menos um ponto de extremidade de API acessível usando /api/ rotas.
• Você deve ter CAN USE permissão no aplicativo. Consulte Configurar permissões para um aplicativo Databricks.
• Deve ser capaz de gerar um token de acesso Azure Databricks usando um dos métodos de autenticação suportados.

Métodos de autenticação

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

Desenvolvimento local

Para te ligares a partir do teu ambiente de desenvolvimento local, usa a CLI ou SDKs do Databricks com as tuas credenciais de utilizador.

1. Faça login com a CLI:

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

   Azure Databricks recomenda usar autenticação utilizador-a-máquina OAuth (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
   

Aplicações externas

Para acesso programático a partir de aplicativos externos, use a autenticação da entidade de serviço com credenciais M2M (máquina a máquina). Ver Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

1. Crie um principal de serviço e obtenha o ID do cliente e o segredo do cliente. Consulte Entidades de serviço.

2. Gerar um token de acesso usando o SDK 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 Databricks

Quando você se conecta de um aplicativo Databricks a outro, o aplicativo lida com 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 notebook do Azure Databricks

Para chamar uma API de uma aplicação a partir de um notebook Azure Databricks, deve trocar o token interno do notebook por um token OAuth com escopo de audiência, e depois utilizar esse token para interagir com a app.

1. Obtenha o ID de cliente OAuth da aplicação. Recuperar o ID usando o Azure Databricks SDK:

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

2. Troque o token do notebook por um token de acesso com âmbito definido para audiência.

   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. Utilize o audience_token como token de autenticação Bearer para invocar a sua aplicação. Para exemplos, veja Enviar pedidos para a aplicação.

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

Se a sua aplicação usar autorização de utilizador, o seu token de acesso deve incluir escopos que sejam um superconjunto dos escopos configurados para a app. Se o token não tiver os escopos necessários, as solicitações podem falhar com erros 401 ou 403.

Um token gerado usando a CLI Databricks inclui o all-apis âmbito por defeito, que satisfaz os requisitos de autorização do utilizador para qualquer aplicação:

databricks auth token --profile my-env

Para solicitar escopos específicos em vez de all-apis, 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.filese 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 pedidos para a aplicação

Ao chamares os endpoints da API da tua aplicação, deves incluir o token Bearer no cabeçalho Authorization e substituir <your-endpoint> pelo caminho real da API da tua aplicação.

CURL

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

Python com pedidos

import requests

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

Python com 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

Quando se ligar a aplicações a partir do seu ambiente local, siga estas práticas recomendadas de segurança:

• Nunca codifice tokens de acesso em seu código-fonte. Use variáveis de ambiente ou armazenamentos de credenciais seguros.
• Atualize os tokens regularmente para minimizar os riscos de segurança se eles forem comprometidos.
• Evite registrar tokens de acesso ou dados confidenciais nos logs do aplicativo.

Solução de problemas

Se você encontrar problemas ao se conectar ao seu aplicativo a partir de uma máquina local, tente estas soluções.

Falhas de autenticação (401 erros)

Verifique o seguinte:

• Seu token é válido (executar databricks auth token --profile my-env)
• O 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 seu token devem ser um superconjunto dos escopos configurados para a aplicação na autorização do utilizador.

Permissão negada (403 erros)

Verifique o seguinte:

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

App não encontrado (404 erros)

Verifique o seguinte:

• O ID e o URL do espaço de trabalho estão corretos
• O aplicativo é implantado e executado
• 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 a partir 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: Conecte-se a partir da máquina local
• Guia: Conectar a partir de aplicações externas
• Livro de receitas: Ligar a partir de outras aplicações
• Configurar permissões para um aplicativo Databricks
• Configurar o espaço de trabalho e o ambiente de desenvolvimento do Databricks Apps
• Autenticação para a CLI do Databricks
• Autenticação unificada da Databricks