Compartilhar via

Grupo do comandos bundle

  • Artigo

Observação

Essas informações se aplicam às versões 0.218.0 e superiores da CLI do Databricks. Para localizar sua versão da CLI do Databricks, execute databricks -v.

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

Importante

Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks. Para configurar a autenticação para a CLI do Databricks, confira Autenticação para a CLI 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 comando bundle init da seguinte maneira e responda aos prompts na tela:

databricks bundle init

Para criar um Pacote de Ativos do Databricks usando um modelo de Pacote de Ativos do Databricks não padrão, execute o comando bundle init 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 de Ativos do Databricks, execute o comando bundle schema 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.

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 comando bundle generate para gerar a configuração de recursos para um trabalho ou pipeline que já existe no workspace do Databricks. Esse comando gera um arquivo *.yml para o trabalho ou pipeline na pasta resources do projeto de pacote e também baixa todos os notebooks referenciados na configuração de pipeline ou trabalho. Atualmente, somente trabalhos com tarefas de notebook são compatíveis com esse comando.

Importante

O comando bundle generate é fornecido como uma conveniência para gerar automaticamente a configuração de recursos. No entanto, ao incluir essa configuração no pacote e realizar a implantação, ela cria um novo recurso e não atualiza o recurso existente, a menos que bundle deployment bind tenha sido previamente usado no recurso.

Execute o comando bundle generate da seguinte forma:

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

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

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]

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 pacote

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 passar 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

Destruir um pacote

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.