Databricks 资产捆绑包配置

项目
09/30/2024

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

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

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

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

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

概述

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

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  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 or complex

# 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.
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema 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
    presets:
      <preset>: <value>
    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.

示例

注意

有关演示捆绑包功能和常见捆绑包用例的配置示例，请参阅捆绑包配置示例和 GitHub 中的捆绑示例存储库。

以下示例捆绑配置指定了一个位于名为 databricks.yml 的本地捆绑配置文件的同一目录中的 hello.py 本地文件。它使用具有指定群集 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 和工作区身份验证凭据，这些凭据是从调用者的 .databrickscfg 文件中与指定工作区 URL 匹配的 host 条目中读取的。此作业运行相同的笔记本，但使用具有指定群集 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

映射

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

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

捆绑包

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

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

bundle:
  name: hello-bundle

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

compute_id

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

git

可以检索并覆盖与程序包关联的 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>

databricks_cli_version

bundle 映射可以包含约束程序包所需的 Databricks CLI 版本的 databricks_cli_version 映射。这可以防止因使用特定版本的 Databricks CLI 不支持的映射引起的问题。

Databricks CLI 版本符合语义版本控制要求，且 databricks_cli_version 映射支持指定版本约束。如果当前的 databricks --version 值不在捆绑包的 databricks_cli_version 映射中指定的边界内，则在捆绑包上执行 databricks bundle validate 时会出错。以下示例演示了一些常见的版本约束语法：

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

variables

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

工作区

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

root_path

此 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} 的默认路径，该路径使用替换。

artifact_path

此 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) 路径。

file_path

此 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

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 选项）。查看 MS Entra 服务主体身份验证。

注意

不能在捆绑包配置文件中指定 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 推断出意外身份验证类型的情况下。请参阅 Azure Databricks 工具和 API 的身份验证。

权限

顶级 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 参考中介绍了创建操作的请求有效负载，databricks bundle schema 命令将输出所有受支持的对象架构。此外，如果在捆绑包配置文件中发现未知资源属性，databricks bundle validate 命令将返回警告。

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

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

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

作业 (job)

以下示例使用资源键 hello-job 声明一个作业：

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

管道

以下示例使用资源键 hello-pipeline 声明一个管道：

resources:
  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

schema

通过使用 schema 资源类型，你可以为工作流和管道中作为 Bundle 的一部分创建的表和其他资产定义 Unity Catalog 构架。不同于其他资源类型，架构具有以下限制：

构架资源的所有者始终是部署用户，不能更改。如果在捆绑包中指定了 run_as，则构架上的操作将忽略它。
只有相应的构架对象创建 API 支持的字段才可用于 schema 资源。例如，不支持 enable_predictive_optimization，因为它仅在更新 API 上可用。

以下示例声明了一个使用资源键 my-pipeline 的管道，该管道会创建一个以键 my-schema 为目标的 Unity Catalog 构架：

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

同步

通过 sync 映射，可以配置哪些文件属于捆绑部署的一部分。

包含和排除

sync 映射中的 include 和 exclude 映射指定了要在捆绑部署中包含或排除的文件或文件夹列表，具体取决于以下规则：

根据捆绑包根目录的 .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

路径

映射 sync 可以包含一个 paths 映射，用于指定要同步到工作区的本地路径。通过 paths 映射，可以跨捆绑包共享通用文件，并可用于同步位于捆绑包根目录之外的文件。（捆绑包根目录是 databricks.yml 文件的位置。）如果单个存储库托管多个捆绑包，并且想要共享库、代码文件或配置，这尤其有用。

指定的路径必须与设置 paths 映射的文件夹上的文件和目录相对。如果一个或多个路径值遍历目录到捆绑包根目录的上级目录，则会动态确定根路径，以确保文件夹结构保持不变。例如，如果捆绑包根目录文件夹名为 my_bundle，则 databricks.yml 中的此配置将同步位于捆绑包根目录上一级的 common 文件夹和捆绑包根目录本身：

sync:
  paths:
    - ../common
    - .

部署此捆绑包会在工作区中产生以下文件夹结构：

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

目标

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

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

此 targets 映射是可选的，但强烈建议使用。如果指定它，它只能显示为顶级映射。

如果未在 targets 映射中指定顶级工作区、项目和资源映射中的设置，则将使用它们，但任何冲突的设置都将被目标内的设置覆盖。

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

默认值

若要为捆绑包命令指定目标默认值，请将 default 映射设置为 true。例如，名为 dev 的目标是默认目标：

targets:
  dev:
    default: true

如果未配置默认目标，或者想要在特定目标内验证、部署和运行作业或管道，请使用捆绑包命令的 -t 选项。

以下命令在 dev 和 prod 目标中验证、部署和运行 my_job：

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

以下示例声明两个目标。第一个目标具有名称 dev，是未为捆绑包命令指定目标时使用的默认目标。第二个目标具有名称 prod，仅在为捆绑包命令指定此目标时才使用。

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

模式和预设

为了方便开发和 CI/CD 最佳做法，Databricks 资产捆绑包为目标提供了部署模式，其为预生产和生产工作流设置默认行为。一些行为也是可配置的。有关详细信息，请参阅 Databricks 资产捆绑包部署模式。

提示

若要为捆绑包设置运行标识，还可以为每个目标指定 run_as，如指定 Databricks 资产捆绑包工作流的运行标识中所述。

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

targets:
  prod:
    mode: production

可以使用 presets 映射自定义某些行为。有关可用预设的列表，请参阅自定义预设。以下示例显示了为所有生产资源添加前缀和标签的自定义生产目标：

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

如果同时设置了 mode 和 presets，则预设将替代默认模式行为。单个资源的设置将替代预设。例如，如果计划设置为 UNPAUSED，但 trigger_pause_status 预设设置为 PAUSED，则将取消暂停计划。

自定义变量

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

自定义变量在 variables 映射中的捆绑配置文件中声明。对于每个变量，请设置可选说明、默认值、类型或用于检索 ID 值的查找，使用如下格式：

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

注意

除非 type 设置为 complex，否则变量假定为类型 string。请参阅定义复杂变量。

例如，若要声明一个名为 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 值。

定义复杂变量

若要为捆绑包定义具有复杂类型的自定义变量，请在捆绑配置中将 type 设置为 complex。

注意

type 设置的唯一有效值为 complex。此外，如果 type 设置为 complex 并且为变量定义的 default 为单个值，则捆绑验证将失败。

在以下示例中，群集设置在名为 my_cluster 的自定义复杂变量中定义：

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

检索对象的 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}

替换

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

提示

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

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

{
  "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 --output json 命令时将解析为下图（为简洁起见，用省略号表示省略的内容）：

{
  "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",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

你还可以为命名资源创建替代项。例如，对于配置了名称 my_pipeline 的管道，${resources.pipelines.my_pipeline.target} 是 my_pipeline 目标值的替代项。

若要确定有效的替代项，可以使用 REST API 参考中介绍的架构层次结构，也可以使用 bundle schema 命令的输出。

下面是一些常用的替换：

${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}