bundle 命令组

注意

此信息适用于 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>"

另请参阅：

• Databricks 资产捆绑包项目模板
• 使用 Databricks 资产捆绑包在 Azure Databricks 上开发作业
• 使用 Databricks 资产捆绑包开发增量实时表管道
• 适用于 MLOps Stacks 的 Databricks 资产捆绑包

显示捆绑包配置架构

若要显示捆绑配置架构，请 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 复制仪表板的工作区路径。

例如，以下命令在resources捆绑项目文件夹中生成包含以下 YAML 的新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 命令。