Autenticação para a CLI do Databricks

Observação

Essas informações se aplicam ao site Databricks CLI versões 0.205 e superiores. A CLI da Databricks está em visualização pública.

Databricks CLI O uso está sujeito à LicençaDatabricks e ao Aviso de PrivacidadeDatabricks , incluindo qualquer provisionamento de Dados de Uso.

Este artigo descreve como configurar a autenticação entre a CLI do Databricks e suas accounts e workspaces do Databricks. Consulte O que é a CLI do Databricks?.

Este artigo pressupõe que você já instalou a CLI do Databricks. Consulte Instalar ou atualizar a CLI do Databricks.

Antes de executar os comandos da CLI do Databricks, configure a autenticação entre a CLI do Databricks e suas contas, espaços de trabalho do Databricks ou uma combinação deles, dependendo dos tipos de comandos da CLI que você deseja executar.

Você deve autenticar a CLI do Databricks para os recursos relevantes em tempo de execução para executar comandos de automação do Databricks em uma account ou workspace do Databricks. Dependendo se você deseja executar comandos de nível de workspace do Databricks, comandos de nível de account do Databricks, ou ambos, é necessário autenticar-se no workspace do Databricks, na account, ou em ambos. Para uma lista de grupos de comandos da CLI do Databricks em nível de workspace e account, execute o comando databricks -h. Para uma lista de operações da API REST em nível de workspace e account cobertas pelos comandos da CLI do Databricks, consulte a API REST do Databricks.

As seções a seguir fornecem informações sobre como configurar a autenticação entre a CLI do Databricks e o Databricks:

Autenticação por access token pessoal do Databricks
Autenticação de máquina para máquina (M2M) do OAuth
Autenticação de usuário para máquina (U2M) do OAuth
Ordem de avaliação de autenticação

Autenticação por access token pessoal do Databricks

A autenticação do token de acesso pessoal do Databricks utiliza um token de acesso pessoal do Databricks para autenticar a entidade desejada do Databricks, como por exemplo uma conta de usuário do Databricks ou uma entidade de serviço do Databricks. Consulte também Autenticação de token de acesso pessoal do Databricks.

Observação

Você não pode usar a autenticação com access tokens pessoais do Databricks para autenticar com uma account do Databricks, pois os comandos em nível de account não utilizam access tokens pessoais do Databricks para autenticação. Para autenticar com uma account do Databricks, considere usar um dos seguintes tipos de autenticação:

Autenticação de máquina para máquina (M2M) do OAuth
Autenticação de usuário para máquina (U2M) do OAuth

Observação

A autenticação básica usando um nome de usuário e senha do Databricks chegou ao fim da vida útil em 10 de julho de 2024. Consulte Fim da vida útil das senhas gerenciadas pelo Databricks.

Para criar um access token pessoal, siga os passos em Databricks access tokens pessoal para usuários do workspace .

Observação

O procedimento a seguir cria um perfil de configuração do Databricks com o nome DEFAULT. Se você já tiver um perfil de configuração DEFAULT que deseja usar, ignore este procedimento. Caso contrário, esse procedimento substituirá o perfil de configuração do DEFAULT existente. Para exibir os nomes e hosts de qualquer perfil de configuração existente, execute o comando databricks auth profiles.

Para criar um perfil de configuração com um nome diferente de DEFAULT, adicione --profile <configuration-profile-name> ou -p <configuration-profile-name> ao final do comando databricks configure a seguir, substituindo <configuration-profile-name> pelo nome do novo perfil de configuração.

Para configurar e usar a autenticação por access token pessoal do Databricks, faça o seguinte:

Use a CLI do Databricks para executar o seguinte comando:
```
databricks configure
```
Para o prompt Databricks Host, insira o URL da instância do seu workspace do Databricks, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com.
Para o prompt Access token pessoal, insira o access token pessoal do Databricks para seu workspace

Depois de inserir seu access token pessoal do Databricks, um perfil de configuração correspondente é adicionado ao seu arquivo .databrickscfg . Se a CLI do Databricks não conseguir encontrar esse arquivo em seu local padrão, ele criará esse arquivo para você primeiro e depois adicionará esse perfil de configuração ao novo arquivo. O local padrão desse arquivo é na sua pasta ~ (sua página inicial de usuário) no Unix, Linux ou macOS, ou sua pasta %USERPROFILE% (sua página inicial de usuário) no Windows.
Agora você pode usar a opção --profile ou -p da CLI do Databricks seguida pelo nome do seu perfil de configuração, como parte do comando da CLI do Databricks, por exemplo, databricks clusters list -p <configuration-profile-name>.

Autenticação OAuth machine-to-machine (M2M)

Em vez de se autenticar com Databricks usando a autenticaçãoDatabricks pessoal access token , o senhor pode usar a autenticação OAuth. OAuth fornece ao tokens tempos de expiração mais rápidos do que o Databricks pessoal access tokens, e oferece melhor invalidação e escopo de sessão no lado do servidor. Como o OAuth access tokens expira em menos de uma hora, isso reduz o risco associado à verificação acidental do tokens no controle de origem. Consulte também Autenticar o acesso ao Databricks com uma entidade de serviço usando o OAuth (OAuth M2M).

Para configurar e usar a autenticação OAuth M2M, faça o seguinte:

Conclua as instruções de configuração da autenticação OAuth M2M. Consulte Autenticar o acesso ao Databricks com uma entidade de serviço usando OAuth (OAuth M2M)
Crie ou identifique um perfil de configuração do Databricks com os seguintes campos no arquivo .databrickscfg. Se você criar o perfil, substitua os placeholders pelos valores apropriados.

Para comandos em nível de account, defina os seguintes valores em seu arquivo .databrickscfg:
```
[<some-unique-configuration-profile-name>]
host          = <account-console-url>
account_id    = <account-id>
client_id     = <service-principal-client-id>
client_secret = <service-principal-oauth-secret>
```
Para comandos no nível do workspace , defina os seguintes valores no arquivo .databrickscfg :
```
[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-oauth-secret>
```
Observação

O local padrão do arquivo .databrickscfg é no diretório inicial do usuário. É ~ para Linux e macOS, e %USERPROFILE% para Windows.
Use a opção --profile ou -p da CLI do Databricks seguida pelo nome do seu perfil de configuração como parte da chamada de comando da CLI do Databricks, por exemplo, databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

Dica

Pressione Tab após --profile ou -p para exibir uma lista de perfis de configuração disponíveis, em vez de digitar o nome do perfil de configuração manualmente.

Autenticação OAuth user-to-machine (U2M)

Em vez de autenticar com Databricks usando a autenticação de tokens, o senhor pode usar a autenticação OAuth. OAuth fornece ao tokens tempos de expiração mais rápidos do que o Databricks pessoal access tokens, e oferece melhor invalidação e escopo de sessão no lado do servidor. Como o OAuth access tokens expira em menos de uma hora, isso reduz o risco associado à verificação acidental do tokens no controle de origem. Consulte também Autenticar o acesso a Databricks com um usuário account usando OAuth (OAuth U2M).

Para configurar e usar a autenticação OAuth U2M, faça o seguinte:

Antes de chamar qualquer comando no nível da account do Databricks, você deve iniciar o gerenciamento do token OAuth localmente executando o seguinte comando. Esse comando deve ser executado separadamente para cada account em que você deseja executar comandos. Se você não deseja chamar nenhuma operação de nível de account, pule para a etapa 5.

No comando a seguir, substitua os seguintes espaços reservados:
- Substitua <account-console-url> pelo seu Databricks https://accounts.cloud.databricks.com.
- Substitua <account-id> pelo ID da sua account do Databricks. Consulte Localizar o ID da sua account.
```
databricks auth login --host <account-console-url> --account-id <account-id>
```
O Databricks CLI solicita que o usuário salve o account URL do console e o account ID localmente como um Databricks perfil de configuração. Pressione Enter para aceitar o nome de perfil sugerido ou insira o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome é substituído por esse URL do console account e pelo ID account.

Para obter uma lista de todos os perfis existentes, em um terminal ou prompt de comando separado, execute o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.
No seu navegador, siga as instruções na tela para fazer login na sua account do Databricks.
Para ver o valor atual do token OAuth e a data e hora de expiração futura, execute o comando databricks auth token --host <account-console-url> --account-id <account-id>.
Antes de chamar qualquer comando no nível do workspace do Databricks, você deve iniciar o gerenciamento do token OAuth localmente executando o seguinte comando. Esse comando deve ser executado separadamente para cada workspace no qual você deseja executar comandos.

No comando a seguir, substitua <workspace-url> pelo URL da instância do seu workspace do Databricks, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com.
```
databricks auth login --host <workspace-url>
```
A CLI do Databricks pede que você salve o URL do espaço de trabalho no local como perfil de configuração do Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou insira o nome de um perfil novo ou existente. Se já existir um perfil com o mesmo nome ele será substituído pelo URL do console desta conta e pela ID da conta.

Para obter uma lista de todos os perfis existentes, em um terminal ou prompt de comando separado, execute o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.
No navegador da web, conclua as instruções na tela para fazer log in no workspace do Databricks.
Para ver o valor atual do token OAuth e a data e hora de expiração futura, execute o comando databricks auth token --host <workspace-url>.
Use a opção --profile ou -p da CLI do Databricks, seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

Dica

Você pode pressionar Tab após --profile ou -p para exibir a lista de perfis de configuração disponíveis existentes para escolher, em vez de inserir o nome do perfil de configuração manualmente.

Ordem de autenticação da avaliação

Sempre que a CLI do Databricks precisa reunir as configurações necessárias para tentar se autenticar com um workspace ou account do Databricks, ela procura essas configurações nos seguintes locais, na seguinte ordem.

Para qualquer comando executado a partir do diretório de trabalho do bundle (a raiz do bundle e qualquer caminho aninhado), os valores dos campos dentro dos arquivos de configuração do bundle de um projeto. (Os arquivos de configuração do bundle não suportam a inclusão direta de valores de credenciais de acesso.)
Os valores das variáveis de ambiente, conforme listado neste artigo e em Campos e variáveis de ambiente para autenticação unificada do cliente.
Valores do campo de perfil de configuração no arquivo .databrickscfg , conforme indicado anteriormente neste artigo.

Sempre que a CLI do Databricks encontra as configurações necessárias, ele interrompe a pesquisa em outros locais. Por exemplo:

A CLI do Databricks precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN é definida e o arquivo .databrickscfg também contém vários tokens de acesso pessoal. Neste exemplo, a CLI do Databricks utiliza o valor da variável de ambiente DATABRICKS_TOKEN e não pesquisa o arquivo .databrickscfg .
O comando databricks bundle deploy -t dev precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN não é definida e o arquivo .databrickscfg contém vários access tokens pessoais. O arquivo de configurações do pacote do projeto contém uma declaração de ambiente dev que faz referência, por meio do campo profile, a um perfil de configuração denominado DEV. Neste exemplo, a CLI do Databricks pesquisa o arquivo .databrickscfg em busca de um perfil denominado DEV e utiliza o valor do campo token desse perfil.
O comando databricks bundle run -t dev hello-job precisa do valor de um access token pessoal do Databricks. Uma variável de ambiente DATABRICKS_TOKEN não é definida e o arquivo .databrickscfg contém vários access tokens pessoais. O arquivo de configurações do pacote do projeto contém uma declaração de ambiente dev que faz referência, por meio do campo host, a uma URL específica do workspace do Databricks. Neste exemplo, a CLI do Databricks pesquisa os perfis de configuração no arquivo .databrickscfg em busca de um perfil que contenha um campo host com uma URL de workspace correspondente. A CLI do Databricks localiza um campo host correspondente e usa o valor do campo token desse perfil.