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/dlt_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.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"
}
},
"..."
}