Partilhar via

Migração da CLI do Databricks

  • Artigo

Este artigo descreve como migrar da CLI do Databricks versão 0.18 ou inferior para a CLI do Databricks versão 0.205 ou superior. As versões 0.205 e superiores da CLI do Databricks estão em Visualização Pública.

Para maior brevidade, este artigo refere-se às versões 0.18 e abaixo da CLI do Databricks como CLI "legada" e às versões 0.205 e superiores da CLI do Databricks como a "nova" CLI.

Para obter mais informações sobre as CLIs herdadas e novas, consulte:

Desinstale a CLI herdada

Se você tiver a CLI herdada instalada e quiser desinstalá-la, use pip (ou pip3, dependendo da sua versão do Python) para executar o uninstall comando, da seguinte maneira:

pip uninstall databricks-cli

Instalar a nova CLI

Para saber como instalar a nova CLI, consulte Instalar ou atualizar a CLI do Databricks.

Verifique a instalação da CLI

Se não tiver a certeza se está a utilizar a nova CLI, siga as instruções nesta secção para verificar e ajustar conforme necessário. Antes de seguir estas instruções, certifique-se de sair de quaisquer ambientes virtuais, conda ambientes ou ambientes semelhantes do Python.

Para verificar a versão da instalação padrão da CLI, execute o seguinte comando:

databricks -v

Se o número da versão não for o esperado, siga um destes procedimentos:

  • Se você quiser usar apenas uma versão da CLI: desinstale todas as versões anteriores da CLI que você não deseja mais usar. Talvez seja necessário atualizar o sistema operacional PATH para que o caminho para a versão restante da CLI que você deseja usar seja listado.
  • Se você quiser continuar usando várias versões da CLI: anexe o caminho completo para a versão da CLI que você deseja usar para cada chamada para a CLI.
  • Se você quiser continuar usando várias versões da CLI, mas não quiser continuar precedendo o caminho completo para a versão da CLI que você usa com mais frequência: certifique-se de que o caminho completo para essa versão esteja listado PATHprimeiro no . Observe que você ainda deve preceder o caminho completo para versões da CLI que não estão listadas primeiro no .PATH

Para atualizar o sistema PATHoperacional , faça o seguinte:

MacOS ou Linux

  1. Liste os caminhos onde databricks está instalado executando um dos seguintes comandos:

    which -a databricks

# Or:
where databricks

  2. Obtenha o caminho para a instalação que você deseja usar sem antecipar o caminho completo para cada chamada para a CLI. Se você não tiver certeza de qual caminho é, execute o caminho completo para cada local, seguido por -v, por exemplo:

    /usr/local/bin/databricks -v

  3. Para colocar o caminho para a instalação que você deseja usar primeiro no , PATHexecute o seguinte comando, substituindo /usr/local/bin pelo caminho que você deseja usar. Não adicione databricks ao final deste caminho. Por exemplo:

    export PATH="/usr/local/bin:$PATH"

  4. Para verificar se o PATH foi definido corretamente para a sessão de terminal atual, execute databricks seguido por -v e verifique o número da versão:

    databricks -v

  5. Para ter a PATH configuração dessa maneira toda vez que você reiniciar o terminal, adicione o comando da etapa 3 ao seu arquivo de inicialização do shell. Por exemplo, para Zshell, esse arquivo normalmente está localizado em ~/.zshrc. Para Bash, esse arquivo normalmente está localizado em ~/.bashrc. Para outros shells, consulte a documentação do seu provedor de shell.

  6. Depois de atualizar o arquivo de inicialização do shell, reinicie o terminal para aplicar o valor atualizado PATH .

Windows

  1. Clique com o botão direito do mouse na instalação que databricks você deseja usar sem antecipar o caminho completo para cada chamada para a CLI.

  2. Clique em Abrir local do arquivo.

  3. Observe o caminho para databricks, por exemplo C:\Windows.

  4. No menu Iniciar, procure variáveis de ambiente.

  5. Clique em Editar variáveis de ambiente para sua conta.

  6. Selecione a variável Path na seção User variables for <username> .

  7. Clique em Editar.

  8. Clique em Novo.

  9. Insira o caminho que você deseja adicionar, sem databricks.exe (como C:\Windows).

  10. Use o botão Mover para cima para mover o caminho que você acabou de adicionar ao início da lista.

  11. Clique em OK.

  12. Para verificar se o PATH foi definido corretamente, abra um novo prompt de comando, execute databricks seguido por -ve verifique o número da versão:

    databricks -v

Usar tipos de autenticação adicionais

A CLI herdada e a nova CLI dão suporte à autenticação de token de acesso pessoal do Azure Databricks. No entanto, o Databricks recomenda que você use outros tipos de autenticação do Azure Databricks, se possível, que apenas a nova CLI suporta.

Se você precisar usar a autenticação de token de acesso pessoal do Azure Databricks, o Databricks recomenda que você use um que esteja associado a uma entidade de serviço em vez de uma conta do Azure Databricks ou usuário do espaço de trabalho. Veja Gerir principais de serviço.

A nova CLI oferece suporte a tokens de ID do Microsoft Entra, além dos tokens de acesso pessoal do Azure Databricks. Esses tokens adicionais são mais seguros, pois normalmente expiram em uma hora, enquanto os tokens de acesso pessoal do Azure Databricks podem ser válidos de um dia até indefinidamente. Isso é especialmente importante se um token for acidentalmente verificado em sistemas de controle de versão que podem ser acessados por outras pessoas. Além disso, a nova CLI pode atualizar automaticamente esses tokens adicionais quando eles expiram, enquanto atualizar os tokens de acesso pessoal do Azure Databricks é um processo manual ou pode ser difícil de automatizar.

Para obter mais informações, consulte Autenticação para a CLI do Databricks.

Grupo de comandos e comparações de comandos

A tabela a seguir lista os grupos de comandos da CLI herdados e seus novos equivalentes de grupo de comandos da CLI. Quando existem diferenças significativas entre CLIs, tabelas adicionais listam comandos ou opções herdadas da CLI e seus novos comandos ou equivalentes de opção da CLI.

Grupos de comando

Grupo de comandos herdado Novo grupo de comandos
cluster-policies cluster-policies. Todos os nomes de comando são os mesmos.
clusters clusters. Todos os nomes de comando são os mesmos.
configure configure. Consulte opções de configuração.
fs fs. Consulte os comandos fs.
groups groups. Consulte os comandos de grupos.
instance-pools instance-pools. Todos os nomes de comando são os mesmos.
jobs jobs. Todos os nomes de comando são os mesmos.
libraries libraries. Todos os nomes de comando são os mesmos, exceto .list O list comando não está mais disponível, use os all-cluster-statuses comandos ou cluster-status em vez disso.
pipelines pipelines. Consulte comandos de pipelines.
repos repos. Todos os nomes de comando são os mesmos.
runs jobs. Consulte Comandos de execução.
secrets secrets. Veja os comandos secretos.
stack Não disponível na nova CLI. O Databricks recomenda que você use o provedor Databricks Terraform.
tokens tokens. Consulte os comandos de tokens.
unity-catalog Vários. Consulte grupos de comandos unity-catalog.
workspace workspace. Consulte os comandos do espaço de trabalho.

configure Opções

Opção herdada Nova opção
-o A CLI herdada usa -o para autenticação OAuth. A nova CLI redefine o propósito -o para especificar se a saída da CLI está no formato texto ou JSON. Não aplicável ao Azure Databricks.
--oauth Não aplicável ao Azure Databricks.
-s ou --scope Não aplicável ao Azure Databricks.
-t ou --token -t ou --token (mesmo)
-f ou --token-file Não disponível na nova CLI.
--host --host (mesmo)
--aad-token Use --host e especifique um token de ID do Microsoft Entra quando solicitado, em vez de um token de acesso pessoal do Azure Databricks.
--insecure Não disponível na nova CLI.
--jobs-api-version Não disponível na nova CLI. A nova CLI usa apenas a API de trabalhos 2.1. Para chamar a API de Trabalhos herdada 2.0, use a CLI herdada e consulte CLI de Trabalhos (legado).
--debug Para depuração e registro em log na nova CLI, consulte Modo de depuração.
--profile --profile (mesmo) ou -p
-h ou --help -h ou --help (mesmo)

fs comandos

Todos os fs comandos na CLI herdada são os mesmos na nova CLI, exceto fs mv a que não está disponível na nova CLI.

Comando herdado Novo comando
fs cat fs cat (mesmo)
fs cp fs cp (mesmo)
fs ls fs ls (mesmo)
fs mkdirs fs mkdir
fs mv Não disponível na nova CLI.
fs rm fs rm (mesmo)

groups comandos

Comando herdado Novo comando
groups add-member groups patch
groups create groups create (mesmo)
groups delete groups delete (mesmo)
groups list groups list (mesmo)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

pipelines comandos

Comando herdado Novo comando
pipelines create pipelines create (mesmo)
pipelines delete pipelines delete (mesmo)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (mesmo)
pipelines list pipelines list-pipeline-events ou pipelines list-pipelines ou pipelines list-updates
pipelines reset pipelines reset (mesmo)
pipelines start pipelines start update
pipelines stop pipelines stop (mesmo)
pipelines update pipelines update (mesmo)

runs comandos

Comando herdado Novo comando
runs cancel jobs cancel-run
runs get jobs get-run
runs get-output jobs get-run-output
runs list jobs list-runs
runs submit jobs submit

secrets comandos

Comando herdado Novo comando
secrets create-scope secrets create-scope (mesmo)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (mesmo)
secrets delete-scope secrets delete-scope (mesmo)
secrets get-acl secrets get-acl (mesmo)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (mesmo)
secrets list-scopes secrets list-scopes (mesmo)
secrets put secrets put-secret
secrets put-acl secrets put-acl (mesmo)
secrets write secrets put-secret
secrets write-acl secrets put-acl

tokens comandos

Comando herdado Novo comando
tokens create tokens create (mesmo)
tokens list tokens list (mesmo)
tokens revoke tokens delete

unity-catalog Grupos de comando

unity-catalog <command> na CLI legada torna-se apenas <command> na nova CLI.

Grupo de comandos herdado Novo grupo de comandos
unity-catalog catalogs catalogs (mesmo, mas soltar unity-catalog)
unity-catalog external-locations external-locations (mesmo, mas soltar unity-catalog)
unity-catalog lineage Não disponível na nova CLI. Consulte Recuperar linhagem usando a API REST de linhagem de dados.
unity-catalog metastores metastores (mesmo, mas soltar unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (mesmo, mas soltar unity-catalog)
unity-catalog recipients recipients (mesmo, mas soltar unity-catalog)
unity-catalog schemas schemas (mesmo, mas soltar unity-catalog)
unity-catalog shares shares (mesmo, mas soltar unity-catalog)
unity-catalog storage-credentials storage-credentials (mesmo, mas soltar unity-catalog)
unity-catalog tables tables (mesmo, mas soltar unity-catalog)

workspace comandos

Comando herdado Novo comando
workspace delete workspace delete (mesmo)
workspace export workspace export (mesmo)
workspace export-dir workspace export
workspace import workspace import (mesmo)
workspace import-dir workspace import
workspace list workspace list (mesmo)
workspace ls workspace list
workspace mkdirs workspace mkdirs (mesmo)
workspace rm workspace delete

Argumentos de padrão e posicionais

A maioria dos novos comandos da CLI tem pelo menos um argumento padrão que não tem uma opção acompanhante. Alguns novos comandos da CLI têm dois ou mais argumentos posicionais que devem ser especificados em uma ordem específica e que não têm opções de acompanhamento. Isso é diferente da CLI herdada, onde a maioria dos comandos exige que as opções sejam especificadas para todos os argumentos. Por exemplo, o comando da nova CLI usa uma ID de clusters get cluster como argumento padrão. No entanto, o comando da clusers get CLI herdada requer que você especifique uma --cluster-id opção junto com a ID do cluster. Por exemplo:

Para a CLI herdada:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

Para a nova CLI:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

Como outro exemplo, o comando da grants get nova CLI usa dois argumentos padrão: o tipo protegível seguido pelo nome completo do protegível. No entanto, o comando da unity-catalog permissions get CLI herdada exige que você especifique uma --<securable-type> opção junto com o nome completo do protegível. Por exemplo:

Para a CLI herdada:

databricks unity-catalog permissions get --schema main.default

Para a nova CLI:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

Modo de depuração

A CLI herdada fornece uma --debug opção para mostrar o rastreamento de pilha completa no erro. Para a nova CLI, a --debug opção não é reconhecida. Em vez disso, use as seguintes opções:

  • Use --log-file <path> para gravar informações de log no arquivo especificado em <path>. Se essa opção não for fornecida, as informações de log serão enviadas para stderr. Especificar --log-file sem especificar --log-level também resulta em nenhuma informação de log sendo gravada no arquivo.
  • Use --log-format <type> para especificar o formato das informações registradas. <type> pode ser text (o padrão, se não especificado) ou json.
  • Use --log-level <format> para especificar o nível de informações registradas. Os valores permitidos são disabled (o padrão, se não especificado), trace, debug, info, warne error.

Para a CLI herdada, o exemplo a seguir mostra o rastreamento de pilha completa no erro:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

Para a nova CLI, o exemplo a seguir registra o rastreamento de pilha completa em um arquivo nomeado new-cli-errors.log no diretório de trabalho atual. O rastreamento de pilha é gravado no arquivo no formato JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

Perguntas comuns

Esta seção lista perguntas comuns sobre a migração do legado para a nova CLI.

O que está acontecendo com a CLI legada?

A CLI herdada ainda está disponível, mas não está recebendo atualizações não críticas. A documentação herdada da CLI reflete isso. A Databricks recomenda que os usuários migrem para a nova CLI o mais rápido possível.

A CLI herdada sempre esteve em um estado Experimental com um aviso de que o Databricks não planeja nenhum novo trabalho de recurso para a CLI herdada e a CLI herdada não é suportada por canais de suporte do Databricks.

Quando a CLI herdada será preterida?

A CLI herdada sempre esteve em um estado Experimental com um aviso de que o Databricks não planeja nenhum novo trabalho de recurso para a CLI herdada e a CLI herdada não é suportada por canais de suporte do Databricks.

O Databricks não estabeleceu uma data ou cronograma para substituir a CLI herdada. No entanto, o Databricks recomenda que os usuários migrem para a nova CLI o mais rápido possível.

Quando a nova CLI será lançada como geralmente disponível (GA)?

Uma data de lançamento ou cronograma para lançar a nova CLI como GA não foi estabelecida. Isso dependerá do feedback que o Databricks receber dos usuários durante a Visualização Pública.

Quais são as principais diferenças entre as CLIs legadas e as novas?

  • A CLI herdada foi lançada como um pacote Python. A nova CLI é lançada como um executável autônomo e não precisa de nenhuma dependência de tempo de execução instalada.
  • A nova CLI tem cobertura completa das APIs REST do Databricks. A CLI herdada não.
  • A nova CLI está disponível como uma visualização pública. A CLI herdada permanece em um estado Experimental.

A nova CLI tem paridade total de recursos com a CLI herdada?

A nova CLI tem cobertura para quase todos os comandos da CLI herdada. No entanto, notavelmente ausente da nova CLI é o stacks grupo de comando na CLI herdada. Além disso, alguns grupos de comandos da CLI herdados, como unity-catalog e runs foram refatorados, em novos grupos de comandos na nova CLI. Para obter orientações sobre migração, consulte as informações fornecidas anteriormente neste artigo.

Como faço para migrar do legado para a nova CLI?

Para obter orientações sobre migração, consulte as informações fornecidas anteriormente neste artigo. Observe que a nova CLI não é um substituto imediato para a CLI herdada e requer alguma configuração para mover da CLI herdada para a nova CLI.

As instalações das CLIs legadas e novas podem existir na mesma máquina?

Sim. As instalações das CLIs herdadas e novas podem existir na mesma máquina, mas devem estar localizadas em diretórios diferentes. Como os executáveis são ambos nomeados databricks, você deve controlar qual executável é executado por padrão configurando o PATH. Se você quiser executar a nova CLI, mas de alguma forma executar acidentalmente a CLI herdada, por padrão, a CLI herdada executará a nova CLI com os mesmos argumentos e mostrará a seguinte mensagem de aviso:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

Como mostrado na mensagem de aviso anterior, você pode definir a DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION variável de ambiente para 1 desabilitar esse comportamento e executar a CLI herdada.

Obter ajuda

Para obter ajuda com a migração da CLI herdada para a nova CLI, consulte os seguintes recursos: