Compartilhar via

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 do Azure Databricks.

Observação

Esse método se aplica somente a aplicativos que disponibilizam APIs ou endpoints (acessíveis usando /api/ rotas). Para aplicativos que fornecem apenas uma interface do usuário ou processamento em segundo plano, você não pode se conectar usando a autenticação de token.

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 do Azure Databricks usando um dos métodos de autenticação com suporte.

Métodos de autenticação

Observação

Você não pode chamar um aplicativo do Databricks diretamente usando um token de ID do Azure Entra. A federação de token requer uma etapa de troca de tokens do lado do cliente, que o Azure Databricks não executa no lado do servidor. Para usar tokens de ID do Azure Entra para autenticação, primeiro você deve trocá-los por tokens OAuth. Veja Autenticar com um token de provedor de identidade.

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 Azure Databricks com suas credenciais de usuário.

  1. Faça logon com a CLI:

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

    O Azure Databricks recomenda o uso da autenticação U2M (usuário para máquina) do OAuth.

  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 Autorizar o acesso da entidade de serviço ao Azure Databricks com o 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 Azure 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()

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

Quando você usa a CLI do Azure Databricks ou SDKs com autenticação unificada, conforme mostrado na seção anterior, as ferramentas solicitam automaticamente o escopo básico all-apis . No entanto, se o aplicativo usar a autorização do usuário, você deverá solicitar manualmente um token de acesso com escopos adicionais usando um fluxo OAuth personalizado.

Certifique-se de que o seu token de acesso inclua os âmbitos configurados em Editar autorização de usuário. Se o token não tiver os escopos necessários, as solicitações poderão falhar com erros 401 ou 403.

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 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. As ferramentas de CLI e SDK fornecem apenas escopos básicos, como all-apis, o que pode não ser suficiente para 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:

  • Last updated on