何謂動態值參考？

發行項
10/14/2024

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

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

已設定作業的值，包括作業名稱、工作名稱和觸發程序類型。
產生的作業中繼資料，包括作業 ID、執行 ID，以及作業執行開始時間。
有關作業已執行或重試工作之修復嘗試次數的相關資料。
指定之工作的結果狀態。
使用作業參數、工作參數或工作值設定的值。

使用動態值參考

設定作業或工作時，請使用動態值參考。您無法直接參考使用筆記本、查詢或 JAR 等工作所設定資產的動態值參考。動態值參考必須使用將內容傳遞至工作的參數或欄位來定義。

動態值參考使用雙大括弧 ({{ }})。當作業或工作執行時，字串常值會取代動態值參考。例如，如果您將下列索引鍵/值組設定為工作參數：

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

如果您的執行 ID 是 550315892394120，則 job_run_id 的值會評估為 job_550315892394120。

注意

雙大括弧的內容不會評估為運算式。您無法在雙大括弧中執行作業或函式。

使用者提供的值識別碼支援英數字元和底線字元。包含特殊字元的 Esc 鍵，方法是使用反引號 (` `) 括住識別碼。

語法錯誤，包括不存在的動態參考值和遺漏大括弧，會以無訊息方式忽略，並視為常值字串。如果您提供屬於已知命名空間的有效參考，例如 {{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}}`	建立叢集並就緒之後，執行開始執行的時間戳記。格式是 UTC 時區中 UNIX epoch 之後的毫秒，如 `System.currentTimeMillis()` 所傳回。請改用 `job.start_time.<format>`。
`{{task_retry_count}}`	如果第一次嘗試失敗，嘗試執行工作的重試次數。第一次嘗試的值是 0，每次重試都會遞增。請改用 `task.execution_count`。
`{{parent_run_id}}`	指派給具有多個工作之作業執行的唯一識別碼。請改用 `job.run_id`。
`{{task_key}}`	指派給具有多個工作之作業一部分的工作唯一名稱。請改用 `task.name`。

共用方式為