Autenticar com tokens de acesso pessoal do Azure Databricks (legado)

Tokens de acesso pessoal (PATs) do Azure Databricks permitem que você se autentique em recursos e APIs no nível do espaço de trabalho. Você pode armazená-las em variáveis de ambiente ou perfis de Azure Databricks configuração. Cada PAT é válido para apenas um workspace e um usuário pode criar até 600 PATs por workspace. Azure Databricks revoga automaticamente PATs que não são usadas há 90 dias.

Você não pode usar tokens de acesso pessoal para automatizar a funcionalidade de nível de conta do Azure Databricks. Em vez disso, use os tokens Microsoft Entra ID dos administradores de conta do Azure Databricks. Os administradores de conta do Azure Databricks podem ser usuários ou principais de serviço. Para obter mais informações, consulte:

• Gerenciar usuários
• Entidades de serviço
• Grupos

Criar tokens de acesso pessoal para usuários do workspace

Para criar um token de acesso pessoal para o usuário do workspace Azure Databricks, faça o seguinte:

1. No workspace Azure Databricks, clique no nome de usuário na barra superior e selecione Settings.
2. Clique em Desenvolvedor.
3. Ao lado de Tokens de acesso, clique em Gerenciar.
4. Clique em Gerar novo token.
5. Insira um comentário que ajude você a identificar esse token no futuro.
6. Defina o tempo de vida do token em dias. Veja Definir o tempo de vida máximo de novos tokens de acesso pessoal.
7. Para limitar as permissões do token, selecione um tipo de token e adicione escopos de API. Consulte tokens de acesso pessoal com escopo.
8. Clique em Gerar.
9. Copie o token exibido para um local seguro e clique em Concluído. Salve o token com segurança e não compartilhe-o. Se você perdê-lo, deverá criar um novo token.

Se você não puder criar ou usar tokens, o administrador do workspace poderá ter desabilitado tokens ou não concedido permissão. Veja o administrador do workspace ou o seguinte:

• Habilitar ou desabilitar a autenticação com token de acesso pessoal para o espaço de trabalho
• Permissões do token de acesso pessoal

Tokens pessoais de acesso com escopo

Os tokens de acesso pessoal com escopo limitam as permissões de um token a operações específicas da API. Em vez de conceder acesso completo ao workspace, você atribui um ou mais escopos de API, como sql, unity-catalogou scim, que limitam quais operações de API REST o token pode chamar.

Para criar um token com escopo na interface do usuário do workspace, selecione um tipo de token e adicione escopos de API ao gerar um novo token. Se você não atribuir escopos, o token manterá as permissões completas da identidade de criação.

Para obter uma lista completa de escopos e suas operações de API associadas, consulte os escopos da API.

Criar tokens de acesso pessoal para entidades de serviço

Um principal de serviço pode criar tokens de acesso pessoal para si mesmo.

1. Execute o seguinte comando para gerar um token de acesso:

   databricks tokens create \
     --lifetime-seconds <lifetime-seconds> \
     -p <profile-name>
   

   Substitua os seguintes valores:

   • <lifetime-seconds>: tempo de vida do token em segundos, como 86400 por 1 dia. O padrão é o limite máximo do espaço de trabalho (normalmente 730 dias).
   • <profile-name>: perfil de configuração com informações de autenticação. Usa DEFAULT como padrão.

2. Copie token_value da resposta, que é o token de acesso para sua entidade de serviço. Salve o token com segurança e não compartilhe-o. Se você perdê-lo, deverá criar um novo token.

Se você não puder criar ou usar tokens, o administrador do workspace poderá ter desabilitado tokens ou não concedido permissão. Veja o administrador do workspace ou o seguinte:

• Habilitar ou desabilitar a autenticação com token de acesso pessoal para o espaço de trabalho
• Permissões do token de acesso pessoal

Executar autenticação de token de acesso pessoal

Para configurar a autenticação com token de acesso pessoal do Azure Databricks, defina os seguintes campos associados como variáveis de ambiente, campos .databrickscfg, campos Terraform ou campos Config:

• O host do Azure Databricks, especificado como a URL da área de trabalho específica no Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.
• O token de acesso pessoal do Azure Databricks para a conta de usuário no Azure Databricks.

Para realizar a autenticação de token de acesso pessoal do Azure Databricks, integre o seguinte em seu código, conforme a ferramenta participante ou o SDK:

Ambiente

Para usar variáveis de ambiente para um tipo de autenticação Azure Databricks específico com uma ferramenta ou SDK, consulte Authorize o acesso a recursos Azure Databricks ou a documentação da ferramenta ou do SDK. Consulte também variáveis de ambiente e campos para autenticação unificada e a prioridade do método de autenticação.

Defina as seguintes variáveis de ambiente:

• DATABRICKS_HOST, definido como a URL Azure Databricks per-workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.
• DATABRICKS_TOKEN, definido como a cadeia de caracteres de token.

Perfil

Crie ou identifique um perfil de configuração do Azure Databricks com os campos a seguir no arquivo .databrickscfg. Se você criar o perfil, substitua os espaços reservados pelos valores apropriados. Para usar o perfil com uma ferramenta ou SDK, consulte Autorizar acesso aos recursos do Azure Databricks ou a documentação da ferramenta ou do SDK. Consulte também variáveis de ambiente e campos para autenticação unificada e a prioridade do método de autenticação.

Defina os seguintes valores em seu arquivo .databrickscfg. Nesse caso, o host é a URL Azure Databricks per-workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net:

[<some-unique-configuration-profile-name>]
host  = <workspace-url>
token = <token>

Em vez de definir manualmente os valores, você pode usar a CLI do Databricks para definir esses valores em vez disso:

1. Use o CLI do Databricks para criar um perfil de configuração do Azure Databricks denominado DEFAULT que usa autenticação de token de acesso pessoal do Azure Databricks. Para fazer isso, execute o seguinte comando:

   databricks configure --profile DEFAULT
   

2. Para o prompt Databricks Host, insira sua URL Azure Databricks por espaço de trabalho, por exemplohttps://adb-1234567890123456.7.azuredatabricks.net.

3. Para o prompt Token de Acesso Pessoal, insira o token de acesso pessoal do Azure Databricks para o seu espaço de trabalho.

CLI

Para a CLI da Databricks, execute o comando databricks configure. Nas solicitações, insira as seguintes configurações:

• O host Azure Databricks, especificado como a URL de destino por espaço de trabalho do Azure Databricks , por exemplo, .
• O token de acesso pessoal do Azure Databricks para a conta de usuário do Azure Databricks.

Para obter mais informações, consulte Autenticação de token de acesso pessoal (herdado).

Conectar

Para o Databricks Connect, use a CLI do Databricks para definir os valores em seu arquivo .databrickscfg, para operações no nível de workspace do Azure Databricks conforme especificado na seção Perfil.

O procedimento a seguir cria um perfil de configuração Azure Databricks chamado DEFAULT, que substitui qualquer perfil DEFAULT existente. Para verificar se existe um DEFAULT perfil, execute databricks auth env --profile DEFAULT. Se existir, use um nome de perfil diferente.

1. Execute o comando a seguir para criar um perfil de configuração de Azure Databricks chamado DEFAULT que usa a autenticação de token de acesso pessoal.

   databricks configure \
     --configure-cluster \
     --profile DEFAULT
   

2. Para o prompt Databricks Host, insira sua URL do Azure Databricks por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.

3. Para o campo Token de Acesso Pessoal, insira o token de acesso pessoal para seu espaço de trabalho.

4. Na lista de clusters disponíveis, selecione o cluster do Azure Databricks de destino em seu espaço de trabalho. Você pode digitar qualquer parte do nome de exibição do cluster para filtrar a lista de clusters disponíveis.

Usar a API REST Azure Databricks para emitir tokens de acesso pessoal

Azure Databricks fornece um ponto de extremidade REST /api/2.0/token/create para emitir PATs. Consulte Criar um token de usuário para obter detalhes da API.

No exemplo a seguir, defina estes valores:

• <databricks-instance>: a URL do workspace do Databricks. Por exemplo, dbc-abcd1234-5678.cloud.databricks.com.
• <your-existing-access-token>: um PAT (cadeia de caracteres) válido existente que tem permissões para criar novos tokens.
• <lifetime-seconds>: o tempo de vida do token em segundos.
• <scopes>: uma lista de escopos a serem atribuídos ao token. Consulte tokens de acesso pessoal com escopo.

curl -X POST https://<databricks-instance>/api/2.0/token/create \
-H "Authorization: Bearer <your-existing-access-token>" \
-H "Content-Type: application/json" \
-d '{
  "lifetime_seconds": <lifetime-seconds>,
  "scopes": [
    "sql",
    "authentication"
  ]
}'

Se for bem-sucedido, isso resultará em uma carga de resposta semelhante a:

{
  "token_value": "<your-newly-issued-pat>",
  "token_info": {
    "token_id": "<token-id>",
    "creation_time": <creation-timestamp>,
    "expiry_time": <expiry-timestamp>,
    "comment": "<comment>",
    "scopes": ["authentication", "sql"],
    "last_accessed_time": 0
  }
}

Coloque o novo token da resposta no cabeçalho de autorização de chamadas subsequentes para as APIs REST do Databricks. Por exemplo:

# This example uses a simple GET. For POST or other REST verbs, you may need to provide additional parameters.
curl -X GET "https://<databricks-instance>/api/2.0/<path-to-endpoint>" \
     -H "Authorization: Bearer <your-new-pat>"

import requests

headers = {
    'Authorization': 'Bearer <your-new-pat>'
}
# This example is for an HTTP GET operation.
response = requests.get('https://<databricks-instance>/api/2.0/<path-to-endpoint>', headers=headers)

Atualizar os escopos de um token de acesso pessoal

Se um token com escopo estiver ausente no escopo necessário para uma chamada à API, a solicitação falhará com um erro que indica o escopo ausente. Para atualizar os escopos de um token, use o endpoint REST /api/2.0/token/<token_id>. O token de chamada deve ter o escopo authentication, que permite o gerenciamento de outros tokens. Use o update_mask campo para especificar quais campos de token serão atualizados.

curl -X PATCH https://<databricks-instance>/api/2.0/token/<token_id> \
-H "Authorization: Bearer <your-existing-access-token>" \
-H "Content-Type: application/json" \
-d '{
  "token": {
    "scopes": ["sql", "unity-catalog"]
  },
  "update_mask": "scopes"
}'

As alterações de escopo podem levar até dez minutos para serem propagadas.

Para exibir todos os escopos disponíveis, use GET /api/2.0/token-scopes.