bundle grupo de comando

Observação

Essas informações se aplicam ao site Databricks CLI versões 0.205 e superiores. A CLI da Databricks está em visualização pública.

Databricks CLI O uso está sujeito à LicençaDatabricks e ao Aviso de PrivacidadeDatabricks , incluindo qualquer provisionamento de Dados de Uso.

O grupo de comando bundle dentro do Databricks CLI permite que o senhor valide, implante e execute de forma programática Databricks fluxos de trabalho como Databricks Job, Delta Live Tables pipeline e MLOps Stacks. Veja o que são Databricks ativo Bundles?

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

Criar um bundle a partir de um projeto padrão

Para criar um Databricks ativo Bundle usando o default Databricks ativo Bundle padrão para Python, execute o comando bundle init da seguinte forma e, em seguida, responda aos avisos na tela:

databricks bundle init

Para criar um Databricks ativo Bundle usando um padrão Databricks ativo Bundle personalizado, execute o comando bundle init da seguinte forma:

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

Veja também:

Exibir o esquema de configuração do pacote

Para exibir o esquema de configuração do Databricks ativo Bundle, execute o comando bundle schema , conforme a seguir:

databricks bundle schema

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

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, como segue:

databricks bundle validate

Em default, 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 comando bundle validate emite avisos se as propriedades do recurso forem definidas nos arquivos de configuração do pacote e não forem encontradas no esquema do objeto correspondente.

Se o senhor quiser gerar apenas um resumo da identidade e do recurso do pacote, use bundle summary.

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

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 em um workspace remoto do Databricks.

Observação

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

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

Gerar um arquivo de configuração do pacote

O senhor pode usar o comando bundle generate para gerar a configuração de recurso para um trabalho, pipelineou painel que já existe em seu site Databricks workspace. Esse comando gera um arquivo *.yml para o Job, pipeline ou painel na pasta resources do projeto do pacote e também downloads quaisquer arquivos, como o Notebook, 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 do recurso. Entretanto, quando essa configuração do Job 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 Bind bundle recurso.

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

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

Observação

Atualmente, apenas o trabalho com a tarefa Notebook é suportado por 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 downloads o simple_notebook.py na 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 dashboard existente no site workspace, execute bundle generate, especificando o ID ou o caminho workspace do dashboard:

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

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

O senhor pode copiar o caminho workspace de um painel na UI workspace.

Por exemplo, o comando a seguir gera um novo arquivo baby_gender_by_county.dashboard.yml na pasta resources do projeto do pacote que contém o YAML abaixo e downloads o arquivo baby_gender_by_county.lvdash.json na pasta src do 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 .lvdash.json depois que o senhor já tiver implantado um painel, use a opção --resource ao executar bundle generate dashboard para gerar esse arquivo para o recurso de painel existente. Para pesquisar e recuperar continuamente as atualizações em um painel, use as opções --force e --watch.

Vincular recurso de pacote

O comando bundle deployment bind permite que o senhor vincule o trabalho e o pipeline definidos pelo pacote ao trabalho e pipeline existentes no Databricks workspace para que eles sejam gerenciados pelo Databricks ativo Bundles. Se o senhor vincular um recurso, os recursos existentes do Databricks no site workspace serão atualizados com base na configuração definida no pacote ao qual ele está vinculado após o próximo bundle deploy.

Dica

É uma boa ideia confirmar o pacote no site workspace 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 site workspace. O comando gera um diff e permite que o senhor negue a vinculação do recurso, mas, se confirmado, todas as atualizações da definição do Job no pacote serão aplicadas ao Job remoto correspondente quando o pacote for implantado novamente.

databricks bundle deployment bind hello_job 6565621249

Use bundle deployment unbind se quiser remover o vínculo entre o Job ou o pipeline em um pacote e sua contraparte remota em um workspace.

databricks bundle deployment unbind [resource-key]

Produzir um resumo do pacote

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

databricks bundle summary

O exemplo de saída a seguir é o resumo de um pacote chamado my_pipeline_bundle que define um Job 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

aprimorar um pacote

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

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 alvo declarado com o nome dev:

databricks bundle deploy -t dev

Um pacote pode ser implantado em vários espaços de trabalho, como o espaço de trabalho de desenvolvimento, de preparação e de produção. Fundamentalmente, a propriedade root_path é o que determina a identidade exclusiva de um pacote, cujo padrão é ~/.bundle/${bundle.name}/${bundle.target}. Portanto, pelo site default, a identidade de um pacote é composta pela identidade do implantador, pelo nome do pacote e pelo nome do destino do pacote. Se eles forem idênticos em diferentes pacotes, a implantação desses pacotes interferirá entre si.

Além disso, uma implantação de pacote rastreia o recurso que cria no destino workspace por seus IDs como um estado que é armazenado no sistema de arquivos workspace. Os nomes de recurso 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 destino workspace, ele será criado.

  • Se um recurso na configuração do pacote existir no destino workspace, ele será atualizado no workspace.

  • Se um recurso for removido da configuração do feixe, ele será removido do alvo workspace se tiver sido implantado anteriormente.

  • A associação de um recurso a um pacote só pode ser esquecida se o senhor alterar o nome do pacote, o destino do pacote ou o endereço workspace. O senhor pode executar bundle validate para gerar um resumo com esses valores.

execução de um pacote

Para executar um Job ou pipeline específico, use o comando bundle run. O senhor deve especificar o recurso key do Job ou pipeline declarado nos arquivos de configuração do pacote. Em default, é usado o ambiente declarado nos arquivos de configuração do pacote. Por exemplo, para executar um Job hello_job no ambiente default, execute o seguinte comando:

databricks bundle run hello_job

Para executar um Job com um key hello_job no contexto de um alvo declarado com o nome dev:

databricks bundle run -t dev hello_job

Se o senhor quiser fazer uma execução de 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 parâmetros separados por vírgula key-value, em que key é o nome do parâmetro. Por exemplo, o comando a seguir define o parâmetro com o nome message como HelloWorld para o Job hello_job:

databricks bundle run --params message=HelloWorld hello_job

Observação

O senhor pode passar parâmetros para o Job tarefa usando as opções do Job tarefa, mas a opção --params é o método recomendado para passar parâmetros do Job. Ocorrerá um erro se os parâmetros de tarefa forem especificados para uma tarefa que não tenha parâmetros de tarefa definidos ou se os parâmetros de tarefa forem especificados para uma tarefa que tenha parâmetros de tarefa definidos.

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

databricks bundle run --restart hello_job

Destruir um pacote

Aviso

A destruição de um pacote exclui permanentemente o trabalho, o pipeline e os artefatos implantados anteriormente no pacote. Essa ação não pode ser desfeita.

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

databricks bundle destroy

Observação

A identidade de um pacote é composta pelo nome do pacote, o destino do pacote e o endereço workspace. Se o senhor tiver alterado algum desses itens e tentar destruir um pacote antes de implantá-lo, ocorrerá um erro.

Por default, você é solicitado a confirmar a exclusão permanente do Job, 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 .