Pular para o conteúdo principal

Conecte-se a um aplicativo API Databricks usando autenticação de tokens

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

nota

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

Requisitos​

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

  • O aplicativo deve expor pelo menos um endpoint API acessível usando rotas /api/ .
  • Você deve ter permissão CAN USE no aplicativo. Consulte Configurar permissões para um aplicativo Databricks.
  • Você deve ser capaz de gerar um access token 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 conectar-se ao seu ambiente de desenvolvimento local, use a CLI ou os SDKs do Databricks com suas credenciais de usuário.

  1. faça login com o CLI:

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

    A Databricks recomenda o uso da autenticação OAuth de usuário para máquina (U2M).

  2. Gerar um access token:

Bash
databricks auth token --profile my-env

Aplicações externas​

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

  1. Crie uma entidade de serviço e obtenha o ID do cliente e o segredo. Veja entidade de serviço.

  2. Gere um access token usando o SDK Databricks :

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

Python
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 os SDKs do 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 usar autorização de usuário, você deverá solicitar manualmente um access token com escopos adicionais usando um fluxo OAuth personalizado.

Certifique-se de que seu access token inclua os escopos configurados em Editar > Autorização do usuário . Se os tokens não tiverem 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 access token com os escopos sql, file.files e dashboards.genie :

Bash
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 access tokens OAuth U2M.

Enviar solicitações para o aplicativo​

Ao chamar o endpoint da API do seu aplicativo, inclua os tokens Bearer no cabeçalho Authorization e substitua <your-endpoint> pelo caminho real API do seu aplicativo:

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

Considerações de segurança​

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

  • Nunca codifique access tokens no seu código-fonte. Use variável de ambiente ou armazenamentos de credenciais seguros.
  • atualize tokens regularmente para minimizar os riscos de segurança caso sejam comprometidos.
  • Evite registrar access tokens ou dados confidenciais nos logs do seu 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 (erros 401)​

Verifique o seguinte:

  • Seus tokens são válidos (execução databricks auth token --profile my-env)
  • Seu perfil está configurado corretamente com databricks auth login
  • Os tokens não expiraram
  • Seus tokens incluem os escopos OAuth necessários. As ferramentas 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 (erros 403)​

Verifique o seguinte:

  • Você tem CAN USE permissão no aplicativo
  • Seus tokens incluem os escopos OAuth necessários. Escopos insuficientes podem causar erros 403, mesmo com permissões válidas.

Aplicativo não encontrado (erros 404)​

Verifique o seguinte:

  • O ID e a URL workspace estão corretos
  • O aplicativo está implantado e em execução
  • O caminho endpoint existe no aplicativo

Problemas de conectividade de rede​

Verifique o seguinte:

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

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

Recurso adicional​

Para mais informação consulte o seguinte recurso:

Última atualização em