`bundle` 命令组

项目
12/20/2024

注意

此信息适用于 Databricks CLI 版本 0.205 及更高版本。 Databricks CLI 目前处于公共预览版阶段。

Databricks CLI 的使用须遵守 Databricks 许可和 Databricks 隐私声明，包括任何数据使用规定。

使用 Databricks CLI 中的 bundle 命令组，能够以编程方式验证、部署和运行 Azure Databricks 工作流，例如 Azure Databricks 作业、增量实时表管道以及 MLOps Stacks。请参阅什么是 Databricks 资产捆绑包？。

可以通过将 bundle 命令追加到 databricks bundle 中来运行这些命令。若要显示 bundle 命令的帮助，请运行 databricks bundle -h。

从项目模板创建捆绑包

要使用适用于 Python 的默认 Databricks 资产捆绑包模板创建 Databricks 资产捆绑包，请按如下所示运行 bundle init 命令，然后回答屏幕上的提示：

databricks bundle init

要使用自定义 Databricks 资产捆绑模板创建 Databricks 资产捆绑包，请如下所示运行 bundle init 命令：

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

另请参阅：

显示捆绑包配置架构

要显示捆绑包配置架构，请运行 bundle schema 命令，如下所示：

databricks bundle schema

若要将 Databricks 资产捆绑包配置架构输出为 JSON 文件，请运行 bundle schema 命令并将输出重定向到 JSON 文件。例如，可以在当前目录中生成名为 bundle_config_schema.json 的文件，如下所示：

databricks bundle schema > bundle_config_schema.json

验证捆绑包

要验证捆绑包配置文件在语法上是否正确，请从捆绑包项目根目录运行 bundle validate 命令，如下所示：

databricks bundle validate

默认情况下，此命令会返回捆绑包标识的摘要：

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!

注意

如果资源属性是在捆绑配置文件中定义的，而在相应对象的架构中找不到这些文件，则 bundle validate 命令会输出警告。

若只想输出捆绑包标识和资源的摘要，请使用捆绑包摘要。

将捆绑包的树同步到工作区

使用 bundle sync 命令，将本地文件系统目录中捆绑包的文件更改单向同步到远程 Azure Databricks 工作区中的目录。

注意

bundle sync 命令无法将远程 Azure Databricks 工作区内的目录中的文件更改同步回到本地文件系统中的目录。

databricks bundle sync 命令的工作原理与 databricks sync 命令相同，且都用于提高工作效率。若需了解命令用法，请参阅同步命令组。

生成捆绑包配置文件

可以使用 bundle generate 命令为 Databricks 工作区中已存在的作业、管道或仪表板生成资源配置。此命令会在捆绑包项目的 resources 文件夹中为作业、管道或仪表板生成一个 *.yml 文件，还会下载配置中引用的任何文件（如笔记本）。

生成作业或管道配置

重要

bundle generate 命令为方便自动生成资源配置提供。但是，当此作业或管道配置包含在捆绑包中并部署时，它将创建一个新资源，并且不会更新现有资源，除非已首先使用 bundle deployment bind。请参阅绑定捆绑资源。

要为作业或管道生成配置，请运行 bundle generate 命令，如下所示：

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

注意

目前，此命令仅支持包含笔记本任务的作业。

例如，以下命令在包含下列 YAML 的 resources 捆绑包项目文件夹中生成一个新的 hello_job.yml 文件，并将 simple_notebook.py 下载到 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

生成仪表板配置

要为工作区中的现有仪表板生成配置，请运行 bundle generate，并指定仪表板的 ID 或工作区路径：

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

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

可以从工作区 UI 复制仪表板的工作区路径。

例如，以下命令在包含下列 YAML 的 resources 捆绑包项目文件夹中生成一个新的 baby_gender_by_county.dashboard.yml 文件，并将 baby_gender_by_county.lvdash.json 文件下载到 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

提示

要在部署仪表板后更新 .lvdash.json 文件，请在运行 bundle generate dashboard 时使用 --resource 选项，以生成现有仪表板资源的文件。要持续轮询和检索仪表板的更新，请使用 --force 和 --watch 选项。

绑定捆绑资源

使用 bundle deployment bind 命令，可以将捆绑包定义的作业和管道链接到 Azure Databricks 工作区中的现有作业和管道，以便由 Databricks 资产捆绑包管理它们。如果绑定了某个资源，工作区中的现有 Databricks 资源将基于在下一次 bundle deploy 之后绑定的捆绑包所定义的配置进行更新。

提示

在运行绑定之前，最好在工作区中确认捆绑包。

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

例如，以下命令将资源 hello_job 绑定到工作区中的远程对应资源。该命令会输出差异，并允许拒绝资源绑定，但如果确认，捆绑包中对作业定义的任何更新会在下次部署捆绑包时应用于相应的远程作业。

databricks bundle deployment bind hello_job 6565621249

如果要移除捆绑包中作业或管道与其工作区中远程对应项之间的链接，请使用 bundle deployment unbind。

databricks bundle deployment unbind [resource-key]

输出捆绑包摘要

bundle summary 命令输出捆绑包的标识和资源摘要，包括资源的深层链接，以便你可以轻松地导航到 Databricks 工作区中的资源。

databricks bundle summary

以下示例输出是名为 my_pipeline_bundle 的捆绑包的摘要，用于定义作业和管道：

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

提示

还可使用 bundle open 导航到 Databricks 工作区中的资源。请参阅打开捆绑包资源。

部署捆绑包

若要将捆绑包部署到远程工作区，请从捆绑包项目根目录运行 bundle deploy 命令。如果未指定命令选项，会使用捆绑包配置文件中声明的默认目标。

databricks bundle deploy

若要将捆绑包部署到特定目标，请将 -t（或 --target）选项与捆绑包配置文件中声明的目标名称一起设置。例如，对于使用名称dev声明的目标：

databricks bundle deploy -t dev

可将捆绑包部署到多个工作区，例如开发、暂存和生产工作区。从根本上说，root_path 属性决定了捆绑包的唯一标识，它默认为 ~/.bundle/${bundle.name}/${bundle.target}。因此，默认情况下，捆绑包的标识由部署者的标识、捆绑包的名称和捆绑包的目标名称组成。如果这些属性在不同的捆绑包中相同，则这些捆绑包的部署会互相干扰。

此外，捆绑包部署将跟踪通过其 ID 在目标工作区中创建的资源，作为存储在工作区文件系统中的状态。资源名称不用于在捆绑包部署和资源实例之间关联，因此：

如果捆绑包配置中的资源不存在于目标工作区中，则会创建该资源。
如果捆绑包配置中的资源存在于目标工作区中，则会在工作区中更新该资源。
如果资源已从捆绑包配置中删除，则会从目标工作区中删除该资源（如果之前已部署）。
仅当你更改捆绑包名称、捆绑包目标或工作区时，才能忘记资源与捆绑包的关联。可以运行 bundle validate 来输出包含这些值的摘要。

运行作业或管道

若要运行特定的作业或管道，请使用 bundle run 命令。必须指定捆绑包配置文件中声明的作业或管道的资源密钥。默认情况下，将使用捆绑配置文件中声明的环境。例如，若要在默认环境中运行作业 hello_job，请运行以下命令：

databricks bundle run hello_job

若要在用名称 dev 声明的目标的上下文中运行具有密钥 hello_job 的作业：

databricks bundle run -t dev hello_job

如果要执行管道验证运行，请使用 --validate-only 选项，如以下示例所示：

databricks bundle run --validate-only my_pipeline

要传递作业参数，请使用 --params 选项，后跟逗号分隔的键值对，其中键是参数名称。例如，以下命令将作业 hello_job 的名为 message 的参数设置为 HelloWorld：

databricks bundle run --params message=HelloWorld hello_job

注意

可以使用作业任务选项将参数传递给作业任务，但建议使用 --params 选项传递作业参数。如果为未定义作业参数的作业指定了作业参数，或者为已定义作业参数的作业指定了任务参数，则会发生错误。

要取消并重启现有作业运行或管道更新，请使用 --restart 选项：

databricks bundle run --restart hello_job

打开捆绑包资源

要导航到工作区中的捆绑包资源，请从捆绑包项目根目录运行 bundle open 命令，指定要打开的资源。若未指定资源键，此命令将输出要从中选择的捆绑包资源的列表。

databricks bundle open [resource-key]

例如，以下命令启动浏览器并导航到为捆绑包配置的 Databricks 工作区中的捆绑包中的 baby_gender_by_county 仪表板：

databricks bundle open baby_gender_by_county

销毁捆绑包

警告

销毁捆绑包会永久删除捆绑包以前部署的作业、管道和项目。此操作不可撤消。

要删除以前部署的作业、管道和项目，请运行 bundle destroy 命令。以下命令删除捆绑包配置文件中定义的所有以前部署的作业、管道和项目：

databricks bundle destroy

注意

捆绑包的标识由捆绑包名称、捆绑包目标和工作区组成。如果更改了其中任何一项，然后尝试在部署之前销毁捆绑包，将发生错误。

默认情况下，系统会提示你是否确认要永久删除以前部署的作业、管道和项目。若要跳过这些提示并执行自动永久删除，请将 --auto-approve 选项添加到 bundle destroy 命令。

通过

bundle 命令组