什么是动态值引用？

项目
10/14/2024

动态值引用是指配置作业和任务时可用的变量集合。使用动态值引用可以为任务配置条件语句，或将信息作为参数进行传递。

动态值引用包括的信息例如：

为作业配置的值，包括作业名称、任务名称和触发器类型等。
生成的有关作业的元数据，包括作业 ID、运行 ID 和作业运行开始时间等。
有关作业已执行的修复尝试次数或任务已运行的重试次数的信息。
指定任务的结果状态。
使用作业参数、任务参数配置的值，或使用任务值设置的值。

使用动态值引用

在配置作业或任务时使用动态值引用。不能直接从笔记本、查询或 JAR 等使用任务配置的资产引用动态值引用。必须使用会将上下文传递到任务的参数或字段来定义动态值引用。

动态值引用使用双大括号 ({{ }}) 来表示。作业或任务运行时，将用一个字符串字面量来替换动态值引用。例如，假设将以下键值对配置为任务参数：

{"job_run_id": "job_{{job.run_id}}"}

如果运行 ID 为 550315892394120，则 job_run_id 的值将评估为 job_550315892394120。

注意

双大括号中的内容不评估为表达式。不能在双大括号中运行操作或函数。

用户提供的值标识符支持字母数字字符和下划线字符。包含特殊字符的转义键用带反引号 (` `) 的标识符括起来。

语法错误（包括不存在的动态引用值和缺少大括号）将被无提示忽略，并被视为文本字符串。如果提供属于已知命名空间（例如 {{job.notebook_url}}）的无效引用，则将显示一条错误消息。

在作业 UI 中使用动态值引用

接受动态值引用的字段提供了插入可用动态值引用的快捷方式。单击 { } 可查看此列表并将其插入到提供的字段中。

注意

UI 不会自动完成用于引用任务值的键。

接受动态值引用的许多字段都需要符合额外的格式才能正确使用。请参阅配置任务参数。

在作业 JSON 中使用动态值引用

借助 {{ }} 语法可在 Databricks CLI 和 REST API 使用的作业 JSON 定义中使用动态值。

作业和任务参数使用不同的语法，任务参数语法因任务类型而异。

以下示例演示了使用动态值引用配置作业参数的部分 JSON 语法：

{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

以下示例演示了使用动态值引用配置笔记本任务参数的部分 JSON 语法：

{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

检查作业运行的参数

任务完成后，可以在运行详细信息页面的“参数”下查看解析的参数值。请参阅查看作业运行详细信息。

支持的值引用

支持以下动态值引用：

参考	说明
`{{job.id}}`	分配给作业的唯一标识符。
`{{job.name}}`	作业运行时作业的名称。
`{{job.run_id}}`	分配给作业运行的唯一标识符。
`{{job.repair_count}}`	当前作业运行的修复尝试次数。
`{{job.start_time.<argument>}}`	基于作业运行开始时间（UTC 时区）的值。返回值基于 `argument` 选项。请参阅日期和时间值的选项。
`{{job.parameters.<name>}}`	具有 `<name>` 键的作业级参数的值。
`{{job.trigger.type}}`	作业运行的触发器类型。可能的值为 `periodic`、`one_time`、`run_job_task`、`file_arrival`、`continuous` 和 `table`。
`{{job.trigger.file_arrival.location}}`	如果为此作业配置了文件到达触发器，则为存储位置的值。
`{{job.trigger.time.<argument>}}`	基于触发作业运行的时间（UTC 时区）的值，对于具有 cron 计划的作业，向下舍入到最接近的分钟。返回值基于 `argument` 选项。请参阅日期和时间值的选项。
`{{task.name}}`	当前任务的名称。
`{{task.run_id}}`	当前任务运行的唯一标识符。
`{{task.execution_count}}`	运行当前任务的次数（包括重试和修复）。
`{{task.notebook_path}}`	当前笔记本任务的笔记本路径。
`{{tasks.<task_name>.run_id}}`	分配给 `<task_name>` 的任务运行的唯一标识符。
`{{tasks.<task_name>.result_state}}`	任务的结果状态 `<task_name>`。可能的值为 `success`、`failed`、`excluded`、`canceled`、`evicted`、`timedout`、`upstream_canceled`、`upstream_evicted` 和 `upstream_failed`。
`{{tasks.<task_name>.error_code}}`	任务 `<task_name>` 运行时出错的错误代码。可能的值举例如下：`RunExecutionError`、`ResourceNotFound` 和 `UnauthorizedError`。对于成功的任务，其值为空字符串。
`{{tasks.<task_name>.execution_count}}`	运行任务 `<task_name>` 的次数（包括重试和修复）。
`{{tasks.<task_name>.notebook_path}}`	笔记本任务 `<task_name>` 的笔记本路径。
`{{tasks.<task_name>.values.<value_name>}}`	具有由任务 `<task_name>` 设置的 `<value_name>` 键的任务值。
`{{workspace.id}}`	分配给工作区的唯一标识符。
`{{workspace.url}}`	工作区的 URL。

可以使用任何任务设置这些引用。请参阅配置任务参数。

还可以在具有任务值的作业中的任务之间传递参数。请参阅使用任务值在任务之间传递信息。

日期和时间值的选项

使用以下参数可指定基于时间的参数变量的返回值。所有返回值都基于时间戳（UTC 时区）。

Argument	说明
`iso_weekday`	将返回一个介于 1 到 7 的数字，表示时间戳的星期几。
`is_weekday`	如果时间戳在工作日，则返回 `true`。
`iso_date`	以 ISO 格式返回日期。
`iso_datetime`	以 ISO 格式返回日期和时间。
`year`	返回时间戳的年份部分。
`month`	返回时间戳的月份部分。
`day`	返回时间戳的日期部分。
`hour`	返回时间戳的小时部分。
`minute`	返回时间戳的分钟部分。
`second`	返回时间戳的秒部分。
`timestamp_ms`	返回时间戳（以毫秒为单位）。

已弃用的动态值引用

以下动态值引用已被弃用。建议的替换引用包含在每个变量的说明中。

变量	说明
`{{job_id}}`	分配给作业的唯一标识符。请改用 `job.id`。
`{{run_id}}`	分配给任务运行的唯一标识符。请改用 `task.run_id`。
`{{start_date}}`	任务运行的开始日期。格式为 yyyy-MM-dd（UTC 时区）。请改用 `job.start_time.<argument>`。
`{{start_time}}`	创建并准备好群集后运行开始执行的时间戳。格式为自 UNIX 纪元以来的毫秒数（UTC 时区），如 `System.currentTimeMillis()` 所返回。请改用 `job.start_time.<format>`。
`{{task_retry_count}}`	第一次尝试运行任务失败后的重试次数。第一次尝试时的值为 0，每次重试时值会递增。请改用 `task.execution_count`。
`{{parent_run_id}}`	分配给具有多个任务的作业运行的唯一标识符。请改用 `job.run_id`。
`{{task_key}}`	分配给作为作业的一部分的任务的唯一名称，该作业具有多个任务。请改用 `task.name`。

通过