Grupo do 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 grupo de comandos bundle na CLI do Databricks permite que você valide, implante e execute programaticamente os fluxos de trabalho do Azure Databricks, como trabalhosdo Azure Databricks, pipelinesdas Tabelas Dinâmicas Delta e Pilhas do MLOps. 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:

• Modelos de projeto do Pacote de Ativos do Databricks
• Desenvolver um trabalho no Azure Databricks usando Databricks Asset Bundles
• Desenvolver pipelines de Tabelas Dinâmicas Delta com Pacotes de Ativos do Databricks
• Pacotes de Ativos do Databricks para pilhas de MLOps

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 configurável:

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 comando bundle validate gera avisos se as propriedades do recurso forem definidas nos arquivos de configuração do pacote configurável e não forem encontradas 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 workspace

Use o comando bundle sync para fazer a sincronização unidirecional das alterações de arquivo de um pacote em um diretório do sistema de arquivos local para um diretório dentro de 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 databricks sync os comandos e são fornecidos como uma conveniência de produtividade. Para obter informações de uso de comando, consulte sincronizar grupo de comandos.

Gerar um arquivo de configuração de pacote

Você pode usar o bundle generate comando para gerar a configuração de recursos para um trabalho, pipeline ou dashboard que já existe no workspace do Databricks. Esse comando gera um *.yml arquivo para o trabalho, pipeline ou painel na resources pasta do projeto de pacote e também baixa todos os arquivos, como notebooks, referenciados na configuração.

Gerar configuração de trabalho ou pipeline

Importante

O comando bundle generate é fornecido como uma conveniência para gerar automaticamente a configuração de recursos. No entanto, quando essa configuração de trabalho ou pipeline é 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 primeiro. Consulte Recursos do pacote de associação.

Para gerar a configuração de um trabalho ou pipeline, execute o bundle generate comando da seguinte maneira:

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:
    6565621249:
      name: Hello Job
      format: MULTI_TASK
      tasks:
        - task_key: run_notebook
          existing_cluster_id: 0704-xxxxxx-yyyyyyy
          notebook_task:
            notebook_path: ./src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

Gerar configuração do painel

Para gerar a configuração de um painel existente no espaço de trabalho, execute bundle generate, 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 espaço de trabalho para um painel da interface do usuário do espaço de trabalho.

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

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 --force opções e --watch .

Associar recursos de pacote

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

Dica

É uma boa ideia confirmar o workspace do pacote antes de realizar a associação.

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

Por exemplo, 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

Use bundle deployment unbind se quiser remover o vínculo entre o trabalho ou pipeline em um pacote e sua correspondente remoto em um espaço de trabalho.

databricks bundle deployment unbind [resource-key]

Gerar 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

A saída de exemplo a seguir é o resumo de um pacote chamado 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

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 workspaces, como workspaces de desenvolvimento, preparo e produção. Fundamentalmente, a propriedade root_path é o que determina a identidade exclusiva de um pacote, que usa ~/.bundle/${bundle.name}/${bundle.target} como padrão. 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, a implantação de um pacote rastreia os recursos que ele cria no workspace de destino por suas IDs como um estado armazenado no sistema de arquivos do workspace. 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 workspace de destino, ele será atualizado no workspace.
• 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 atualização de pipeline ou execução de trabalho existente, use a opção --restart:

databricks bundle run --restart hello_job

Abrir um recurso de pacote

Para navegar até um recurso de pacote configurável na área de trabalho, execute o bundle open comando a partir da raiz do projeto de pacote configurável, especificando o recurso a ser aberto. Se uma chave de recurso não for especificada, esse comando gerará uma lista dos recursos do pacote configurável para 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

A destruição de um pacote exclui permanentemente os trabalhos, pipelines e artefatos implantados anteriormente de um 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 implantados anteriormente definidos nos arquivos de configuração do pacote:

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ê receberá uma solicitação para 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.