CLI do Databricks (herdada)

  • Artigo

Importante

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

O Databricks recomenda o uso da CLI do Databricks versão 0.205 ou superior em vez da versão herdada 0.18 ou inferior da CLI do Databricks. A CLI do Databricks versão 0.18 ou inferior não tem suporte do Databricks. Para obter informações sobre as versões 0.205 e superiores da CLI do Databricks, confira 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 herdada do Databricks está em um estado Experimental. O Databricks não planeja nenhum trabalho de novo recurso 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 Problemas no repositório do SDK do Databricks para Go no GitHub.

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

Requisitos

  • Python 3 – 3.6 e superior
  • Python 2 – 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 do 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 há suporte para o uso da CLI herdada do Databricks com contêineres de armazenamento habilitados para firewall. 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 da CLI herdada do Databricks, configure a autenticação entre ela e o Azure Databricks. Esta seção descreve como configurar a autenticação para a CLI herdada do Databricks.

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 (antigo 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 do Microsoft Entra ID

Para configurar a CLI do Databricks herdada utilizando um token do Microsoft Entra ID, gere o token do Microsoft Entra ID (antigo 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 por workspace, com o formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obter a URL por workspace, confira URL por workspace.

Após a conclusão do prompt, suas credenciais de acesso são armazenadas no arquivo ~/.databrickscfg no Linux ou no macOS ou no arquivo %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 DEFAULTdo arquivo será substituído pelos 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 por workspace, com o formato https://adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obter a URL por workspace, confira URL por workspace.

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

Token:

Após a conclusão dos prompts, suas credenciais de acesso são armazenadas no arquivo ~/.databrickscfg no Linux ou no macOS ou no arquivo %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 DEFAULTdo arquivo será substituído pelos 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 do 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 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 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.

Testar 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 arquivos de cópia 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 herdada do Databricks geram a resposta JSON do ponto de extremidade 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 comado obter trabalho e usá-lo como um argumento do comando criar trabalho. Nesses casos, recomendamos que você use 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'

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"
  }
]

Por exemplo, você pode instalar o jq no macOS usando o Homebrew com brew install jq ou no 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

coloque os parâmetros de cadeia de caracteres JSON entre aspas duplas e os caracteres de aspas dentro da cadeia de caracteres 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