CLI do Databricks

A interface de linha de comandos do Databricks (CLI) oferece uma interface fácil de utilizar para a plataforma Azure Databricks. O projeto open source está alojado no GitHub. A CLI tem por base a API REST 2.0 do Databricks e está organizada em grupos de comandos de acordo com a API de Áreas de Trabalho, a API de Clusters, a API de Conjuntos de Instâncias, a API do DBFS, a API de Grupos, a API de Tarefas, a API de Bibliotecas e a API de Segredos: workspace, clusters, instance-pools, fs, groups, jobs, runs, libraries e secrets.

Importante

Esta CLI está em desenvolvimento ativo e é disponibilizada como um cliente experimental, o que significa que as interfaces ainda estão sujeitas a alterações.

Configurar a CLI

Esta secção mostra os requisitos e da CLI e descreve como instalar e configurar o seu ambiente para a executar.

Requisitos

  • Python 3 - 3.6 e posterior

  • Python 2 - 2.7.9 e posterior

    Importante

    No MacOS, a instalação predefinida do Python 2 não implementa o protocolo TLSv1_2 e a execução da CLI com esta instalação do Python resulta em 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

A utilização da CLI do Databricks com contentores de armazenamento ativados por firewall não é suportada. O Databricks recomenda a utilização do Databricks Connect ou az storage.

Instalar a CLI

Execute pip install databricks-cli com a versão adequada de pip da instalação do Python.

Configurar a autenticação

Antes de poder executar os comandos da CLI, tem de configurar a autenticação. Para se autenticar na CLI, pode utilizar um token de acesso pessoal do Databricks ou um token do Azure Active Directory (Azure AD).

Configurar a autenticação com um token do Azure AD

Para configurar a CLI com um token do Azure AD, gere o token do Azure AD e armazene-o na variável de ambiente DATABRICKS_AAD_TOKEN.

export DATABRICKS_AAD_TOKEN=<azure-ad-token>

Execute databricks configure --aad-token. O comando emite a instrução:

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

Introduza o URL por área de trabalho, com o formato adb-<workspace-id>.<random-number>.azuredatabricks.net. Para obter o URL por área de trabalho, veja URL por área de trabalho.

Depois de concluir a instrução, as credenciais de acesso são armazenadas no ficheiro ~/.databrickscfg. O ficheiro deverá conter entradas como:

host = https://<databricks-instance>
token =  <azure-ad-token>

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

Para configurar a CLI de modo a utilizar o token de acesso pessoal, execute databricks configure --token. O comando emite as instruções:

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

Depois de concluir as instruções, as credenciais de acesso são armazenadas no ficheiro ~/.databrickscfg. O ficheiro deverá conter entradas como:

host = https://<databricks-instance>
token =  <personal-access-token>

Na CLI 0.8.1 e posteriores, pode alterar o caminho deste ficheiro ao definir a variável de ambiente DATABRICKS_CONFIG_FILE.

Importante

Uma vez que a CLI tem por base a API REST, a configuração da autenticação no ficheiro .netrc tem precedência sobre a configuração em .databrickscfg.

A CLI 0.8.0 e posterior suporta as seguintes variáveis de ambiente:

  • 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.

Perfis de ligação

A configuração da CLI do Databricks suporta múltiplos perfis de ligação. É possível utilizar a mesma instalação da CLI do Databricks para fazer chamadas à API em várias áreas de trabalho do Azure Databricks.

Para adicionar um perfil de ligação:

databricks configure [--profile <profile>]

Para utilizar o perfil de ligação:

databricks workspace ls --profile <profile>

Aliases de grupos de comandos

Por vezes, pode não ser prático acrescentar prefixos a cada invocação da CLI com o nome de um grupo de comandos, como por exemplo databricks workspace ls. Para facilitar a utilização da CLI, pode criar aliases para os grupos de comandos para encurtar os comandos. Por exemplo, para encurtar databricks workspace ls para dw ls na shell Bourne again, pode adicionar alias dw="databricks workspace" ao perfil de bash adequado. Regra geral, este ficheiro está localizado em ~/.bash_profile.

Dica

O Azure Databricks já encurtou databricks fs para dbfs; databricks fs ls e dbfs ls são equivalentes.

Utilizar a CLI

Esta secção mostra como obter ajuda da CLI, analisar a saída da mesma e invocar comandos em cada grupo de comandos.

Apresentar a ajuda dos grupos de comandos da CLI

Para listar os subcomandos de um grupo de comandos, execute databricks <group> -h. Por exemplo, se quiser listar os subcomandos da CLI do DBFS, execute databricks fs -h.

Utilizar jq para analisar a saída da CLI

Alguns comandos da CLI do Databricks produzem a resposta JSON a partir do ponto final 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, tem de assumir o campo settings de /api/2.0/jobs/get e utilizá-lo como argumento no comando databricks jobs create.

Nesses casos, recomendamos que utilize o utilitário jq. Pode instalar o jq em MacOS mediante a utilização do Homebrew com brew 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:

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

    databricks jobs run-now --job-id 9 --jar-params '["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:

    databricks jobs run-now --job-id 9 --jar-params "[\"20180505\", \"alantest\"]"
    

Comandos da CLI