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 do 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 nome que ajuda você a identificar esse token mais tarde.
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. Selecione um tipo de escopo e adicione escopos de API. Selecione BI Tools para ferramentas que se conectam a databricks SQL warehouses como Tableau ou Power BI ou selecione Other APIs para escolher escopos manualmente. Consulte tokens de acesso pessoal com escopo.
8. Para habilitar o escopo automático para este token, ative Tokens de escopo automático. O autoescopo restringe automaticamente os escopos do token às APIs que ele utiliza, aplicando o all-apis escopo temporariamente durante o período de observação. Essa opção aparece apenas quando um administrador ativou a pré-visualização do autoescopo para seu workspace, e o autoescopo se aplica apenas a tokens com vida útil superior a 30 dias. Consulte Escopo automático para tokens de acesso pessoal.
9. Clique em Gerar.
10. 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 escopo e adicione escopos de API ao gerar um novo token. Selecione BI Tools para ferramentas que se conectam a databricks SQL warehouses como Tableau ou Power BI ou selecione Other APIs para escolher escopos manualmente.

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

Escopo automático para tokens de acesso pessoal

O escopo automático restringe automaticamente as permissões de um token apenas às APIs que ele usa ativamente. O Azure Databricks observa o uso da API do token ao longo de um período de 30 dias e então aplica os escopos inferidos. O Auto-scoping é executado uma vez por token. Durante o período de observação, o token mantém o acesso total ao espaço de trabalho (o all-apis escopo). O Azure Databricks envia um e-mail de lembrete 7 dias antes da imposição e um e-mail de imposição quando os escopos inferidos são aplicados.

Controles de escopo automático

• Visualização do espaço de trabalho (controlada pelo administrador): Um administrador ativa ou desativa a pré-visualização automática de escopo para todo o espaço de trabalho a partir do console da conta ou da página Pré-visualizações do espaço de trabalho. Consulte Gerenciar visualizações do Azure Databricks.
• Configuração por token (autoscope_enabled): Quando a pré-visualização está ativada, cada token adere ou não individualmente no momento da criação.

O escopo automático se aplica apenas a tokens com vida útil superior a 30 dias. Isso inclui novos tokens criados com auto-escoping ativado e tokens existentes de longa duração. Para um token elegível existente, o período de observação de 30 dias começa quando um administrador ativa a prévia. O Azure Databricks aplica os escopos inferidos ao final desse período e envia um e-mail de lembrete 7 dias antes da entrada em vigor, o mesmo cronograma de um token com escopo automático recém-criado.

Desativar delimitação automática

• Um token, antes da imposição: Defina o token para escopos específicos na interface do workspace (Configurações>Desenvolvedor>Tokens de acesso>Gerenciar, depois clique em Atualizar token) ou com a API de Token (veja Atualizar os escopos de um token de acesso pessoal). Definir escopos específicos interrompe o escopo automático permanentemente para esse token. Definir o token de volta para o all-apis escopo (um array vazio scopes) é um no-op e não interrompe o auto-scoping. Para manter um token com acesso total all-apis que nunca é restringido automaticamente por escopo, crie um novo token com escopo automático desativado.
• Todo o espaço de trabalho: peça a um administrador para desativar a prévia de escopo automático na página Previews. Consulte Gerenciar visualizações do Azure Databricks.

Após a finalização da aplicação, o auto-escoping não é mais executado para aquele token, então você pode definir seus escopos livremente, inclusive de volta para all-apis.

Para revisar o status de auto-escoping e os escopos inferidos para seus tokens, veja Revisar status de auto-escoping dos tokens.

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 o 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 por workspace de destino do 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, defina como a URL por workspace do Azure Databricks, 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 . 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 de Host do Databricks, insira sua URL de por workspace do Azure Databricks, por exemplo, https://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 do Azure Databricks, especificado como a URL por workspace de destino do 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 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 de Host do Databricks, insira sua URL de por workspace do Azure Databricks, 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, ou um array vazio ([]) para conceder acesso total ao espaço de trabalho (o all-apis escopo). 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"
  ],
  "autoscope_enabled": true
}'

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, haverá falha na solicitação 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"
}'

Para conceder a um token acesso completo ao espaço de trabalho (o escopo all-apis), defina scopes como um array vazio ("scopes": []). A string all-apis literal não é um valor de escopo aceito.

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.