Databricks CLI (legado)

  • Artigo

Importante

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

O Databricks recomenda que você use a CLI do Databricks versão 0.205 ou superior em vez da CLI do Databricks herdada versão 0.18 ou inferior. A CLI do Databricks versão 0.18 ou inferior não é suportada pelo Databricks. Para obter informações sobre as versões 0.205 e superiores da CLI do Databricks, consulte O que é 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 do Databricks herdada está em um estado Experimental . O Databricks não planeja nenhum novo trabalho de recurso para a CLI do Databricks herdada no momento.

A CLI do Databricks herdada não é suportada pelos canais de suporte do Databricks. Para fornecer comentários, fazer perguntas e relatar problemas, use a guia Problemas na interface de linha de comando para repositório Databricks no GitHub.

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

Requisitos

  • Python 3 - 3.6 e posterior
  • Python 2 - 2.7.9 e posterior

Importante

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

Limitações

Não há suporte para o uso da CLI Databricks herdada com contêineres de armazenamento habilitados para firewall. O Databricks recomenda a utilização do Databricks Connect ou az storage.

Configurar a CLI

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

Instalar ou atualizar a CLI

Esta seção descreve como instalar ou atualizar sua máquina de desenvolvimento para executar a CLI do Databricks herdada.

Instalar a CLI

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

pip install databricks-cli

Atualizar a CLI

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

pip install databricks-cli --upgrade

Para listar a versão da CLI do Databricks herdada 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 do Databricks herdada e o Azure Databricks. Esta seção descreve como configurar a autenticação para a CLI do Databricks herdada.

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

Nota

Como prática recomendada de segurança, quando você se autentica com ferramentas, sistemas, scripts e aplicativos automatizados, o Databricks recomenda que você use tokens de acesso pessoal pertencentes a entidades de serviço em vez de usuários do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Configurar a autenticação usando um token do Microsoft Entra ID (anteriormente Azure Ative Directory)

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

Execute o seguinte comando:

databricks configure --aad-token

O comando emite a instrução:

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

Insira o URL por espaço de trabalho, 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 .databrickscfg arquivo já existir, o perfil de DEFAULT configuração desse arquivo será substituído pelos novos dados. Para criar um perfil de configuração com um nome diferente, consulte Perfis de conexão.

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

Para configurar a CLI do Databricks herdada para usar um token de acesso pessoal, execute o seguinte comando:

databricks configure --token

O comando começa emitindo o prompt:

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

Insira o URL por espaço de trabalho, 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 emitindo o 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 .databrickscfg arquivo já existir, o perfil de DEFAULT configuração desse arquivo será substituído pelos novos dados. Para criar um perfil de configuração com um nome diferente, consulte Perfis de conexão.

Na CLI 0.8.1 e posteriores, pode alterar o caminho deste ficheiro ao definir 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 partir da CLI 0.17.2, a CLI não funciona com um arquivo .netrc. Você pode ter um .netrc arquivo em seu ambiente para outros fins, mas a CLI não usará esse .netrc arquivo.

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

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

As definições de variáveis de ambiente têm precedência sobre as definições no ficheiro de configuração.

Testar 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 for bem-sucedido, este comando lista os arquivos e diretórios na raiz DBFS do espaço de trabalho associado ao seu DEFAULT perfil.

Perfis de conexão

A configuração herdada da CLI do Databricks suporta vários perfis de conexão. A mesma instalação da CLI do Databricks herdada pode ser usada para fazer chamadas de API em vários espaços de trabalho do 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 .databrickscfg arquivo contém uma entrada de perfil correspondente:

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

Para utilizar o perfil de ligação:

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

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

Teste seus perfis de conexão

Para verificar se você configurou algum perfil 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 for bem-sucedido, este comando lista os arquivos e diretórios na raiz DBFS do espaço de trabalho para o perfil de conexão especificado. Execute este comando para cada perfil de conexão que você deseja testar.

Para ver os seus perfis disponíveis, consulte o seu .databrickscfg ficheiro.

Utilizar a CLI

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

Apresentar a ajuda dos grupos de comandos da CLI

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

databricks fs -h

Exibir ajuda do subcomando da CLI

Você lista a ajuda para um subcomando usando a --help opção ou -h . Por exemplo, para listar a ajuda para o subcomando DBFS copy files:

databricks fs cp -h

Grupos de comando de alias

Às vezes, pode ser inconveniente prefixar cada invocação da CLI do Databricks herdada com o nome de um grupo de comandos, por exemplo databricks workspace ls , na CLI do Databricks herdada. Para tornar a CLI do Databricks herdada mais fácil de usar, você pode usar grupos de comandos de alias para comandos mais curtos. Por exemplo, para encurtar databricks workspace ls para dw ls no shell Bourne novamente, você pode adicionar alias dw="databricks workspace" ao perfil bash apropriado. Regra geral, este ficheiro está localizado em ~/.bash_profile.

Gorjeta

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

Use jq para analisar a saída da CLI

Alguns comandos herdados da CLI do Databricks produzem a resposta JSON do ponto de extremidade da API. Em alguns casos, pode ser útil analisar partes do JSON para transmitir para outros comandos. Por exemplo, para copiar uma definição de trabalho, você deve pegar o campo de um comando get job e usá-lo como um argumento para o settings comando create job. Nesses casos, recomendamos que utilize o utilitário jq.

Por exemplo, o comando a seguir imprime as configurações do trabalho com a ID 233.

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

Resultado:

{
  "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 apenas os nomes e IDs de todos os clusters disponíveis no espaço de trabalho:

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

Resultado:

[
  {
    "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 Homebrew com ou no Windows usando Chocolatey com brew install jqchoco install jq. Para obter mais informações sobre o jq, veja o Manual do jq.

Parâmetros da cadeia JSON

Os parâmetros das cadeias são processados de forma diferente consoante o sistema operativo:

Linux ou macos

tem de incluir os parâmetros das cadeias JSON em plicas. Por exemplo:

'["20180505", "alantest"]'

Windows

tem de incluir os parâmetros das cadeias JSON em aspas duplas e os carateres de aspas dentro da cadeia têm de ser precedidos de \. Por exemplo:

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

Resolução de Problemas

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

Usar EOF com databricks configure não funciona

Para Databricks CLI 0.12.0 e superior, usar o fim da sequência de arquivo (EOF) em um script para passar parâmetros para o databricks configure comando 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 é lançada:

# 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, siga um destes procedimentos:

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

Comandos da CLI