如何配置及使用調度參數 - DataWorks

在資料工作流程中，任務代碼（如SQL）通常需要根據調度時間動態改變，以處理不同日期的資料分區。為避免手動修改代碼，可以使用調度參數。通過在代碼中預設預留位置，任務調度時系統會自動將佔位符替換為業務日期、定時已耗用時間等動態值，實現工作流程的自動化與參數化運行。

核心配置流程

使用調度參數需要定義調度參數，並在調度配置中為調度參數進行賦值。在資料開發測試無誤後，將含有調度參數的代碼提交至營運中心，由系統進行自動調度並根據賦值邏輯動態替換調度參數的值。

步驟	動作	核心目標
1. 定義參數	在節點代碼中，使用 `${param}` 格式定義一個或多個參數。	為動態值預留一個預留位置。
2. 配置參數	在節點的調度配置 > 調度參數面板，為代碼中的變數賦值。	將佔位符`${param}`與具體的調度參數（如`$bizdate`、`$[yyyymmdd-1]`）等關聯起來。
3. 測試	使用煙霧測試 (Smoke Test)功能，類比特定業務日期，驗證參數替換和代碼執行的正確性。	在開發環境確保配置無誤。
4. 發布與驗證	將節點提交到生產環境，並在營運中心確認最終的參數配置。	確保線上任務的參數符合預期。

使用步驟

一、定義參數

雙擊目標節點，如ODPS SQL節點，進入節點編輯介面。

在代碼中定義參數：在ODPS SQL節點或其他SQL節點代碼中，使用 ${param} 文法定義一個參數名。DataWorks推薦使用有意義的參數名，方便後期查閱和管理。

調度參數調用格式：

格式類型	調用文法	適用範圍	備忘
通用格式	`${參數名}`	適用於絕大多數節點類型，如 ODPS SQL、資料同步節點等。	這是最常用格式。
特殊格式	因節點而異，非 `${...}` 格式。	PyODPS、Shell	詳情請參考：各類型節點的調度參數配置樣本

-- 樣本：定義一個名為pt_date的變數，用於分區過濾
SELECT * FROM my_table WHERE ds = '${pt_date}';

單擊介面右側的調度配置，進入調度參數配置。
配置調度參數，配置方式見下文。

二、配置參數

支援通過可視化定義和用運算式定義兩種方式設定調度參數，可以通過參數列表右上方的用運算式定義進行切換，預設為可視化定義模式。

配置參數
可視化定義
單擊節點右側的調度配置，進入調度參數配置介面。
- 新增參數
  單擊節點右側的調度配置，在調度參數中添加參數。支援以下兩種參數的添加方式。
  1. 單擊新增參數，手動填寫參數的參數名和參數值。注意參數名需與代碼中定義的變數名保持一致。
  2. 單擊載入代碼中的參數，DataWorks將自動解析上文代碼中的變數，如${pt_date}，並回填，您只需填寫參數值即可。
- 參數賦值
  支援設定系統內建變數、自訂時間變數和常量。
  - 單擊輸入框，下拉式清單中，展示了部分常用的參數運算式，可以直接選用。可支援手動輸入自訂運算式或者系統內建變數。
  - 支援根據業務需要填寫，參數值支援的範圍詳見：調度參數支援的格式。
用運算式定義
單擊用運算式定義，切換配置模式。如果您更習慣運算式方式配置參數，可以使用該模式。
- 使用運算式定義時，多個參數之間使用空格分隔。
- 當通過用運算式定義方式，添加、刪除或修改調度參數時，DataWorks會對當前運算式的文法進行校正，校正不通過則無法配置相應調度參數。
  例如，DataWorks會對等號左右不允許使用空格等文法規則進行檢測。
參數預覽
參數定義完成後，單擊調度參數預覽，查看調度參數在指定業務日期後N個執行個體的參數預覽效果，測試參數定義是否符合預期。支援調整業務日期和執行個體預覽個數。

說明

此處部分節點如離線同步會內建${bizdate}參數，該參數名自動賦值為$bizdate，您可替換代碼中bizdate參數名為自訂的參數名。${bizdate}本身無特殊含義，與其他自訂參數相同。

三、煙霧測試 (Smoke Test)

調度參數賦值完成後，建議通過煙霧測試 (Smoke Test)功能，配置業務日期，類比目標任務的調度情境，驗證該情境下代碼執行及調度參數的替換是否符合預期。若不符合預期，請根據需要及時調整，以免影響任務正常調度運行。

執行煙霧測試 (Smoke Test)會產生相應執行個體產生執行個體費用。執行個體的費用詳情請參見Serverless資源群組計費。

提交節點代碼。
1. 配置調度時間和調度依賴。
2. 單擊儲存，儲存代碼和配置後，單擊提交按鈕，提交當節點最新代碼提交至營運中心後，才可在開發環境使用煙霧測試 (Smoke Test)功能。
  說明
  若發現煙霧測試 (Smoke Test)時執行的不是最新的代碼或者參數，請重新提交節點。
執行煙霧測試 (Smoke Test)。
單擊工具列的煙霧測試 (Smoke Test)按鈕，在煙霧測試 (Smoke Test)彈窗中選擇業務日期，單擊確認，開始進行煙霧測試 (Smoke Test)。
查看煙霧測試 (Smoke Test)日誌。
1. 在彈出的煙霧測試 (Smoke Test)記錄視窗中，找到最新的記錄，單擊查看日誌。
2. 在日誌中檢查參數列印情況，確認是否符合預期。
  說明
  若不慎關閉視窗，可點擊工具列的煙霧測試 (Smoke Test)記錄按鈕重新開啟。

重要

運行與進階運行功能需手動為代碼中的變數賦值常量，因此無法校正配置的調度參數是否符合預期。

四、發布與驗證

在開發環境驗證完成後，任務可以提交發布至營運中心，正式提交生產，進行自動調度。任務發布後，請務必檢查生產環境的調度參數，以防運行出錯。

說明

如果周期任務的調度參數配置不符合預期，或營運中心搜尋不到目標任務，請確認該任務是否發布成功。任務的發佈動作，詳情請參見發布任務。

檢查參數定義。
進入營運中心，切換目標地區和工作空間，進入周期任務營運 > 周期任務介面。在工作清單中單擊任務名稱，查看任務的屬性面板中的執行參數是否符合預期。
營運中心煙霧測試 (Smoke Test)。
在營運中心也可以通過煙霧測試 (Smoke Test)，來確認已提交發布的任務在生產環境下，是否按照預期進行參數替換和代碼執行。詳情參見：執行測試並查看測試執行個體。
重要
需要注意的是，煙霧測試 (Smoke Test)會真實執行生產環境的資料，請謹慎執行，避免對生產庫的資料造成汙染。
實際調度結果觀測。
待任務進入自動調度後，可以通過查看周期執行個體中的參數是否已經按要求自動替換來進一步驗證替換參數是否正確。

完整配置樣本

本文以ODPS SQL節點為例，通過在開發環境執行煙霧測試 (Smoke Test)功能測試配置的調度參數是否符合預期，並在任務發布後，查看生產營運中心中該任務的調度參數配置情況。

說明

各類型節點的調度參數配置，詳情請參見各類型節點的調度參數配置樣本。

編輯節點代碼並配置調度參數。
ODPS SQL節點的代碼及調度參數的配置情況如下圖所示。
1. 代碼中定義變數。
```
--賦值系統內建參數
SELECT '${var1}';
SELECT '${var2}';
--賦值自訂參數
SELECT '${var3}';
SELECT '${var4}';
--賦值常量
SELECT '${var5}';
```
2. 為變數賦值。
  在調度配置 > 調度參數地區，為變數賦值（如地區2）。更多賦值格式參見：調度參數支援的格式。
  - var1=$bizdate，即取yyyymmdd格式的業務日期。
  - var2=$cyctime，即取yyyymmddhh24miss格式的任務定時已耗用時間。
  - var3=${yyyymmdd}，即取yyyymmdd格式的業務日期。
  - var4=$[yyyymmddhh24miss]，即取yyyymmddhh24miss格式的任務定時已耗用時間。
  - var5=杭州，即設定var5的值為常量，杭州。
3. 可選：配置調度時間。
  配置ODPS SQL節點的調度周期為小時調度（如地區3）。
  說明
  您可以根據實際情況選擇是否配置時間周期，本文以添加時間周期樣本。
  - 調度開始時間為16:00
  - 調度結束時間為23:59
  - 調度時間間隔為1小時。
  更多時間周期配置，詳情請參見時間屬性配置說明。
4. 設定調度依賴。
  為開發節點配置調度依賴。詳見：配置調度依賴。此處使用根節點作為本節點的上遊依賴。
在節點編輯頁面的頂部工具列，單擊及表徵圖，儲存並提交ODPS SQL節點的配置。
執行開發環境煙霧測試 (Smoke Test)。
1. 單擊表徵圖，在開發環境測試對話方塊配置業務時間，類比節點的調度周期。
  業務時間配置如下：
  - 業務日期：2025-10-16
  - 開始時間：16：00
  - 結束時間：17：00
  ODPS SQL任務為小時調度任務，則該任務在業務日期：2025-10-17的16：00、17：00時間會產生兩個執行個體。
  說明
  因為業務日期為運行日期的前一天，因此，任務實際運行日期為2025-10-17。
  16：00節點預期的取值結果如下：
  - var1=20251016。
  - var2=20251017160000。
  - var3=20251016。
  - var4=20251017160000。
  17：00節點預期的取值結果如下：
  - var1=20251016。
  - var2=20251017170000。
  - var3=20251016。
  - var4=20251017170000。
2. 單擊確認，節點按照指定時間啟動運行。
3. 已耗用時間結束後，單擊表徵圖，查看煙霧測試 (Smoke Test)日誌。
  節點產生的兩個執行個體運行成功，且節點運行結果符合預期。
若當前工作空間為標準模式，需要將節點發布至生產環境。在ODPS SQL節點編輯頁面，單擊頂部功能表列右側的發布，發布當前節點。任務的發佈動作見：節點發布。
進入營運中心，確認節點的調度參數配置。
1. 單擊DataStudio頂部功能表列右側的營運中心，進入營運中心頁面。
2. 在周期任務營運 > 周期任務介面，搜尋目標節點。
  說明
  節點發布成功後，您才能在周期任務介面搜尋到。
3. 單擊目標節點名稱，在屬性中查看執行參數。
  本次樣本中，節點的執行參數為var1=$bizdate var2=$cyctime var3=${yyyymmdd} var4=$[yyyymmddhh24miss]，符合預期。
4. 觀察執行個體實際替換情況。等待調度執行個體產生之後，單擊周期執行個體菜單，搜尋任務名稱，單擊任務執行個體名稱，在屬性中查看執行參數。
  本次樣本中，節點的執行參數為var1=20251016 var2=20251017160000 var3=20251016 var4=20251017160000，符合預期。

DataWorks：配置並使用調度參數