Databricks 资产捆绑包配置

项目
04/15/2024

重要

此功能目前以公共预览版提供。

本文介绍用于定义 Databricks 资产捆绑包的 Databricks 资产捆绑包配置文件的语法。请参阅什么是 Databricks 资产捆绑包？

捆绑包配置文件必须以 YAML 格式表示，并且必须至少包含顶级捆绑包映射。每个捆绑包必须至少包含一个（且只包含一个）名为 databricks.yml 的捆绑包配置文件。如果有多个捆绑配置文件，则它们必须由 databricks.yml 文件引用。

有关 YAML 的详细信息，请参阅官方 YAML 规范和教程。

要创建和使用捆绑包配置文件，请参阅 Databricks 资产捆绑包开发工作流。

概述
示例
映射
自定义变量
Git 设置
替换

概述

本部分提供捆绑包配置文件架构的视觉表示形式。有关详细信息，请参阅映射。

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  compute_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    compute_id: string
    default: true | false
    mode: development
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

示例

下面是一个捆绑包配置文件示例。此捆绑包指定了名为 hello.py 的本地文件的远程部署，它与这个名为 databricks.yml 的本地捆绑包配置文件位于同一目录。它使用具有指定群集 ID 的远程群集将此笔记本作为作业运行。远程工作区 URL 和工作区身份验证凭据是从名为 DEFAULT 的调用方本地配置文件中读取的。

注意

Databricks 建议尽可能使用 host 映射而不是 default 映射，因为这样可以提高捆绑包配置文件的可移植性。设置 host 映射会指示 Databricks CLI 在 .databrickscfg 文件中查找匹配的配置文件，然后使用该配置文件的字段来确定要使用的 Databricks 身份验证类型。如果 .databrickscfg 文件中存在多个具有匹配 host 字段的配置文件，则必须使用 profile 指示 Databricks CLI 要使用哪个特定配置文件。有关示例，请参阅本节后面的 prod 目标声明。

使用这种方法可以重用以及替代 resources 块中的作业定义和设置：

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

虽然以下捆绑包配置文件在功能上等效，但它未模块化，因此不能方便地重用。此外，此声明将一个任务追加到作业，而不是替代现有作业：

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

以下示例将上一示例模块化，但添加了一个具有编程（或逻辑）名称 prod 的目标，该目标使用不同的远程工作区 URL 和工作区身份验证凭据，这些值是从与包含指定工作区 URL 的 host 条目匹配的调用方 .databrickscfg 文件中读取的。此作业运行相同的笔记本，但使用具有指定群集 ID 的不同远程群集。请注意，不需要在 prod 映射中声明 notebook_task 映射，因为如果未显式替代 prod 映射中的 notebook_task 映射，它会回退为使用顶级 resources 映射中的 notebook_task 映射。

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

若要在 dev 目标中验证、部署和运行此作业，请运行以下命令：

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

若要该为在 prod 目标中验证、部署和运行此作业，请运行以下命令：

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

以下示例将上一示例拆分为多个组件文件，以进一步模块化和更好地在多个捆绑包配置文件中重用定义和设置。使用这种方法不仅可以重用各种定义和设置，还能将其中的任何文件交换为可提供完全不同声明的其他文件：

databricks.yml：

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml：

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml：

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

有关更多示例，请参阅 GitHub 中的捆绑包示例存储库。

映射

以下部分按顶级映射介绍了捆绑包配置文件语法。

bundle
variables
工作区
权限
项目
包括
resources
同步
目标

捆绑包

捆绑包配置文件只能包含一个顶级 bundle 映射，该映射关联捆绑包的内容和 Azure Databricks 工作区设置。

此 bundle 映射必须包含一个用于指定捆绑包的编程（或逻辑）名称的 name 映射。以下示例使用编程（或逻辑）名称 hello-bundle 声明一个捆绑包。

bundle:
  name: hello-bundle

bundle 映射可以拥有一个子 compute_id 映射。通过此映射，可以指定要替代在捆绑包配置文件中其他位置定义的任何和所有群集的群集的 ID。此替代适用于生产前的仅开发方案。映射 compute_id 仅适用于其 mode 映射设置为 development 的目标。有关 compute_id 映射的详细信息，请参阅目标映射。

捆绑包配置文件还可以包含顶级 git 映射。

bundle 映射还可以是顶级目标映射中一个或多个目标的子级。其中的每个子 bundle 映射在目标级别指定任何非默认替代。但是，不能在目标级别替代顶级 bundle 映射的 name 值。

variables

捆绑包设置文件可以包含一个顶级 variables 映射，用于指定要使用的变量设置。请参阅自定义变量。

工作区

捆绑包配置文件只能包含一个顶级 workspace 映射，该映射指定要使用的任何非默认 Azure Databricks 工作区设置。

此 workspace 映射可以包含 root_path 映射，以指定要在工作区中用于部署和工作流运行的非默认根目录路径，例如：

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

默认情况下，对于 root_path，Databricks CLI 使用 /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target} 的默认路径，该路径使用替换。

此 workspace 映射也可以包含 artifact_path 映射，以指定要在工作区中用于部署和工作流运行的非默认项目路径，例如：

workspace:
  artifact_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

默认情况下，对于 artifact_path，Databricks CLI 使用 ${workspace.root}/artifacts 的默认路径，该路径使用替换。

注意

artifact_path 映射不支持 Databricks 文件系统 (DBFS) 路径。

此 workspace 映射也可以包含 file_path 映射，以指定要在工作区中用于部署和工作流运行的非默认文件路径，例如：

workspace:
  file_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

默认情况下，对于 file_path，Databricks CLI 使用 ${workspace.root}/files 的默认路径，该路径使用替换。

state_path 映射默认为 ${workspace.root}/state 的默认路径，表示工作区中用于存储有关部署的 Terraform 状态信息的路径。

workspace 映射还可以包含以下可选映射，以指定要使用的 Azure Databricks 身份验证机制。如果未在此 workspace 映射中指定这些可选映射，必须在 workspace 映射中将其指定为顶级目标映射中一个或多个目标的子级。

重要

对于 Azure Databricks 身份验证，必须对以下 workspace 映射的值进行硬编码。例如，无法使用 ${var.*} 语法为这些映射的值指定自定义变量。

profile 映射（或使用 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）指定与此工作区一起用于 Azure Databricks 身份验证的配置文件的名称。此配置文件映射到在设置 Databricks CLI 时创建的配置文件。

注意

Databricks 建议使用 host 映射（或使用 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）代替 profile 映射，因为这样可以使捆绑包配置文件更易于移植。设置 host 映射会指示 Databricks CLI 在 .databrickscfg 文件中查找匹配的配置文件，然后使用该配置文件的字段来确定要使用的 Databricks 身份验证类型。如果 .databrickscfg 文件中存在多个具有匹配 host 字段的配置文件，则必须使用 profile 映射（或 --profile 或 -p 命令行选项）指示 Databricks CLI 要使用哪个配置文件。有关示例，请参阅示例中的 prod 目标声明。
host 映射指定 Azure Databricks 工作区的 URL。请参阅每工作区 URL。
对于 Azure CLI 身份验证，将使用映射 azure_workspace_resource_id。也可以在本地环境变量 DATABRICKS_AZURE_RESOURCE_ID 中设置此值。或者，可以使用 azure_workspace_resource_id 值创建配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。请参阅 Azure CLI 身份验证。
对于使用服务主体的 Azure 客户端机密身份验证，将使用映射 azure_workspace_resource_id、azure_tenant_id 和 azure_client_id。也可以分别在局部环境变量 DATABRICKS_AZURE_RESOURCE_ID、ARM_TENANT_ID 和 ARM_CLIENT_ID 中设置这些值。或者，可以使用 azure_workspace_resource_id、azure_tenant_id 和 azure_client_id 值创建配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。请参阅 Microsoft Entra ID 服务主体身份验证。

注意

不能在捆绑包配置文件中指定 Azure 客户端密码值。应该设置本地环境变量 ARM_CLIENT_SECRET。或者，可以将 azure_client_secret 值添加到配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。
对于 Azure 托管标识身份验证，将使用映射 azure_use_msi、azure_client_id 和 azure_workspace_resource_id。也可以分别在局部环境变量 ARM_USE_MSI、ARM_CLIENT_ID 和 DATABRICKS_AZURE_RESOURCE_ID 中设置这些值。或者，可以使用 azure_use_msi、azure_client_id 和 azure_workspace_resource_id 值创建配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。请参阅 Azure 托管标识身份验证。
azure_environment 映射为一组特定的 API 终结点指定 Azure 环境类型（例如 Public、UsGov、China 和 Germany）。默认值为 PUBLIC。也可以在本地环境变量 ARM_ENVIRONMENT 中设置此值。或者，可以将 azure_environment 值添加到配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。
azure_login_app_id 映射不可操作，保留供内部使用。
auth_type 映射指定要使用的 Azure Databricks 身份验证类型，尤其是在 Databricks CLI 推断出意外身份验证类型的情况下。请参阅身份验证类型字段。

权限

顶级 permissions 映射指定要应用于捆绑包中定义的所有资源的一个或多个权限级别。如果要将权限应用于特定资源，请参阅定义特定资源的权限。

允许的顶级权限级别是 CAN_VIEW、CAN_MANAGE 和 CAN_RUN。

捆绑包配置文件中的以下示例定义用户、组和服务主体的权限级别，这些权限级别应用于捆绑包中 resources 定义的所有作业、管道、试验和模型：

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

项目

顶级 artifacts 映射指定在捆绑包部署期间自动生成的一个或多个项目，这些项目稍后可在捆绑包运行中使用。每个子项目都支持以下映射：

需要 type。若要在部署之前生成 Python wheel 文件，必须将此映射设置为 whl。
path 是从捆绑包配置文件位置到 Python wheel 文件的 setup.py 文件位置的可选相对路径。如果未包含 path，Databricks CLI 将尝试在捆绑包的根目录中查找 Python wheel 文件的 setup.py 文件。
files 是可选映射，包含 source 子映射，可用于指定要包含在复杂生成指令中的非默认位置。这些位置被指定为捆绑包配置文件所在位置的相对路径。
build 是部署前要在本地运行的一组可选非默认生成命令。对于 Python wheel 生成，Databricks CLI 假定它可以找到 Python wheel 包的本地安装来运行生成，并且在每个捆绑包部署期间默认运行命令 python setup.py bdist_wheel。要指定多个构建命令，请使用双与号 (&&) 字符分隔每个命令。

有关详细信息，包括使用 artifacts 的示例捆绑包，请参阅使用 Databricks 资产捆绑包开发 Python wheel 文件。

提示

可以使用在 Databricks 资源包中动态定义项目设置中描述的技术来定义、组合和覆盖捆绑包中项目的设置。

包括

include 数组指定路径 glob 列表，其中包含要放入捆绑包中的配置文件。这些路径 glob 是相对于以下位置的值：指定了路径 glob 的捆绑包配置文件所在的位置。

Databricks CLI 捆绑包中不包含任何配置文件。必须使用 include 数组来指定要包含在捆绑包中的任何及所有配置文件（除了 databricks.yml 文件本身）。

此 include 数组只能显示为顶级映射。

捆绑包配置文件中的以下示例包括三个指定的配置文件。这些文件与捆绑包配置文件位于同一目录：

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

捆绑包配置文件中的以下示例包括文件名以 bundle 开头并以 .yml 结尾的所有文件。这些文件与捆绑包配置文件位于同一目录：

include:
  - "bundle*.yml"

资源

resources 映射指定了捆绑包使用的 Azure Databricks 资源的相关信息。

此 resources 映射可以显示为顶级映射，也可以是顶级目标映射中一个或多个目标的子级，并且包括零个或一个受支持的资源类型。每个资源类型映射都包含一个或多个单独的资源声明，其中每个声明必须具有唯一的名称。这些单独的资源声明使用创建操作的请求有效负载（以 YAML 表示）来定义资源。 Databricks REST API 参考中记录了创建操作请求有效负载。

下表列出了捆绑包支持的资源类型，以及指向有关相应有效负载的文档的链接：

资源类型	资源映射
`jobs`	作业映射：POST /api/2.1/jobs/create 有关详细信息，请参阅作业任务类型和替代新的作业群集设置。
`pipelines`	管道映射：POST /api/2.0/pipelines
`experiments`	试验映射：POST /api/2.0/mlflow/experiments/create
`models`	模型映射：POST /api/2.0/mlflow/registered-models/create
`model_serving_endpoints`	模型服务终结点映射：POST /api/2.0/serving-endpoints
`registered_models` (Unity Catalog)	Unity Catalog 模型映射：POST /api/2.1/unity-catalog/models

资源声明引用的文件夹和文件的所有路径都相对于指定这些路径的捆绑配置文件的位置。

以下示例声明了一个资源键为 hello-job 的作业和一个资源键为 hello-pipeline 的管道：

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

同步

sync 数组指定要包含在捆绑包部署中或从捆绑包部署中排除的文件或路径 glob 的列表，具体取决于以下规则：

根据捆绑包根目录的 .gitignore 文件中的任何文件和路径 glob 列表，include 映射可以包含相对于捆绑包根目录的文件 glob 和/或路径 glob 的列表，以便显式包含。
根据捆绑包根目录的 .gitignore 文件中的任何文件和路径 glob 列表，以及 include 映射中文件和路径 glob 的列表，exclude 映射可以包含相对于捆绑包根目录的文件 glob 和/或路径 glob 的列表，以便显式排除。

指定的文件夹和文件的所有路径都是相对于以下位置的路径：指定了这些路径的捆绑包配置文件的位置。

include 和 exclude 文件和路径模式的语法遵循标准 .gitignore 模式语法。请参阅 gitignore 模式格式。

例如，如果以下 .gitignore 文件包含以下条目：

.databricks
my_package/dist

捆绑包配置文件包含以下 include 映射：

sync:
  include:
    - my_package/dist/*.whl

那么，my_package/dist 文件夹中文件扩展名为 *.whl 的所有文件将包含在内。 my_package/dist 文件夹中的任何其他文件不会包含在内。

但是，如果捆绑包配置文件还包含以下 exclude 映射：

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

那么，my_package/dist 文件夹中文件扩展名为 *.whl 的所有文件（名称为 delete-me.whl 的文件除外）将包含在内。 my_package/dist 文件夹中的任何其他文件也不会包含在内。

还可以在特定目标的 targets 映射中声明 sync 数组。目标中声明的任何 sync 数组将与任何顶级 sync 数组声明合并。例如，在前面的示例中，targets 级别的以下 include 映射将与顶级 sync 数组的 include 映射合并：

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

运行 databricks bundle validate 时，生成的图形的相关部分如下所示：

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

目标

targets 映射指定运行 Azure Databricks 工作流的一个或多个上下文。每个目标是项目、Azure Databricks 工作区设置和 Azure Databricks 作业或管道详细信息的唯一集合。

此 targets 映射是可选的，但强烈建议使用。如果指定它，它只能显示为顶级映射。如果未指定 targets 映射，则始终会使用顶级 workspace、artifacts 和 resources 映射中的设置。

targets 映射由一个或多个目标映射组成，每个目标映射必须具有唯一的编程（或逻辑）名称。

如果目标映射未指定 workspace、artifacts 或 resources 子映射，则该目标将使用顶级 workspace、artifacts 和 resources 映射中的设置。

如果目标映射指定了 workspace、artifacts 或 resources 映射，同时存在顶级 workspace、artifacts 或 resources 映射，则任何有冲突的设置将由目标中的设置替代。

目标还可以替代任何顶级变量的值。

若要将某个目标指定为默认目标，除非另行指定，否则请添加 default 映射并将其设置为 true。例如，名为 dev 的目标是默认目标：

targets:
  dev:
    default: true

若要指定将目标视为开发目标，请添加 mode 映射，并将其设置为 development。若要指定将目标视为生产目标，请添加 mode 映射，并将其设置为 production。例如，此名为 prod 的目标被视为生产目标：

targets:
  prod:
    mode: production

如果指定 mode，则会为预生产和生产工作流提供相应的默认行为的集合。有关详细信息，请参阅 Databricks 资产捆绑包部署模式。此外，还可以为每个目标指定 run_as，如“指定 Databricks 资产捆绑包工作流的运行标识”中所述。

以下示例声明两个目标。第一个目标的编程（或逻辑）名称为 dev，并且是默认目标。第二个目标的编程（或逻辑）名称为 prod，而不是默认目标。第二个目标将使用名为 PROD 的 Azure Databricks 连接配置文件进行身份验证：

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

若要在 dev 目标中验证、部署和运行作业或管道，请运行以下命令：

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run <job-or-pipeline-programmatic-name>

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev <job-or-pipeline-programmatic-name>

若要该为在 prod 目标中验证、部署和运行此作业，请运行以下命令：

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod <job-or-pipeline-programmatic-name>

自定义变量

可以使用自定义变量来使捆绑包配置文件更模块化且更易于重用。例如，可以声明一个变量来代表现有群集的 ID，然后需要将该变量的值更改为在多个目标中运行的各种工作流的不同群集 ID，而无需更改捆绑包配置文件的原始代码。

你可以在捆绑包配置文件中的 variables 映射中声明一个或多个变量。对于每个变量，你可以设置可选说明、默认值或用于检索 ID 值的查找，格式如下：

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    lookup:
      <optional-object-type>: <optional-object-name>

例如，若要声明一个名为 my_cluster_id 且默认值为 1234-567890-abcde123 的变量，以及一个名为 my_notebook_path 且默认值为 ./hello.py 的变量，请运行：

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

如果不在此声明中为变量提供 default 值，则稍后必须在命令行中、通过环境变量或者在捆绑包配置文件中的其他位置提供该值。本部分稍后将介绍这些方法。

注意

无论选择采用哪种方法来提供变量值，在部署和运行阶段都应该使用相同的方法。否则，在部署和基于该现有部署的作业或管道运行之间的时间里，可能会出现意外结果。

若要在捆绑包配置文件中引用自定义变量，请使用替换。对于变量，请使用格式 ${var.<variable_name>}。例如，若要引用名为 my_cluster_id 和 my_notebook_path 的变量，请使用：

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

设置变量的值

如果未为变量提供 default 值，或者你想要临时替代变量的 default 值，请使用以下方法之一提供变量的新临时值：

提供变量的值作为 validate、deploy 或 run 等 bundle 命令的一部分。为此，请使用选项 --var="<key>=<value>"，其中 <key> 是变量的名称，<value> 是变量的值。例如，在 bundle validate 命令中，若要将 1234-567890-abcde123 值提供给名为 my_cluster_id 的变量，并将 ./hello.py 值提供给名为 my_notebook_path 的变量，请运行：
```
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
```
通过设置环境变量提供变量的值。环境变量的名称必须以 BUNDLE_VAR_ 开头。若要设置环境变量，请参阅操作系统的文档。例如，若要将 1234-567890-abcde123 值提供给名为 my_cluster_id 的变量，并将 ./hello.py 值提供给名为 my_notebook_path 的变量，请在调用 validate、deploy 或 run 等 bundle 命令之前运行以下命令：

对于 Linux 和 macOS：
```
export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
```
对于 Windows：
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
```
或者，将变量的值作为 validate、deploy 或 run 等 bundle 命令的一部分提供，例如，对于 Linux 和 macOS，请运行：
```
BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
```
或者对于 Windows，请运行：
```
"set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
```

在捆绑包配置文件中提供变量的值。为此，请遵循以下格式在 targets 映射中使用 variables 映射：

variables:
  <variable-name>: <value>

例如，若要为两个不同目标的名为 my_cluster_id 和 my_notebook_path 的变量提供值，请运行：

targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py

在以上示例中， Databricks CLI 按以下顺序查找变量 my_cluster_id 和 my_notebook_path 的值，当它找到每个匹配变量的值时会停止查找，并跳过该变量的任何其他位置：

在指定为 bundle 命令的一部分的任何 --var 选项中。
在任何以 BUNDLE_VAR_ 开头的环境变量集中。
在属于捆绑包配置文件内的 targets 映射的任何 variables 映射中。
捆绑包配置文件内的顶级 variables 映射中该变量定义的任何 default 值。

检索对象的 ID 值

对于 alert、cluster_policy、cluster、dashboard、instance_pool、job、metastore、pipeline、query、service_principal 和 warehouse 对象类型，可以使用以下格式为自定义变量定义一个 lookup 来检索命名对象的 ID：

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

如果为变量定义了查找，则具有指定名称的对象的 ID 将用作变量的值。这可确保始终将对象的正确解析的 ID 用于变量。

注意

如果不存在具有指定名称的对象，或者有多个具有指定名称的对象，则会发生错误。

例如，在以下配置中，${var.my_cluster_id} 将被替换为 12.2 共享群集的 ID。

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}

Git 设置

可以检索并覆盖与捆绑包关联的版本控制详细信息。这对于注释已部署的资源非常有用。例如，你可能希望在部署的机器学习模型的描述中包含存储库的原始 URL。

每当运行 bundle 命令（例如 validate、deploy 或 run）时，bundle 命令都会使用以下默认设置填充命令的配置树：

bundle.git.origin_url，表示存储库的源 URL。该值与从克隆存储库运行命令 git config --get remote.origin.url 时获得的值相同。可以使用替换在捆绑包配置文件（如 ${bundle.git.origin_url}）中引用此值。
bundle.git.branch，表示存储库中的当前分支。该值与从克隆存储库运行命令 git branch --show-current 时获得的值相同。可以使用替换在捆绑包配置文件（如 ${bundle.git.branch}）中引用此值。
bundle.git.commit，表示存储库中的 HEAD 提交。该值与从克隆存储库运行命令 git rev-parse HEAD 时获得的值相同。可以使用替换在捆绑包配置文件（如 ${bundle.git.commit}）中引用此值。

若要检索或覆盖 Git 设置，捆绑包必须位于与 Git 存储库关联的目录中，例如通过运行 git clone 命令初始化的本地目录。如果目录未与 Git 存储库关联，则这些 Git 设置为空。

如果需要，可以替代顶级 bundle 映射的 git 映射中的 origin_url 和 branch 设置，如下所示：

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

替换

可以使用替换来使捆绑包配置文件更模块化且更易于重用。

提示

还可以对作业参数值使用动态值引用，以将有关作业运行的上下文传递给作业任务。请参阅将有关作业运行的上下文传递到作业任务中。

例如，在运行 bundle validate 命令时，你可能会看到如下所示的图形（为简洁起见，用省略号表示省略的内容）：

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

在以上示例中，可以使用替换 ${workspace.current_user.userName} 来引用捆绑包配置文件中的值 someone@example.com。

同样，以下替换：

/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

在如下所示的捆绑包配置文件中（为简洁起见，用省略号表示省略的内容）：

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

在运行 bundle validate 命令时将解析为下图（为简洁起见，用省略号表示省略的内容）：

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

若要确定有效的替换，可以使用 REST API 参考中记录的架构层次结构，也可以使用 bundle validate 命令的输出。例如，根据输出架构的此部分，${resources.pipelines.my_pipeline.target} 被替换为 my_pipeline 的目标的值（在本例中为 hellobundle_dev）：

{
  "...": {
    "...": "..."
  }
  "resources": {
    "...": "...",
    "pipelines": {
      "my_pipeline": {
        "...": "..."
        "target": "hellobundle_dev"
        "...": "..."
      }
    }
  }
}

下面是一些常用的替换：

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.short_name}
${workspace.current_user.userName}
${workspace.file_path}
${workspace.root_path}
${resources.jobs.<job-name>.id}
${resources.models.<model-name>.name}
${resources.pipelines.<pipeline-name>.name}