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

项目
10/04/2024

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

提示

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

替换

你可以使用替换来检索设置的值，这些值会根据捆绑包部署和运行的上下文而更改。

例如，运行 bundle validate --output json 命令时，你可能会看到如下所示的图表：

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

替换可用于引用捆绑包 name、捆绑包 target 和工作区 userName 字段的值，以便在捆绑包配置文件中构造工作区 root_path：

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

你还可以为命名资源创建替代项。例如，对于配置了名称 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}

自定义变量

你可以在捆绑包中定义简单和复杂的自定义变量，以实现很多方案所需的值动态检索。自定义变量在 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 值，则必须在执行捆绑命令时、通过环境变量或在捆绑配置文件中的其他位置设置它，如设置变量的值中所述。

若要在捆绑包配置文件中引用自定义变量，请使用变量替换${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}

通过

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

替换

自定义变量

设置变量的值

定义复杂变量

检索对象的 ID 值

反馈

其他资源