Compartilhar via

CLI herdada do Databricks

Importante

Esta documentação foi desativada e pode não estar atualizada.

O Databricks recomenda a utilização da versão 0.205 ou superior da CLI do Databricks em substituição à versão antiga 0.18 ou inferior. A CLI do Databricks versão 0.18 ou inferior não tem suporte do Databricks. Para obter informações sobre as versões da CLI do Databricks 0.205 e superiores, consulte a CLI do Databricks.

Para migrar da CLI do Databricks versão 0.18 ou inferior para a CLI do Databricks versão 0.205 ou superior, consulte migração da CLI do Databricks.

A CLI herdada do Databricks está em um estado Experimental. O Databricks não planeja o desenvolvimento de novos recursos para a CLI herdada do Databricks neste momento.

A CLI herdada do Databricks não tem suporte por meio dos canais de suporte do Databricks. Para fornecer comentários, fazer perguntas e relatar problemas, use a guia Issues no repositório interface de linha de comando do Databricks no GitHub.

A interface de linha de comando legada do Databricks (também conhecida como CLI legada do Databricks) é um utilitário que oferece uma interface de fácil uso para automatizar a plataforma do Azure Databricks a partir do seu terminal, prompt de comando ou scripts de automação.

Requisitos

  • Python 3 a 3,6 e superior
  • Python 2 a 2,7,9 e superior

Importante

No macOS, a instalação padrão do Python 2 não implementa o protocolo TLSv1_2 e a execução da CLI herdada do Databricks com essa instalação Python resulta no erro: AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2'. Use Homebrew para instalar uma versão do Python que tenha ssl.PROTOCOL_TLSv1_2.

Limitações

Não é suportado o uso da CLI herdada do Databricks com contêineres de armazenamento com firewall ativado. O Databricks recomenda que você use o Databricks Connect ou o az storage.

Configurar a CLI

Esta seção descreve como configurar a CLI herdada do Databricks.

Instalar ou atualizar a CLI

Esta seção descreve como instalar ou atualizar seu computador de desenvolvimento para executar a CLI herdada do Databricks.

Instalar a CLI

Execute pip install databricks-cli usando a versão apropriada do pip para a instalação do Python:

pip install databricks-cli

Atualizar a CLI

Execute pip install databricks-cli --upgrade usando a versão apropriada do pip para a instalação do Python:

pip install databricks-cli --upgrade

Para listar a versão da CLI herdada do Databricks que está instalada no momento, execute databricks --version:

databricks --version

Configurar a autenticação

Antes de executar comandos herdados da CLI do Databricks, você deve configurar a autenticação entre a CLI herdada do Databricks e a Azure Databricks. Esta seção descreve como configurar a autenticação para a CLI herdada do Databricks.

Para autenticar com a CLI herdada do Databricks, você pode usar um token de acesso pessoal Databricks ou um token Microsoft Entra ID (anteriormente Azure Active Directory).

Observação

Como melhor prática de segurança, ao autenticar com ferramentas, sistemas, scripts e aplicativos automatizados, o Databricks recomenda que você use tokens de acesso pertencentes às entidades de serviço e não aos usuários do workspace. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Configurar a autenticação usando um token de Microsoft Entra ID

Para configurar a CLI herdada do Databricks usando um token Microsoft Entra ID, genera o token Microsoft Entra ID (anteriormente Azure Active Directory) e armazene-o na variável de ambiente DATABRICKS_AAD_TOKEN.

Execute o comando a seguir:

databricks configure --aad-token

O comando emitirá o seguinte prompt:

Databricks Host (should begin with https://):

Insira sua URL para cada workspace, com o formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obter a URL por espaço de trabalho, consulte URL por espaço de trabalho.

Depois de concluir o prompt, suas credenciais de acesso são armazenadas no arquivo ~/.databrickscfg no Linux ou macOS ou %USERPROFILE%\.databrickscfg no Windows. O arquivo contém uma entrada de perfil padrão:

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

Se o arquivo .databrickscfg já existir, o perfil de configuração desse arquivo DEFAULT será substituído com os novos dados. Para criar um perfil de configuração com um nome diferente, confira Perfis de conexão.

Configurar a autenticação usando um token de acesso pessoal do Databricks

Para que a CLI herdada do Databricks use um token de acesso pessoal, execute o seguinte comando:

databricks configure --token

O comando começa com a emissão do prompt:

Databricks Host (should begin with https://):

Insira sua URL para cada workspace, com o formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obter a URL por espaço de trabalho, consulte URL por espaço de trabalho.

O comando continua com a emissão do prompt para inserir seu token de acesso pessoal:

Token:

Depois de concluir os prompts, suas credenciais de acesso são armazenadas no arquivo ~/.databrickscfg no Linux ou macOS ou %USERPROFILE%\.databrickscfg no Windows. O arquivo contém uma entrada de perfil padrão:

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

Se o arquivo .databrickscfg já existir, o perfil de configuração desse arquivo DEFAULT será substituído com os novos dados. Para criar um perfil de configuração com um nome diferente, confira Perfis de conexão.

Na CLI 0.8.1 e superior, é possível alterar o caminho desse arquivo definindo a variável de ambiente DATABRICKS_CONFIG_FILE.

Linux ou macOS
export DATABRICKS_CONFIG_FILE=<path-to-file>
Windows
setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

Importante

A CLI não funciona mais com um arquivo .netrc a partir da versão 0.17.2. Você pode ter um arquivo .netrc no seu ambiente para outras finalidades, mas a CLI não usará esse arquivo .netrc.

A CLI 0.8.0 e superior dá suporte às seguintes variáveis de ambiente Azure Databricks:

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

Uma configuração de variável de ambiente tem precedência sobre a configuração no arquivo de configuração.

Teste a configuração de autenticação

Para verificar se você configurou a autenticação corretamente, você pode executar um comando como o seguinte:

databricks fs ls dbfs:/

Se tiver êxito, esse comando listará os arquivos e diretórios na raiz DBFS do workspace associado ao seu perfil DEFAULT.

Perfis de conexão

A configuração da CLI herdada do Databricks dá suporte a vários perfis de conexão. A mesma instalação da CLI herdada do Databricks pode ser usada para fazer chamadas à API em vários workspaces Azure Databricks.

Para adicionar um perfil de conexão, especifique um nome exclusivo para o perfil:

databricks configure [--token | --aad-token] --profile <profile-name>

O arquivo .databrickscfg contém uma entrada de perfil correspondente:

[<profile-name>]
host = <workspace-URL>
token = <token>

Para usar o perfil de conexão:

databricks <group> <command> --profile <profile-name>

Se --profile <profile-name> não for especificado, o perfil padrão será usado. Se não for encontrado nenhum perfil padrão, será solicitado que você configure a CLI com um perfil padrão.

Teste seus perfis de conexão

Para verificar se você configurou os perfis de conexão corretamente, você pode executar um comando como o seguinte com um dos nomes de perfil de conexão:

databricks fs ls dbfs:/ --profile <profile-name>

Se tiver êxito, esse comando listará os arquivos e diretórios na raiz DBFS do workspace associado ao perfil de conexão especificado. Execute este comando para cada perfil de conexão que você deseja testar.

Para exibir seus perfis disponíveis, consulte o seu arquivo .databrickscfg.

Como usar a CLI

Esta seção mostra como obter ajuda para a CLI herdada do Databricks, analisar a saída dela e invocar comandos em cada grupo de comandos.

Exibir ajuda do grupo de comandos da CLI

Você lista os subcomandos para qualquer grupo de comandos usando a opção --help ou a opção -h. Por exemplo, para listar os subcomandos da CLI do DBFS:

databricks fs -h

Exibir a ajuda do subcomando da CLI

Você lista a ajuda para um subcomando usando a opção --help ou a opção -h . Por exemplo, para listar a ajuda para o subcomando de cópia de arquivos do DBFS:

databricks fs cp -h

Grupos de comandos de alias

Às vezes, pode ser inconveniente prefixar cada invocação da CLI herdada do Databricks com o nome de um grupo de comandos, por exemplo databricks workspace ls na CLI herdada do Databricks. Para facilitar o uso da CLI herdada do Databricks, é possível criar um alias de grupos de comandos para comandos mais curtos. Por exemplo, para encurtar databricks workspace ls para dw ls no Bourne Again Shell, você pode adicionar alias dw="databricks workspace" ao perfil bash apropriado. Normalmente, esse arquivo está localizado em ~/.bash_profile.

Dica

A CLI herdada do Databricks já cria o alias databricks fs para dbfs; databricks fs ls e dbfs ls são equivalentes.

Usar jq para analisar a saída da CLI

Alguns comandos da CLI legada do Databricks produzem a resposta JSON do endpoint da API. Às vezes, pode ser útil analisar partes do JSON para redirecionar em outros comandos. Por exemplo, para copiar uma definição de trabalho, você precisa usar o campo settings de um comando get job e usá-lo como um argumento do comando create job. Nesses casos, recomendamos que você use o utilitário jq.

Por exemplo, o comando a seguir exibe as configurações da tarefa com a ID 233.

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'

Saída:

{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

Como outro exemplo, o comando a seguir imprime os nomes e as IDs de todos os clusters disponíveis no workspace:

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'

Saída:

[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

Você pode instalar jq por exemplo no macOS usando o Homebrew com brew install jq ou em Windows usando o Chocolatey com choco install jq. Para obter mais informações sobre jq, consulte o Manual jq.

Parâmetros de cadeia de caracteres JSON

Os parâmetros de cadeia de caracteres são tratados de maneira diferente, dependendo do seu sistema operacional:

Linux ou macOS

coloque os parâmetros de cadeias de caracteres JSON entre aspas simples. Por exemplo:

'["20180505", "alantest"]'

Windows

Você deve colocar os parâmetros de string JSON entre aspas duplas, e os caracteres de aspas dentro da string devem ser precedidos por \. Por exemplo:

"[\"20180505\", \"alantest\"]"

Solução de problemas

As seções a seguir fornecem dicas para solucionar problemas comuns com a CLI herdada do Databricks.

O uso de EOF com databricks configure não funciona

Para a CLI 0.12.0 do Databricks e versões superiores, o uso da sequência de fim de arquivo (EOF) em um script para passar parâmetros para o comando databricks configure não funciona. Por exemplo, o script a seguir faz com que a CLI do Databricks ignore os parâmetros, e nenhuma mensagem de erro é gerada:

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

Para corrigir esse problema, adote uma das seguintes medidas:

  • Use uma das outras opções de configuração programática, conforme descrito em Configurar a autenticação.
  • Adicione manualmente os valores host e token ao arquivo .databrickscfg, conforme descrito em Configurar a autenticação.
  • Faça downgrade da instalação da CLI do Databricks para a versão 0.11.0 ou versões inferiores. Depois, execute o script novamente.

Comandos de CLI

  • Last updated on