Migração da CLI da Databricks

Este artigo descreve como migrar de Databricks CLI versão 0.18 ou abaixo para Databricks CLI versão 0.205 ou acima. Databricks CLI As versões 0.205 e acima estão em Public Preview.

Para fins de brevidade, este artigo se refere a Databricks CLI versões 0.18 e abaixo como o "legado" CLI, e Databricks CLI versões 0.205 e acima como o "novo" CLI.

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

• Databricks CLI (legacy) para a CLI legada.
• O que é a CLI da Databricks? para a nova CLI.

Desinstalar a CLI herdada

Se o senhor tiver o CLI legado instalado e quiser desinstalá-lo, use pip (ou pip3, dependendo da sua versão do Python) para executar o comando uninstall, como segue:

Bash

pip uninstall databricks-cli

Instalar a nova CLI

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

Verifique a instalação da CLI

Se não tiver certeza de que está usando a nova CLI, siga as instruções desta seção para verificar e ajustar conforme necessário. Antes de seguir estas instruções, certifique-se de sair de qualquer ambiente virtual Python, conda ou ambientes semelhantes.

Para verificar a versão de sua instalação do default do CLI, execute o seguinte comando:

Bash

databricks -v

Se o número da versão não for o esperado, faça o seguinte:

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

Para atualizar o PATH do seu sistema operacional, faça o seguinte:

MacOS or Linux

1. Liste os caminhos em que o site databricks está instalado executando um dos comandos a seguir:

   Bash

   which -a databricks
   
   # Or:
   where databricks

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

   Bash

   /usr/local/bin/databricks -v

3. Para colocar o caminho da instalação que deseja usar primeiro no seu PATH, execute o seguinte comando, substituindo /usr/local/bin pelo caminho que deseja usar. Não adicione databricks ao final desse caminho. Por exemplo:

   Bash

   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 de -v e verifique o número da versão:

   Bash

   databricks -v

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

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

Windows

1. Clique com o botão direito do mouse na instalação do databricks que o senhor deseja usar sem anexar o caminho completo a cada chamada à CLI.

2. Clique em Abrir localização do arquivo .

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

4. No menu começar , procure por variável de ambiente .

5. Clique em Edit variável de ambiente para seu account .

6. Selecione a variável Path na seção Variáveis do usuário para <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 endereço PATH foi definido corretamente, abra um novo prompt de comando, execute databricks seguido de -v e verifique o número da versão:

    Bash

    databricks -v

Use tipos de autenticação adicionais

O legado CLI e o novo CLI suportam a autenticação de tokens de acesso pessoal Databricks. No entanto, a Databricks recomenda que o senhor use outros tipos de autenticação da Databricks, se possível, que somente a nova CLI suporta.

Se for necessário usar a autenticação de tokens de acesso pessoal Databricks, a Databricks recomenda que o senhor use um token associado a uma entidade de serviço em vez de um usuário Databricks account ou workspace. Ver entidade de serviço.

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

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

grupo de comando e comparações de comando

A tabela a seguir lista os grupos de comando legados CLI e seus novos equivalentes de grupo de comando CLI. Nos casos em que existem diferenças significativas entre as CLIs, tabelas adicionais listam o comando ou as opções do legado CLI e seus equivalentes no novo comando ou opção CLI.

Grupos de comando

Grupo de comando legado	Novo grupo de comando
cluster-policies	cluster-policies. Todos os nomes de comandos são iguais.
clusters	clusters. Todos os nomes de comandos são iguais.
configure	configure. Veja as opçõesconfigure.
fs	fs. Consulte fs comando.
groups	groups. Consulte groups comando.
instance-pools	instance-pools. Todos os nomes de comandos são iguais.
jobs	jobs. Todos os nomes de comandos são iguais.
libraries	libraries. Todos os nomes de comandos são os mesmos, exceto list. O comando list não está mais disponível; em vez disso, use o comando all-cluster-statuses ou cluster-status.
pipelines	pipelines. Consulte pipelines comando.
repos	repos. Todos os nomes de comandos são iguais.
runs	jobs. Consulte runs comando.
secrets	secrets. Consulte secrets comando.
stack	Não está disponível na nova CLI. A Databricks recomenda que, em vez disso, o senhor use o provedor Databricks Terraform.
tokens	tokens. Consulte tokens comando.
unity-catalog	Diversos. Consulte unity-catalog grupos de comando.
workspace	workspace. Consulte workspace comando.

Opçõesconfigure

Opção legada	Nova opção
-o	A CLI herdada usa -o para autenticação OAuth. Para saber mais sobre o OAuth na nova CLI, consulte Autenticação OAuth máquina a máquina (M2M) ou Autenticação OAuth usuário a máquina (U2M). A nova CLI reaproveita o endereço -o para especificar se a saída da CLI está no formato de texto ou JSON.
--oauth	Para saber mais sobre o OAuth na nova CLI, consulte Autenticação OAuth máquina a máquina (M2M) ou Autenticação OAuth usuário a máquina (U2M).
-s ou --scope	Para saber mais sobre o OAuth na nova CLI, consulte Autenticação OAuth máquina a máquina (M2M) ou Autenticação OAuth usuário a máquina (U2M).
-t ou --token	-t ou --token (mesmo)
-f ou --token-file	Não está disponível na nova CLI.
--host	--host (mesmo)
--aad-token	Use --host e especifique um Microsoft Entra ID tokens quando solicitado, em vez de um Databricks personal access tokens.
--insecure	Não está disponível na nova CLI.
--jobs-api-version	Não está disponível na nova CLI. A nova CLI usa apenas a API 2.1 do Jobs. Para chamar a API 2.0 de Jobs herdada, use a CLI herdada e consulte CLI da Databricks (herdada).
--debug	Para depuração e registro na nova CLI, consulte Modo de depuração.
--profile	--profile (mesmo) ou -p
-h ou --help	-h ou --help (mesmo)

fs comando

Todos os fs comandos no legado CLI são os mesmos no novo CLI, exceto fs mv que não está disponível no novo CLI.

Comando Legacy	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 está disponível na nova CLI.
fs rm	fs rm (mesmo)

groups comando

Comando Legacy	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 comando

Comando Legacy	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 comando

Comando Legacy	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 comando

Comando Legacy	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 comando

Comando Legacy	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 antiga se torna apenas <command> na nova CLI.

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

workspace comando

Comando Legacy	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 padrão e posicionais

A maioria dos novos CLI comando tem pelo menos um argumento default que não tem uma opção de acompanhamento. Alguns dos novos CLI comandos 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 do legado CLI, em que a maioria dos comandos exige que as opções sejam especificadas para todos os argumentos. Por exemplo, o novo comando CLI's clusters get usa um ID de clustering como argumento default. No entanto, o comando clusers get do CLIlegado exige que o senhor especifique uma opção --cluster-id junto com o ID do clustering. Por exemplo:

Para a CLI herdada:

Bash

# 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:

Bash

# 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 novo comando CLI's grants get recebe dois argumentos default: o tipo de securizável seguido do nome completo do securizável. No entanto, o comando unity-catalog permissions get da CLI herdada exige que o senhor especifique uma opção --<securable-type> juntamente com o nome completo do securizável. Por exemplo:

Para a CLI herdada:

Bash

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

Para a nova CLI:

Bash

# 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 legada fornece uma opção --debug para mostrar o rastreamento completo da pilha em caso de erro. Na nova CLI, a opção --debug não é reconhecida. Em vez disso, use as seguintes opções:

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

Para a CLI herdada, o exemplo a seguir mostra o rastreamento completo da pilha em caso de erro:

Bash

databricks fs ls / --debug

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

Para o novo CLI, o exemplo a seguir logs o rastreamento completo da pilha em um arquivo chamado new-cli-errors.log no diretório de trabalho atual. O rastreamento de pilha é gravado no arquivo no formato JSON:

Bash

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 da CLI antiga para a nova.

O que está acontecendo com a CLI herdada?

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

O legado CLI sempre esteve em um estado Experimental com um aviso de que Databricks não planeja nenhum novo trabalho de recurso para o legado CLI, e o legado CLI não é suportado pelo canal de suporte Databricks.

Quando a CLI legada será descontinuada?

O legado CLI sempre esteve em um estado Experimental com um aviso de que Databricks não planeja nenhum novo trabalho de recurso para o legado CLI, e o legado CLI não é suportado pelo canal de suporte Databricks.

A Databricks não estabeleceu uma data ou cronograma para a descontinuação da CLI herdada. No entanto, a 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 disponível de forma geral (GA)?

Não foi estabelecida uma data de lançamento ou um cronograma para o lançamento da nova CLI como GA. Isso dependerá do feedback que a Databricks receber dos usuários durante a visualização pública.

Quais são as diferenças key entre a CLI antiga e a nova?

• A CLI legada 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 da Databricks. A CLI herdada não faz isso.
• A nova CLI está disponível como uma visualização pública. A CLI legada permanece em um estado Experimental.

O novo CLI tem paridade total de recurso com o legado CLI?

O novo CLI tem cobertura para quase todo o comando do legado CLI. No entanto, notavelmente ausente do novo CLI está o grupo de comando stacks no legado CLI. Além disso, alguns grupos de comando legados do CLI, como unity-catalog e runs, foram refatorados em novos grupos de comando no novo CLI. Para obter orientações sobre migração, consulte as informações fornecidas anteriormente neste artigo.

Como faço para migrar da CLI antiga para a nova?

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 da CLI antiga e requer alguma configuração para passar da CLI antiga para a nova.

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

Sim. As instalações das CLIs antigas e novas podem existir na mesma máquina, mas devem estar localizadas em diretórios diferentes. Como os executáveis são ambos denominados databricks, o senhor deve controlar qual executável é executado por default configurando o PATH da sua máquina. CLI CLI Se default o senhor quiser executar o novo, mas, de alguma forma, acidentalmente executar o legado,CLI o legado executará o novo 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>

Conforme mostrado na mensagem de aviso anterior, o senhor pode definir a variável de ambiente DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION como 1 para desativar esse comportamento e, em vez disso, executar o site legado CLI.

Obtenha ajuda

Para obter ajuda na migração do site legado CLI para o novo CLI, consulte o recurso a seguir:

• Central de ajuda do Databricks

• Horário comercial do Databricks

• Suporte do Databricks