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
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:
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 token de acesso pessoal, faça o seguinte:
Em seu workspace do Databricks, clique em seu nome de usuário do Databricks na barra superior e, em seguida, selecione Configurações no menu suspenso.
Clique em Desenvolvedor.
Ao lado de Access tokens, clique em Gerenciar.
Clique em Gerar novo token.
(Opcional) Insira um comentário que ajude a identificar esse token no futuro e altere o tempo de vida default do token de 90 dias. Para criar um token sem vida útil (não recomendado), deixe a caixa Duração da vida (dias) vazia (em branco).
Clique em Gerar.
Copie o token exibido em um local seguro e clique em Concluído.
Observação
É importante que você salve o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token, não poderá gerar de novo exatamente o mesmo token. Em vez disso, você deverá repetir esse procedimento para criar outro token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do workspace clicando no ícone da lixeira (Revogar) ao lado do token na página Access tokens .
Se o senhor não conseguir criar ou usar o site tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou o tokens ou não lhe deu permissão para criar ou usar o tokens. Consulte o administrador do site workspace ou os tópicos a seguir:
Para configurar e usar a autenticação por access token pessoal do Databricks, faça o seguinte:
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.
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>
oudatabricks 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 comandodatabricks 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 exemplohttps://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 comandodatabricks 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 exemplodatabricks account groups list -p <configuration-profile-name>
oudatabricks 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 ambienteDATABRICKS_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 ambienteDATABRICKS_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 ambientedev
que faz referência, por meio do campoprofile
, a um perfil de configuração denominadoDEV
. Neste exemplo, a CLI do Databricks pesquisa o arquivo.databrickscfg
em busca de um perfil denominadoDEV
e utiliza o valor do campotoken
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 ambienteDATABRICKS_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 ambientedev
que faz referência, por meio do campohost
, 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 campohost
com uma URL de workspace correspondente. A CLI do Databricks localiza um campohost
correspondente e usa o valor do campotoken
desse perfil.