Partilhar via

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

Observação

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

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.
  • 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

Não é possível chamar um aplicativo Databricks diretamente usando um token de ID do Azure Entra. A federação de tokens requer uma etapa de troca de token 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, você deve primeiro trocá-los por tokens OAuth. Ver Autenticar com um token de provedor de identidade.

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

Desenvolvimento local

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

  1. Faça login com a CLI:

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

    O Azure Databricks recomenda o uso da autenticação de usuário para máquina (U2M) 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

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). Consulte 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. 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 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()

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

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

Verifique se o token de acesso inclui os escopos configurados em Editar>autorização de usuário. Se o token não tiver os escopos necessários, as solicitações podem falhar com erros 401 ou 403.

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

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. As ferramentas CLI e SDK fornecem apenas escopos básicos, como all-apis, que podem não ser suficientes para a autorização do usuário.

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:

  • Last updated on