Pular para o conteúdo principal
Última atualização em

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

De um notebook Databricks​

Para chamar a API de um aplicativo a partir de um Notebook Databricks , você deve trocar os tokens internos do Notebook por tokens OAuth com escopo de público-alvo e, em seguida, usar esses tokens para consultar o aplicativo.

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

    Python
    from databricks.sdk import WorkspaceClient

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

  2. Troque os tokens do Notebook por um access token com escopo de público-alvo:

    Python
    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 audience_token como tokens Bearer para chamar seu aplicativo. Para exemplos, consulte Enviar solicitações para o aplicativo.

nota

Os tokens trocados são específicos para o aplicativo em questão, portanto, você não pode usá-los para chamar outras APIs Databricks . O parâmetro scope na solicitação de troca de tokens deve corresponder ou ser um superconjunto dos escopos configurados para o aplicativo na autorização do usuário.

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

Se seu aplicativo usa autorização de usuário, seu access token deve incluir escopos que sejam um superconjunto dos escopos configurados para o aplicativo. Se os tokens não tiverem os escopos necessários, as solicitações podem falhar com erros 401 ou 403.

Os tokens gerados usando a CLI Databricks incluem o escopo all-apis por default, o que atende aos requisitos de autorização do usuário para qualquer aplicativo:

Bash
databricks auth token --profile my-env

Para solicitar escopos específicos em vez de all-apis, você pode solicitar manualmente um access token com escopos explícitos usando um fluxo OAuth personalizado. Por exemplo, a seguinte solicitação pede 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. Os escopos dos seus tokens devem ser um superconjunto dos escopos configurados para o aplicativo na 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: