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

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 的值，当它找到每个匹配变量的值时会停止查找，并跳过该变量的任何其他位置：

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

定义复杂变量

除非将其定义为复杂变量，否则会假定自定义变量为字符串类型。 若要为捆绑包定义具有复杂类型的自定义变量，请在捆绑配置中将 type 设置为 complex。

在以下示例中，群集设置在名为 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}