何謂動態值參考？

發行項
01/22/2025

動態值參考描述設定作業和工作時可用的變數集合。使用動態值參考來設定工作的條件語句，或將資訊傳遞為參數或自變數。

動態值參考包括下列資訊：

已設定作業的值，包括作業名稱、工作名稱和觸發類型。
產生的作業中繼資料，包括作業 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}}`	工作執行開始的日期。格式為UTC時區中的yyyy-MM-dd。請改用 `job.start_time.<argument>`。
`{{start_time}}`	建立叢集並就緒之後，執行開始執行的時間戳記。格式為從 UNIX epoch 開始經過的毫秒數，採用 UTC 時區，如 `System.currentTimeMillis()`所返回。請改用 `job.start_time.<format>`。
`{{task_retry_count}}`	如果第一次嘗試失敗，嘗試執行工作的重試次數。第一次嘗試的值是 0，每次重試都會遞增。請改用 `task.execution_count`。
`{{parent_run_id}}`	指派給具有多個任務之作業執行過程的唯一標識符。請改用 `job.run_id`。
`{{task_key}}`	指派給具有多個工作之作業一部分的工作唯一名稱。請改用 `task.name`。

共用方式為