Databricks 资产捆绑包中的替换和变量

2025-10-21

Databricks 资产捆绑包支持替换和自定义变量，这使得捆绑包配置文件更模块化，且更易于重用。替换和自定义变量实现了值动态检索，以便在部署和运行捆绑包时确定设置。

提示

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

替换

可以使用替换来检索可能根据捆绑包部署和运行的上下文更改的设置值。例如，子区域可用于引用捆绑包 name、捆绑包 target和工作区 userName 字段的值，以在捆绑配置文件中构造工作区 root_path ：

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

如果 someone@example.com 部署了此捆绑包，则会将其部署到根路径 /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev。

你还可以为命名资源创建替代项。例如，对于以下管道定义，可以用于 ${resources.pipelines.my_pipeline.target} 管道目标的值：

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

若要确定有效的替换，请使用捆绑包配置引用、资源配置引用或 REST API 引用中记录的相应对象的架构层次结构，或命令的 bundle schema 输出。

下面是一些常用的替换：

${bundle.name}
${bundle.target} # Use this substitution instead of ${bundle.environment}
${workspace.host}
${workspace.current_user.domain_friendly_name}
${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}

自定义变量

你可以在捆绑包中定义简单和复杂的自定义变量，以实现很多方案所需的值动态检索。自定义变量在 variables 映射内的捆绑配置文件中或 variable-overrides.json 文件中声明。有关 variables 映射的信息，请参阅变量。

以下示例配置定义了变量 my_cluster_id 和 my_notebook_path：

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 部分提供变量的值，则必须在执行捆绑命令、通过环境变量、捆绑配置文件中的其他位置或在 .databricks/bundle/<target>/variable-overrides.json 捆绑项目中的文件中设置该值。请参阅设置变量的值。

引用变量

若要在捆绑包配置文件中引用自定义变量，请使用变量替换${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 变量的值，请使用以下方法之一提供变量的新临时值。

注意

捆绑变量是部署时变量。部署捆绑包时会解析它们。例如，运行作业时，它将运行以前部署的作业和该部署的已配置变量，因此为运行作业的变量传递不同的值将不适用。而是使用作业参数将值传递给作业运行。请参阅 “传递作业参数”。

提供变量的值作为 bundle、validate 或 deploy 等 run 命令的一部分。为此，请使用选项 --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 的变量，请在调用 bundle、validate 或 deploy 等 run 命令之前运行以下命令：

对于 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"
```
或者，将变量的值作为 bundle、validate 或 deploy 等 run 命令的一部分提供，例如，对于 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"
```

在捆绑配置文件中使用 variables 映射中的 targets 映射提供变量的值，格式如下：

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/bundle/<target>/variable-overrides.json 文件中提供变量的值，使用以下格式：
```
{
  "<variable-name>": "<variable-value>"
}
```
例如，若要为开发目标命名 my_cluster_id 和 my_notebook_path 的变量提供值，请创建一个文件 .databricks/bundle/dev/variable-overrides.json 并将其内容设置为：
```
{
  "my_cluster_id": "1234-567890-abcde123",
  "my_notebook_path": "./hello.py"
}
```
还可以在 variable-overrides.json 文件中定义复杂变量。

注意

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

优先级顺序

Databricks CLI 按以下顺序查找变量的值，在找到变量的值时停止：

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

定义复杂变量

除非将其定义为复杂变量，否则会假定自定义变量为字符串类型。若要为捆绑定义具有复杂类型的自定义变量，请在捆绑配置中将 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

还可以在 .databricks/bundle/<target>/variable-overrides.json 文件中定义复杂变量，如以下示例所示：

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

检索对象的 ID 值

对于 alert、cluster_policy、cluster、dashboard、instance_pool、job、metastore、notification_destination、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}

输出替换和变量值

若要确保 Databricks 资产捆绑包正确指定和分析替换和变量，请运行 databricks bundle validate。请参阅 databricks 捆绑包验证。若要查看在部署捆绑包时将使用的值，请使用 --output json 以下选项：

databricks bundle validate --output json

例如，对于在作业任务中定义和使用变量 my_cluster_id 的捆绑包：

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

databricks bundle validate架构输出如下：

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}