通过

Databricks 资产捆绑包配置

  • 项目

本文介绍用于定义 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
  cluster_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>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# 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.
    cluster_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 映射，该映射关联捆绑包的内容和 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 版本控制详细信息。 这对于注释已部署的资源非常有用。 例如，你可能希望在部署的机器学习模型的描述中包含存储库的原始 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 映射，其中定义了自定义变量。 对于每个变量，请设置可选说明、默认值、自定义变量是否为复杂类型、用于检索 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>

注意

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

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

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

工作区

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

重要

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

root_path

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

artifact_path

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

file_path

此 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

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。

  • 对于 OAuth 计算机到计算机 (M2M) 身份验证，请使用映射 client_id。 也可以在本地环境变量 DATABRICKS_CLIENT_ID 中设置此值。 或者，可以使用 client_id 值创建配置文件，然后使用 profile 映射指定配置文件的名称（或者在通过 Databricks CLI 运行捆绑包验证、部署、运行和销毁命令时使用 --profile 或 -p 选项）。 请参阅使用 OAuth (OAuth M2M) 通过服务主体对 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

项目

顶级 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 命令将返回警告。

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

资源类型 资源映射
clusters 群集映射：POST /api/2.1/jobs/create
作业 作业映射：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

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

clusters

借助 clusters 资源可以创建通用群集。 以下示例将创建一个名为 my_cluster 的群集并将其设置为用于在 my_job 中运行笔记本的群集：

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          existing_cluster_id: ${resources.clusters.my_cluster.id}
          notebook_task:
            notebook_path: "./src/my_notebook.py"

作业 (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.

Databricks 资产捆绑包不支持顶级授权映射，因此如果想为架构设置授权，请在 schemas 映射中定义架构的授权：

schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - CAN_MANAGE
        - principal: my_team
          privileges:
            - CAN_READ
      catalog_name: main
      comment: "my schema with grants"

同步

通过 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

若要为捆绑包命令指定目标默认值，请将 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，则将取消暂停计划。