參數化

關於參數

您可以透過傳遞可改變工作、工作或工作執行行為的參數來自訂工作執行。

您可以在工作流程的三個不同層次提供參數：工作層次、工作層次以及工作執行層次。發生衝突時，參數的優先順序如下：工作執行 > 工作 > 工作。

工作執行層次參數：工作執行有效負載中指定的工作執行層次參數優先於工作組態中定義的工作層次參數。這表示工作執行期間所指定的任何參數都會覆寫工作特定的預設值。
工作層次參數：如果未提供特定工作的工作執行參數，則工作會使用在工作組態中的工作層次定義的參數。相同名稱的工作層次參數會覆寫該特定工作的工作層次參數。因此，如果您想要使用工作特定參數，應該以不同的方式命名工作參數。
工作層次參數：如果未提供工作層次或程式實際執行參數，則會套用在工作層次設定的預設值。如果沒有其他特定的參數可用，則工作層次參數會被視為預設值。

附註：

工作參數在工作相關資訊環境中是不可變更的。這表示如果有一個參數為 JobParamA 且解析值為 JobParamRuntimeValueA 的工作，則 TaskA 執行無法變更 JobParamA 的值。對於所有工作和整個工作執行，JobParamA 的值會維持為 JobParamRuntimeValueA。因此，如果您想要在工作之間共用資訊，可以使用中間儲存體或輸出參數來達成此目標。

當工作名稱、工作值索引鍵或工作參數名稱包含特殊字元 (例如！@$%) 時，您必須使用底線 (` `) 括住這些 ID。只能使用文數字和底線字元，但不能在底線加上 ID。

舉例而言：

{
  "VariableWithSpecialChars": "{{job.parameters.`param$@`}}"
}

「系統參數」是範本參數，其值是由系統在工作流程執行與後續任務執行時提供。您不需要為這些範本參數提供任何預設值或其他值。AI Data Platform Workbench 具有在工作流程中支援的有效範本參數 / 動態值參考固定清單。系統參數的輸入方式為以兩個大括號括住。例如，{{job.id}}。

表格 12-1 支援的系統參數

Parameter - 參數	描述
繁體中文	指定給中樞的唯一識別碼
繁體中文	Hub 的區域
{{workspace.id}}	指定給工作區的唯一識別碼
繁體中文	工作區的 URL
{{JOBID}}	指定給工作的唯一識別碼
{{job.name}}	工作執行時的工作名稱
人才招聘	指派給工作執行的唯一識別碼
繁體中文	目前工作執行的修復嘗試次數
繁體中文 (香港)	以工作執行開始時間為基礎的值 (以 UTC 時區表示)。傳回值是以引數選項為基礎。請參閱日期與時間值的選項。
繁體中文 (香港)	索引鍵為 [name] 的工作層次參數值
繁體中文 (香港)	工作執行的觸發類型。可能的值為「手動」與「已排定」。
繁體中文 (香港)	如果為此工作設定檔案到達觸發程式，則為儲存位置的值
{{job.trigger.time.[ 引數 ]}}	以觸發工作執行的時間 (UTC 時區) 為基礎的值，以 cron 排程的工作捨去至最接近的分鐘。傳回值是以引數選項為基礎。請參閱日期與時間值的選項。
{{ 任務名稱 }}	目前任務的名稱
繁體中文 (香港)	目前作業執行的唯一識別碼
繁體中文 (台灣)	目前作業的執行次數 (包括重試與修復)
繁體中文 (香港)	目前記事本任務的記事本路徑
繁體中文 (香港)	指定給 [task_name] 作業執行的唯一識別碼
繁體中文 (台灣)	工作 [task_name] 的結果狀態。可能的值包括成功、失敗、排除、取消、略過、逾時、upstream_canceled 和 upstream_failed。
繁體中文 (香港)	執行作業時發生錯誤，作業 [task_name] 的錯誤代碼。可能的值範例為 RunExecutionError、ResourceNotFound 和 UnauthorizedError。對於成功的工作，這會評估為空白字串。
{{tasks.[ 任務名稱 ].execution_count}}	作業 [task_name] 的執行次數 (包括重試和修復)
繁體中文 (台灣)	記事本作業 [task_name] 的記事本路徑
{{tasks.[task_name].values.[value_name}}	具有由作業 [task_name] 設定之鍵值 [value_name] 的作業值

表格 12-2 日期與時間的選項

引數	描述
iso_weekday	傳回 1 到 7 的數字，代表時間戳記中的星期幾
is_weekday	如果時間戳記在工作日，則傳回 `true`
日期 (_U)	傳回 ISO 格式的日期
日期時間 (_D)	以 ISO 格式傳回日期與時間
年	傳回時間戳記的年部分
月份	傳回時戳的月份部分
天	傳回時戳的第幾部份
小時	傳回時戳的小時部分
分鐘	傳回時戳的分鐘部分
秒	傳回時間戳記的第二個部份
時間戳記毫秒	傳回時戳 (毫秒)

在任務與記事本之間傳遞參數

您可以將作業的參數傳遞至記事本，反之亦然。這會啟用動態工作流程行為，讓記事本能夠根據執行時期值調整處理。

oidlUtils.parameters 套裝軟體提供了處理這些參數作業的必要功能。oidlUtils 套裝程式是「AI 資料平台工作台」中的公用程式程式庫，可簡化參數管理、傳遞作業值以及其他工作流程作業等作業。它通常用於記事本和任務，以在工作流程階段取得和設定參數。

任務關鍵碼值為字串或 JSON。例如，若要使用字串作為任務索引鍵值，參數呼叫的外觀如下：

oidlUtils.parameters.setTaskValue(key="payload", value="abc", "defaultValue")

若要使用 JSON 作為任務索引鍵值，參數呼叫的外觀如下：

oidlUtils.parameters.setTaskValue(key="payload", value=json.dumps(payload), "defaultValue")

範例工作流程：傳送參數

在此案例中，工作流程有兩個記事本。記事本 1 會從工作接收參數、處理參數，以及設定在下一個工作中傳遞至記事本 2 的輸出參數。

記事本 1：取得並設定參數

# Get parameter if already set in the task
param_key = "param1"
param_value = oidlUtils.parameters.getParameter(param_key, "defaultValue")
print(param_value)
print("Param {} value is {}".format(param_key, param_value))

 
# Set parameter value in the task
output_parameter_key = "output_parameter"
output_param_value = oidlUtils.parameters.getParameter(output_parameter_key, "defaultValue2")
print("Param {} value is {}".format(output_parameter_key, output_param_value))
oidlUtils.parameters.setTaskValue(output_parameter_key, "1234")

第一個記事本會擷取從工作傳送的參數 (param1)，然後設定新參數 (output_param_2)，該參數將用於下一個工作。

記事本 2：讀取輸出參數

output_param_2= "output_parameter"
param_value = oidlUtils.parameters.getTaskValue("GetSetParameter", output_param_2, "defaultValue")
print("Param {} value is {}".format(output_param_2, param_value))

第二個記事本會透過工作流程任務從「記事本 1」接收 output_param_2 並加以處理。

工作 1：記事本 1
- 在第一個任務中，參數可以從工作或任務本身傳遞至記事本 1。
- 記事本 1 會將參數當作輸入參數 param1 處理，並設定新的輸出參數 (例如 output_param_2)。
工作 2：記事本 2
- 在第二個工作中，「記事本 2」會透過傳遞工作流程中所設定之第一個工作 "GetSetParameter" 的名稱，直接在記事本程式碼中參照「工作 1」來接收輸出參數。
- output_param_2 的值會傳遞至「記事本 2」，以便進一步處理。

此方法可讓您輕鬆在任務與筆記型電腦之間動態傳送值，讓您的工作流程更具彈性且可調適性。