Databricks 资产捆绑包配置

2025-10-27

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

databricks.yml

捆绑包必须包含一个（且只有一个）配置文件，该文件在捆绑项目文件夹的根目录中命名 databricks.yml 。 databricks.yml 是定义捆绑包的主配置文件，但它可以在映射中 include 引用其他配置文件，例如资源配置文件。捆绑配置以 YAML 表示。有关 YAML 的详细信息，请参阅官方 YAML 规范。

最简单的 databricks.yml 定义捆绑包名称，该名称位于所需的顶级映射捆绑包和目标部署中。

bundle:
  name: my_bundle

targets:
  dev:
    default: true

有关所有顶级映射的详细信息，请参阅 “映射”。

提示

借助对 Databricks 资产捆绑包的 Python 支持，可以在 Python 中定义资源。请参阅 Python 中的捆绑配置。

规范

以下 YAML 规范为 Databricks 资产捆绑包提供顶级配置密钥。有关配置参考，请参阅配置参考。

# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_id: string
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# These are any scripts that can be run.
scripts:
  <some-unique-script-name>:
    content: string

# 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>'
  paths:
    - '<some-file-or-path-to-synchronize>'

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

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

# These are the default workspace settings if not otherwise overridden in
# the 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. 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
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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 中的捆绑示例存储库。

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

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 的目标，该目标使用不同的远程工作区 URL 和工作区身份验证凭据，这些凭据是从调用者的 .databrickscfg 文件中与指定工作区 URL 匹配的 host 条目中读取的。此作业运行相同的笔记本，但使用具有指定群集 ID 的不同远程群集。

注意

Databricks 建议尽可能使用 host 映射而不是 default 映射，因为这样可以提高捆绑包配置文件的可移植性。设置 host 映射会指示 Databricks CLI 在 .databrickscfg 文件中查找匹配的配置文件，然后使用该配置文件的字段来确定要使用的 Databricks 身份验证类型。如果存在具有匹配 host 字段的多个配置文件，则必须使用 --profile 捆绑命令上的选项来指定要使用的配置文件。

请注意，不需要在 notebook_task 映射中声明 prod 映射，因为如果未显式替代 notebook_task 映射中的 resources 映射，它会回退为使用顶级 notebook_task 映射中的 prod 映射。

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 验证、部署和运行此作业。有关捆绑包生命周期的详细信息，请参阅开发 Databricks 资产捆绑包。

# 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:
  - '*.yml'

# hello-job.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

# 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

映射

以下部分介绍了捆绑包配置顶级映射。有关配置参考，请参阅配置参考。

包
run_as
包括
脚本
同步
项目
变量
工作区
权限
资源
目标

捆绑销售

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

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

bundle:
  name: hello-bundle

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

cluster_id（集群标识）

bundle 映射可以拥有一个子 cluster_id 映射。通过此映射，可以指定要替代在捆绑包配置文件中其他位置定义的任何和所有群集的群集的 ID。有关如何检索群集 ID 的信息，请参阅计算资源 URL 和 ID。

cluster_id 替代适用于仅开发应用场景，并且仅支持其 mode 映射设置为 development 的目标。有关 target 映射的详细信息，请参阅目标。

compute_id

注意

此设置已弃用。请改用 cluster_id。

bundle 映射可以拥有一个子 compute_id 映射。通过此映射，可以指定要替代在捆绑包配置文件中其他位置定义的任何和所有群集的群集的 ID。

git

可以检索和替代与捆绑包关联的 Git 版本控制详细信息，这对于传播稍后可用于标识资源的部署元数据非常有用。例如，您可以溯源由 CI/CD 部署的作业所在的存储库。

每当运行 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}）中引用此值。

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

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

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

run_as

该 run_as 设置指定 user_name 或 service_principal_name 用于运行捆绑包。它提供将用于部署捆绑作业或管道的标识与用于运行作业或管道的标识分开的功能。

请参阅指定 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'

脚本

该 scripts 设置指定可以使用 bundle run.. 映射中的每个 scripts 命名脚本都包含包含包含命令的内容。例如：

scripts:
  my_script:
    content: uv run pytest -m ${bundle.target}

有关详细信息，请参阅 “执行脚本”。

同步

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

包含和排除

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

根据捆绑包根目录的 .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 文件夹中的任何其他文件也不会包含在内。

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

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/
    ...

项目

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

type 是生成 Python wheel 所必需的。若要在部署之前生成 Python wheel 文件，请将该文件设置为 whl。若要生成其他项目，无需指定此设置。
path 是可选路径。路径相对于捆绑配置文件的位置。对于 Python 滚轮生成，它是 Python 滚轮文件文件 setup.py 的路径。如果未包含 path，Databricks CLI 会尝试在打包文件的根目录中查找 Python wheel 文件的 setup.py 文件。
files 是一个可选映射，其中包含子 source 映射，可用于指定生成的项目。路径相对于捆绑配置文件的位置。
build 是部署前要在本地运行的一组可选非默认生成命令。对于 Python wheel 生成，Databricks CLI 假定它可以找到 Python wheel 包的本地安装来运行生成，并且在每个捆绑包部署期间默认运行命令 python setup.py bdist_wheel。在单独的行上指定多个生成命令。
dynamic_version 使捆绑包能够根据 wheel 文件的时间戳来更新 wheel 版本。然后，新代码就可以在无需更新setup.py或pyproject.toml版本的情况下部署。仅当 type 设置为 whl 时，该设置才有效。

以下示例配置运行测试并生成滚轮。有关用于 artifacts 生成滚轮的完整捆绑包教程，请参阅使用 Databricks 资产捆绑包生成 Python 滚轮文件。

artifacts:
  default:
    type: whl
    build: |-
      # run tests
      python -m pytest tests/ -v

      # build the actual artifact
      python setup.py bdist_wheel

    path: .

有关生成 JAR 并将其上传到 Unity 目录的示例配置，请参阅将 JAR 文件上传到 Unity 目录的捆绑包。

提示

可以定义、合并和替代捆绑包中项目的设置，如 “替代”和目标设置中所述。

变量

捆绑包设置文件可能包含一个顶级 variables 映射，其中定义了自定义变量。对于每个变量，请设置可选说明、默认值、自定义变量是否为复杂类型、用于检索 ID 值的查找，使用如下格式：

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

注意

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

若要在捆绑包配置中引用自定义变量，请使用替换 ${var.<variable_name>}。

有关自定义变量和替换的详细信息，请参阅 Databricks 资产捆绑包中的替换和变量。

工作区

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

重要

有效的 Databricks 工作区路径开头为 /Workspace，但还支持 /Volumes（适用于工件）。自定义工作区路径会自动添加 /Workspace 前缀；因此，如果在自定义路径中使用任何工作区路径替换（如 ${workspace.file_path}），则不需要在路径前添加 /Workspace。

根路径

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

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

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

工件路径

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

workspace:
  artifact_path: /Workspace/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: /Workspace/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 身份验证类型。如果 host 文件中存在多个具有匹配 .databrickscfg 字段的配置文件，则必须使用 profile 映射（或 --profile 或 -p 命令行选项）指示 Databricks CLI 要使用哪个配置文件。有关示例，请参阅prod中的目标声明。
host 映射指定 Azure Databricks 工作区的 URL。请参阅每工作区 URL。
对于 OAuth 计算机到计算机 (M2M) 身份验证，请使用映射 client_id。也可以在本地环境变量 DATABRICKS_CLIENT_ID 中设置此值。或者，可以使用 client_id 值创建配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。请参阅使用 OAuth 授权服务主体访问 Azure Databricks。

注意

不能在捆绑包配置文件中指定 Azure Databricks OAuth 机密值。应该设置本地环境变量 DATABRICKS_CLIENT_SECRET。或者，可以将 client_secret 值添加到配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。
对于 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 资源。

权限

顶级 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

资源

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

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

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

以下示例配置定义了一个作业资源。

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

有关捆绑包中支持的资源以及常见配置和示例的详细信息，请参阅 Databricks 资产捆绑包资源和捆绑包配置示例。

目标

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

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

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

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

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

默认

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

targets:
  dev:
    default: true

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

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

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，则将取消暂停计划。

通过