Compartilhar via

Grupo de comandos bundle

Observação

Essas informações se aplicam às versões 0.205 e superiores da CLI do Databricks. A CLI do Databricks está em Visualização Pública.

O uso da CLI do Databricks está sujeito à Licença do Databricks e ao Aviso de Privacidade do Databricks, incluindo quaisquer disposições de Dados de Uso.

O bundle grupo de comandos dentro da CLI do Databricks permite que você valide, implante e execute programaticamente fluxos de trabalho do Azure Databricks, como trabalhos do Azure Databricks, Pipelines Declarativos do Lakeflow e MLOps Stacks. Consulte O que são os Pacotes de Ativos do Databricks?.

Você executa comandos bundle anexando-os a databricks bundle. Para exibir a ajuda para o comando bundle, execute databricks bundle -h.

Criar um pacote com base em um modelo de projeto

Para criar um Pacote de Ativos do Databricks usando o modelo padrão do Pacote de Ativos do Databricks para Python, execute o bundle init comando da seguinte maneira e responda aos prompts na tela:

databricks bundle init

Para criar um Pacote de Ativos do Databricks usando um modelo personalizado do Pacote de Ativos do Databricks, execute o bundle init comando da seguinte maneira:

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

Consulte também:

Exibir o esquema de configuração do pacote

Para exibir o esquema de configuração do pacote, execute o bundle schema comando da seguinte maneira:

databricks bundle schema

Para gerar o esquema de configuração do Pacote de Ativos do Databricks como um arquivo JSON, execute o comando bundle schema e redirecione a saída para um arquivo JSON. Por exemplo, você pode gerar um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:

databricks bundle schema > bundle_config_schema.json

Validar um pacote

Para validar se os arquivos de configuração do pacote estão sintaticamente corretos, execute o comando bundle validate na raiz do projeto do pacote, da seguinte maneira:

databricks bundle validate

Por padrão, esse comando retorna um resumo da identidade do pacote.

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

Observação

O bundle validate comando gera avisos se as propriedades do recurso são definidas nos arquivos de configuração de pacote que não são encontrados no esquema do objeto correspondente.

Se você quiser apenas gerar um resumo da identidade e dos recursos do pacote, use o resumo do pacote.

Sincronizar a árvore de um pacote com um espaço de trabalho

O comando bundle sync executa uma sincronização unidirecional das alterações de arquivo de um pacote em um diretório do sistema de arquivos local para um diretório em um workspace remoto do Azure Databricks.

Observação

Os comandos bundle sync não podem sincronizar alterações de arquivo de um diretório em um workspace remoto do Azure Databricks, de volta para um diretório dentro de um sistema de arquivos local.

Os comandos databricks bundle sync funcionam da mesma forma que os comandos databricks sync e são fornecidos como uma conveniência de produtividade. Para obter informações de uso de comando, consulte osync grupo de comandos.

Gerar um arquivo de configuração de pacote

O bundle generate comando gera configuração para um recurso que já existe no workspace do Databricks. São suportados os seguintes recursos:

Por padrão, esse comando gera um arquivo *.yml do recurso na pasta resources do projeto do pacote e também baixa todos os arquivos, como notebooks, referenciados na configuração.

Importante

O comando bundle generate é fornecido como uma conveniência para gerar automaticamente a configuração de recursos. No entanto, quando a configuração de recursos é incluída no pacote e implantada, ela cria um novo recurso e não atualiza o recurso existente, a menos que bundle deployment bind tenha sido usado pela primeira vez. Confira Vincular um recurso do pacote.

Gerar configuração do aplicativo

Para gerar a configuração de um aplicativo existente no workspace, execute bundle generate app, especificando o nome do aplicativo no workspace:

databricks bundle generate app --existing-app-name [app-name]

Você pode obter o nome do aplicativo na guia Compute>Apps da UI do espaço de trabalho.

Por exemplo, o comando a seguir gera um novo hello_world.app.yml arquivo na pasta de projeto do resources pacote e baixa os arquivos de código do aplicativo, como o arquivo app.yaml de configuração de comando do aplicativo e principal app.py. Por padrão, os arquivos de código são copiados para a pasta do src pacote.

databricks bundle generate app --existing-app-name "hello_world"

# This is the contents of the resulting /resources/hello-world.app.yml file.
resources:
  apps:
    hello_world:
      name: hello-world
      description: A basic starter application.
      source_code_path: ../src/app

Gerar configuração do painel

Para gerar a configuração de um painel existente no espaço de trabalho, execute bundle generate dashboard, especificando a ID ou o caminho do espaço de trabalho para o painel:

databricks bundle generate dashboard --existing-id [dashboard-id]

databricks bundle generate dashboard --existing-path [dashboard-workspace-path]

Você pode copiar o caminho do workspace para um dashboard na interface do usuário do workspace.

Por exemplo, o comando a seguir gera um novo arquivo baby_gender_by_county.dashboard.yml na pasta do projeto resources do pacote, que contém o YAML abaixo, e faz o download do arquivo baby_gender_by_county.lvdash.json para a pasta do projeto src.

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: 'Baby gender by county'
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

Dica

Para atualizar o arquivo depois de já ter implantado .lvdash.json um painel, use a --resource opção ao executar bundle generate dashboard para gerar esse arquivo para o recurso de painel existente. Para sondar e recuperar continuamente as atualizações de um painel, use as opções --force e --watch.

Gerar configuração de tarefa ou pipeline

Para gerar a configuração para um trabalho ou pipeline, execute o comando bundle generate job ou bundle generate pipeline:

databricks bundle generate [job|pipeline] --existing-[job|pipeline]-id [job-id|pipeline-id]

Observação

Atualmente, somente trabalhos com tarefas de notebook são compatíveis com esse comando.

Por exemplo, o comando a seguir gera um novo arquivo hello_job.yml na pasta do projeto do pacote resources contendo o YAML abaixo e faz o download do simple_notebook.py para a pasta do projeto src.

databricks bundle generate job --existing-job-id 6565621249

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    hello_job:
      name: 'Hello Job'
      tasks:
        - task_key: run_notebook
          email_notifications: {}
          notebook_task:
            notebook_path: ../src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

Associar um recurso agrupado

O bundle deployment bind comando permite vincular recursos definidos por pacote a recursos existentes no workspace do Azure Databricks para que eles se tornem gerenciados pelos Pacotes de Ativos do Databricks. Se você associar um recurso, o recurso existente do Azure Databricks no workspace será atualizado com base na configuração definida no pacote ao qual ele está associado após o próximo bundle deploy.

databricks bundle deployment bind [resource-key] [resource-id]

Bind não recria dados. Por exemplo, se um pipeline com dados em um catálogo tiver a vinculação aplicada, você poderá implantar nesse pipeline sem perder os dados existentes. Além disso, você não precisa recomputar a visão materializada, por exemplo, para que os pipelines não precisem ser executados novamente.

O comando bind deve ser usado com a flag --target. Por exemplo, associe sua implantação de produção ao pipeline de produção usando databricks bundle deployment bind --target prod my_pipeline 7668611149d5709ac9-2906-1229-9956-586a9zed8929

Dica

É uma boa ideia confirmar o recurso no workspace antes de executar a associação.

O Bind tem suporte para os seguintes recursos:

O comando a seguir associa o recurso hello_job ao seu equivalente remoto no workspace. O comando mostra as diferenças e permite que você recuse a associação de recursos, mas, se confirmada, todas as atualizações na definição de trabalho no pacote são aplicadas ao trabalho remoto correspondente na próxima vez que o pacote for implantado.

databricks bundle deployment bind hello_job 6565621249

Desassociar um recurso de pacote

Se você quiser remover o link entre o recurso em um pacote e seu equivalente remoto em um workspace, use bundle deployment unbind:

databricks bundle deployment unbind [resource-key]

Por exemplo, para desassociar o recurso hello_job:

databricks bundle deployment unbind hello_job

Mostrar um resumo do pacote

O bundle summary comando gera um resumo da identidade e dos recursos de um pacote, incluindo links profundos para recursos para que você possa navegar facilmente até o recurso no workspace do Databricks.

databricks bundle summary

O exemplo de saída a seguir é o resumo de uma reunião chamada my_pipeline_bundle que define um trabalho e um pipeline:

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

Dica

Você também pode usar bundle open para navegar até um recurso no workspace do Databricks. Consulte Abrir um recurso de pacote.

Implantar um pacote de software

Para implantar um pacote no workspace remoto, execute o comando bundle deploy na raiz do projeto do pacote. Se nenhuma opção de comando for especificada, o destino padrão, conforme declarado nos arquivos de configuração do pacote, será usado.

databricks bundle deploy

Para implantar o pacote em um destino específico, defina a opção -t (ou --target) junto com o nome do destino, conforme declarado nos arquivos de configuração do pacote. Por exemplo, para um destino declarado com o nome dev:

databricks bundle deploy -t dev

Um pacote pode ser implantado em vários espaços de trabalho, como espaços de trabalho de desenvolvimento, homologação e produção. Fundamentalmente, a root_path propriedade é o que determina a identidade exclusiva de um pacote, que usa como padrão ~/.bundle/${bundle.name}/${bundle.target}. Portanto, por padrão, a identidade de um pacote é composta pela identidade do implantador, pelo nome do pacote e pelo nome de destino do pacote. Se forem idênticos em diferentes pacotes, a implantação dos pacotes sofrerá interferência.

Além disso, uma implantação de reunião rastreia os recursos que cria no espaço de trabalho de destino por suas IDs como um estado armazenado no sistema de arquivos do espaço de trabalho. Os nomes de recursos não são usados para correlacionar uma implantação de pacote e uma instância de recurso, portanto:

  • Se um recurso na configuração do pacote não existir no workspace de destino, ele será criado.
  • Se houver um recurso na configuração do pacote no espaço de trabalho de destino, ele será atualizado lá.
  • Se um recurso for removido da configuração do pacote, ele será removido do workspace de destino se ele tiver sido implantado anteriormente.
  • A associação de um recurso a um pacote só poderá ser esquecida se você alterar o nome do pacote, o destino do pacote ou o workspace. Você pode executar bundle validate para gerar um resumo contendo esses valores.

Executar um trabalho ou pipeline

Para executar um trabalho ou pipeline específico, use o comando bundle run. Você deve especificar a chave de recurso do trabalho ou pipeline declarado nos arquivos de configuração do pacote. Por padrão, será usado o ambiente declarado dentro dos arquivos de configuração do pacote. Por exemplo, para executar um trabalho hello_job no ambiente padrão, execute o seguinte comando:

databricks bundle run hello_job

Para executar um trabalho com uma chave hello_job no contexto de um destino declarado com o nome dev:

databricks bundle run -t dev hello_job

Se você quiser fazer uma validação de pipeline, use a opção --validate-only, conforme mostrado no exemplo a seguir:

databricks bundle run --validate-only my_pipeline

Para passar parâmetros de trabalho, use a opção --params, seguida por pares chave-valor separados por vírgulas, em que a chave é o nome do parâmetro. Por exemplo, o comando a seguir define o parâmetro com o nome message como HelloWorld para o trabalho hello_job:

databricks bundle run --params message=HelloWorld hello_job

Observação

Você pode transmitir parâmetros para tarefas de trabalho usando as opções de tarefa de trabalho, mas a opção --params é o método recomendado para passar parâmetros de trabalho. Ocorrerá um erro se os parâmetros de trabalho forem especificados para um trabalho que não tenha parâmetros de trabalho definidos ou se os parâmetros de tarefa forem especificados para um trabalho que tenha parâmetros de trabalho definidos.

Para cancelar e reiniciar uma execução de trabalho existente ou uma atualização de pipeline, use a opção --restart:

databricks bundle run --restart hello_job

Acrescente -- (hífen duplo) após bundle run para executar scripts com as credenciais de autenticação configuradas do pacote. Por exemplo, o comando a seguir gera o diretório de trabalho atual do usuário atual:

databricks bundle run -- python3 -c 'import os; print(os.getcwd())'

As informações de autenticação do bundle são passadas para processos-filhos usando variáveis de ambiente. Consulte a autenticação unificada do cliente do Databricks.

Abrir um recurso de pacote

Para navegar até um recurso de pacote no ambiente de trabalho, execute o comando bundle open a partir da raiz do projeto de pacote, especificando o recurso a ser aberto. Se uma chave de recurso não for especificada, esse comando gerará uma lista dos recursos do pacote a partir do qual escolher.

databricks bundle open [resource-key]

Por exemplo, o comando a seguir inicia um navegador e navega até o painel baby_gender_by_county no pacote no workspace do Databricks configurado para o pacote:

databricks bundle open baby_gender_by_county

Destruir um pacote

Aviso

Destruir um pacote exclui permanentemente os trabalhos, pipelines e artefatos previamente implantados por esse pacote. Essa ação não pode ser desfeita.

Para excluir trabalhos, pipelines e artefatos que foram implantados anteriormente, execute o comando bundle destroy. O comando a seguir exclui todos os trabalhos, pipelines e artefatos que foram implantados anteriormente e que estão definidos nos arquivos de configuração do bundle:

databricks bundle destroy

Observação

A identidade de um pacote é composta pelo nome do pacote, pelo destino do pacote e pelo workspace. Se você tiver alterado qualquer um deles e tentar destruir um pacote antes da implantação, ocorrerá um erro.

Por padrão, você será solicitado a confirmar a exclusão permanente dos trabalhos, pipelines e artefatos implantados anteriormente. Para ignorar esses prompts e executar a exclusão permanente automática, adicione a opção --auto-approve ao comando bundle destroy.