`bundle` 命令组

2025-05-19

注意

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

Databricks CLI 使用受 Databricks 许可证和 Databricks 隐私声明的约束，包括任何使用情况数据预配。

使用 bundleDatabricks CLI 中的命令组，可以编程方式验证、部署和运行 Azure Databricks 工作流，例如 Azure Databricks 作业、DLT 管道和 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 命令相同，且都用于提高工作效率。有关命令使用情况信息，请参阅 sync 命令组。

生成捆绑包配置文件

该 bundle generate 命令为 Databricks 工作区中已存在的资源生成配置。支持以下资源：

默认情况下，此命令在捆绑项目的*.yml文件夹中为资源生成resources文件，并下载配置中引用的任何文件，例如笔记本。

重要

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

生成应用配置

若要为工作区中的现有应用生成配置，请运行 bundle generate app，并在工作区中指定应用的名称：

databricks bundle generate app --existing-app-name [app-name]

可以从工作区 UI 的 “计算>应用 ”选项卡获取应用名称。

例如，以下命令在hello_world.app.yml捆绑项目文件夹中生成一个新resources文件，并下载应用的代码文件，例如应用的命令配置文件和主app.yaml文件app.py。默认情况下，代码文件将复制到捆绑包的文件夹 src 。

databricks bundle generate app --existing-app-name "hello_world"

# This is the contents of the resulting /resources/hello-world.app.yml file.
resources:
  apps:
    hello_world:
      name: hello-world
      description: A basic starter application.
      source_code_path: ../src/app

生成仪表板配置

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

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

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

可以从工作区用户界面复制仪表板的工作区路径。

例如，以下命令在baby_gender_by_county.dashboard.yml捆绑项目文件夹中生成包含以下 YAML 的新resources文件，并将该文件下载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文件，请在运行--resource生成该文件以用于现有仪表板资源时使用bundle generate dashboard选项。若要持续轮询和检索对仪表板的更新，请使用 --force 和 --watch 选项。

生成作业或管道配置

若要为作业或管道生成配置，请运行 bundle generate job 或 bundle generate pipeline 命令：

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

注意

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

例如，以下命令在包含下列 YAML 的 hello_job.yml 捆绑包项目文件夹中生成一个新的 resources 文件，并将 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 deployment bind 此命令可将捆绑定义的资源链接到 Azure Databricks 工作区中的现有资源，以便它们由 Databricks 资产捆绑包管理。如果绑定某个资源，则现有工作区中的 Azure Databricks 资源会在下一个 bundle deploy之后，根据捆绑包中定义的配置进行更新。

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

绑定不会重新创建数据。例如，如果目录中具有数据的管道已应用绑定，则可以部署到该管道，而不会丢失现有数据。此外，例如，无需重新计算物化视图，管道因此不必重新运行。

绑定命令应与--target标记一起使用。例如，使用 databricks bundle deployment bind --target prod my_pipeline 7668611149d5709ac9-2906-1229-9956-586a9zed8929 将生产部署绑定到生产管道

提示

在运行绑定之前，最好先确认工作区中的资源。

以下资源支持绑定：

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

databricks bundle deployment bind hello_job 6565621249

解除绑定资源包

如果要删除捆绑包中的资源与其工作区中远程对应项之间的链接，请使用 bundle deployment unbind：

databricks bundle deployment unbind [resource-key]

例如，若要取消绑定 ID 为 hello_job 的 6565621249 资源：

databricks bundle deployment unbind 6565621249

输出捆绑包摘要

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

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

databricks bundle run -t dev hello_job

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

databricks bundle run --validate-only my_pipeline

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

databricks bundle run --params message=HelloWorld hello_job

注意

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

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

databricks bundle run --restart hello_job

在--后追加bundle run（双连字符）以使用捆绑包配置的身份验证凭据执行脚本。例如，以下命令输出当前用户的当前工作目录：

databricks bundle run -- python3 -c 'import os; print(os.getcwd())'

捆绑身份验证信息使用环境变量传递到子进程。请参阅 Databricks 客户端统一身份验证。

打开捆绑资源

若要导航到工作区中的捆绑资源，请从捆绑项目根目录运行 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 命令组