bundle grupo de comando

Nota

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 CLIdo Databricks permite validar, implantar e executar programaticamente fluxos de trabalho do Azure Databricks, como trabalhos do Azure Databricks, pipelines Delta Live Tables e MLOps Stacks. Consulte O que são Databricks Asset Bundles?.

Execute bundle comandos anexando-os ao databricks bundle. Para exibir a ajuda para o bundle comando, execute databricks bundle -h.

Criar um pacote a partir de um modelo de projeto

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

databricks bundle init

Para criar um Databricks Asset Bundle usando um modelo personalizado do Databricks Asset Bundle, 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 Databricks Asset Bundle
• Desenvolver um trabalho no Azure Databricks usando Databricks Asset Bundles
• Desenvolva pipelines Delta Live Tables com pacotes de ativos Databricks
• Pacotes de ativos Databricks para pilhas 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 Databricks Asset Bundle como um arquivo JSON, execute o bundle schema comando e redirecione a saída para um arquivo JSON. Por exemplo, você pode gerar um arquivo nomeado bundle_config_schema.json dentro do 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 bundle estão sintaticamente corretos, execute o bundle validate comando a partir da raiz do projeto bundle, 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!

Nota

O bundle validate comando emite avisos se as propriedades do recurso forem definidas nos arquivos de configuração do pacote que não forem 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

Use o comando para fazer a bundle sync sincronização unidirecional das alterações de arquivo de um pacote em um diretório local do sistema de arquivos para um diretório dentro de um espaço de trabalho remoto do Azure Databricks.

Nota

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

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

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 painel que já existe em seu espaço de trabalho 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 blocos de anotações, referenciados na configuração.

Gerar configuração de trabalho ou pipeline

Importante

O bundle generate comando é 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 pela primeira vez. Consulte Vincular recursos do pacote.

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]

Nota

Atualmente, apenas trabalhos com tarefas de bloco de anotações são suportados por esse comando.

Por exemplo, o comando a seguir gera um novo hello_job.yml arquivo na resources pasta do projeto bundle que contém o YAML abaixo e baixa o simple_notebook.py para a pasta do src projeto.

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 configuração para um painel existente no espaço de trabalho, execute bundle generate, especificando o 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 resources pasta do projeto bundle que contém o YAML abaixo e baixa o 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

Gorjeta

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

Vincular recursos do pacote

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

Gorjeta

É uma boa ideia confirmar o pacote no espaço de trabalho antes de executar o bind.

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

Por exemplo, o comando a seguir vincula o recurso hello_job à sua contraparte remota no espaço de trabalho. O comando gera uma comparação e permite que você negue a vinculação de recursos, mas, se confirmada, todas as atualizações na definição de trabalho no pacote são aplicadas ao trabalho remoto correspondente quando o pacote for implantado na próxima vez.

databricks bundle deployment bind hello_job 6565621249

Use bundle deployment unbind se quiser remover o link entre o trabalho ou pipeline em um pacote e sua contraparte remota em um espaço de trabalho.

databricks bundle deployment unbind [resource-key]

Saída de um resumo do pacote

O bundle summary comando produz 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 espaço de trabalho 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

Gorjeta

Você também pode usar bundle open para navegar até um recurso no espaço de trabalho Databricks. Consulte Abrir um recurso de pacote.

Implantar um pacote

Para implantar um bundle no espaço de trabalho remoto, execute o bundle deploy comando a partir da raiz do projeto bundle. 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 -t opção (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, preparação e produção. Fundamentalmente, a propriedade é o que determina a root_path identidade exclusiva de um pacote, que tem como ~/.bundle/${bundle.name}/${bundle.target}padrão . Portanto, por padrão, a identidade de um pacote é composta pela identidade do implantador, o nome do pacote e o nome de destino do pacote. Se eles forem idênticos em pacotes diferentes, a implantação desses pacotes interferirá uns com os outros.

Além disso, uma implantação de pacote 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 entre uma implantação de pacote e uma instância de recurso, portanto:

• Se um recurso na configuração do pacote não existir no espaço de trabalho de destino, ele será criado.
• Se existir um recurso na configuração do pacote no espaço de trabalho de destino, ele será atualizado no espaço de trabalho.
• Se um recurso for removido da configuração do pacote, ele será removido do espaço de trabalho de destino se tiver sido implantado anteriormente.
• A associação de um recurso com um pacote só pode ser esquecida se você alterar o nome do pacote, o destino do pacote ou o espaço de trabalho. 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 bundle run comando. Você deve especificar a chave de recurso do trabalho ou pipeline declarado nos arquivos de configuração do pacote. Por padrão, o ambiente declarado nos arquivos de configuração do pacote é usado. 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 dentro do contexto de um destino declarado com o nome dev:

databricks bundle run -t dev hello_job

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

databricks bundle run --validate-only my_pipeline

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

databricks bundle run --params message=HelloWorld hello_job

Nota

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

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

databricks bundle run --restart hello_job

Abrir um recurso de pacote

Para navegar até um recurso de pacote no espaço de trabalho, execute o bundle open comando 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 produzirá uma lista dos recursos do pacote 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 bundle no espaço de trabalho Databricks configurado para o bundle:

databricks bundle open baby_gender_by_county

Destrua um pacote

Aviso

A destruição de um pacote exclui permanentemente os trabalhos, pipelines e artefatos implantados anteriormente por um pacote. Esta ação não pode ser anulada.

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

databricks bundle destroy

Nota

A identidade de um pacote é composta pelo nome do pacote, o destino do pacote e o espaço de trabalho. Se você tiver alterado qualquer um deles e, em seguida, 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 --auto-approve opção ao bundle destroy comando.