調度參數是DataWorks的核心功能，用於在任務自動調度時動態替換代碼中的時間參數。它解決了在週期性任務中寫入程式碼日期的維護難題，使商務程序能自動適配不同的業務日期和執行時間。本文為您介紹調度參數的參數值支援的格式及相關使用。
閱讀此文檔前，請先閱讀並理解調度參數的配置方式，參見： 配置並使用調度參數。
核心概念：時間基準
時間參數是調度參數的主要應用情境，可用於在任務運行時動態替換各種時間字串。DataWorks的所有動態時間參數都基於以下兩種核心的時間基準。
概念 | 定義 | 預設參數值 | 自訂格式 | 時間精度 |
業務日期 | 指任務定時運行日期的前一天。在T+1的離線計算情境中，它代表需要處理的業務資料的發生日期。 例如，今天統計前一天的營業額，此處的前一天，指交易發生的日期，也就是業務日期。 |
|
| 年月日 |
定時時間 | 指任務在調度配置中設定的調度時間。在任務運行時會被系統替換為任務執行個體啟動並執行當天，是任務的理論運行時刻，不隨實際運行時的資源排隊或延遲而位移。 |
|
| 年月日時分秒 |
概念等價總結：
業務日期 ≈ 昨天 （資料的日期）
定時時間 ≈ 今天 （任務啟動並執行時間）
一個典型的T+1任務就是：在今天（定時時間）的淩晨，啟動一個任務，去處理昨天（業務日期）的資料。
參數值運算式
調度參數支援多種賦實值型別，包括：
自訂時間參數：如
${...}和$[...]，可在兩種時間基準值（業務日期和定時時間）的基礎上進行變換，詳見：自訂時間參數。系統內建參數：如
$bizdate、$bizmonth、$jobid，可用於擷取業務日期、業務月份、商務程序ID等，不局限於時間類型。詳見：系統內建參數。常量：如
'123'，'abc'等。
特殊字元限制：參數運算式不支援填寫空格和=。
基本使用原則
調度參數通過在中定義參數名和參數值來確定賦值邏輯，定義完成後即可在代碼中，通過${參數名}的方式來引用。更詳細的參數配置流程見：配置並使用調度參數。
業務日期和定時時間可以通過系統內建參數
$bizdate和$cyctime直接填入參數值，在取值上：$bizdate=${yyyymmdd}$cyctime=$[yyyymmddhh24miss]
以上為$bizdate與${yyyymmdd}、$cyctime與$[yyyymmddhh24miss]的參數定義和業務日期為2025-10-16時的預覽結果。
若基準時間的參數值不滿足要求，也可以通過
${...}和$[...]進行自訂時間參數，自訂時間參數可在兩種基準時間的基礎上進行變換。
自訂時間參數
DataWorks支援通過${...}和$[...]來擷取業務時間和定時時間，並支援通過以下幾種類型，對時間進行靈活變換，以符合業務需要。以節點配置的調度時間為天調度，調度時間02:30:45為例。假設業務日期為20251031，以下是基準時間：
業務日期：${yyyymmdd}的取值為20251031。
定時時間：$[yyyymmddhh24miss]的取值為20251101023045。
${...} 與 $[...] 的核心區別
${...} 和 $[...] 兩種格式在時間基準和計算能力上存在本質區別，混用這兩種格式將導致資料錯誤。
對比維度 |
|
|
時間基準 | 業務日期（T-1） | 定時時間（T） |
時間精度 | 天 （年月日） | 秒 （年月日時分秒） |
位移計算能力 | 支援對 年、月、周、天 進行位移計算。 | 支援對 天、小時、分鐘 進行位移計算。 |
核心限制 | 不支援時、分、秒等更小時間單位的格式化與位移計算。 | 不支援通過 |
等價系統參數 |
|
|
時間格式化
使用大括弧${...}或$[...]，結合yyyy、yy、mm及dd自訂群組合產生時間參數，擷取業務日期前後多少年、月、天。
代碼 | 描述 |
|
| ||
賦值方式 | 結果 | 賦值方式 | 結果 | ||
| 4位年份 |
|
|
|
|
| 2位月份 |
|
|
|
|
| 2位日期 |
|
|
|
|
| 24小時制小時 | 不支援（精度為天） | - |
|
|
| 12小時制小時 | - |
|
| |
| 分鐘 | - |
|
| |
| 秒 | - |
|
| |
| 取年月 |
|
|
|
|
| 格式化為用“-”拼接 |
|
|
|
|
| 格式化為用“-”拼接，並帶時分秒 | 不支援（精度為天） | - | 支援方式見字串拼接：方案2。 | |
位移計算
位移計算是動態參數的核心，可基於業務日期或定時時間進行前後加減。如在時間基準的基礎上實現擷取前後N年、月、日，或N小時、分鐘（小時分鐘僅支援定時時間）的時間計算。${...}和$[...]由於時間基準的精度不同，可支援的範圍也不一樣。
${...}模式的位移計算核心能力：支援對年、月、周、天進行整數位移。
重要不支援時、分的位移計算。即不支援${yyyy-mm-dd-1/24}等用法。
文法：
${<時間格式><±N>}，N對應時間格式的最小單位。如格式為yyyymm，則N的單位對應mm（月）；如格式為yyyymmdd，則格式對應dd（天）。日期加減周期
位移單位
擷取方式
舉例
前/後N年
年
${yyyy±N}或${yy±N}取上一年：
${yyyy-1}前/後N月
月
${yyyymm±N}取上個月：
${yyyymm-1}前/後N周
周
${yyyymmdd±7*N}取上周：
${yyyymmdd-7*1}前/後N天
天
${yyyymmdd±N}取前天：
${yyyymmdd-1}
$[...]模式的位移計算核心能力：支援對天、小時、分鐘進行分數位移。
重要$[...]無法根據$[yyyy-N]、$[mm-N]時間格式擷取多少年前、多少月前的時間資料。如需對年月進行位移計算，需用add_months函數來支援年月位移。文法：
$[<時間格式><±N>]，其中小時位移使用N/24 ，分鐘位移使用N/24/60，N為需要位移的小時或分鐘數。需求
位移單位
擷取方式
舉例
前/後 N 年
年
$[add_months(yyyymmdd,12*N)]（後N年）$[add_months(yyyymmdd,-12*N)]（前N年）取上一年：
$[add_months(yyyymmdd,-12)]前/後 N 月
月
$[add_months(yyyymmdd,N)]（後N月）$[add_months(yyyymmdd,-N)]（前N月）取上個月：
$[add_months(yyyymmdd,-1)]前/後 N 周
周
$[yyyymmdd±7*N]取上周：
$[yyyymmdd±7*1]前/後 N 天
天
$[yyyymmdd±N]取昨天：
$[yyyymmdd-1]前/後 N 小時
小時
可用格式：
$[hh24miss±N/24]、$[hh24±N/24]$[自訂時間格式±N/24]。
不同時間格式的取前一個小時：
取月：
$[mm-1/24]。取年：
$[yyyy-1/24]。取年月：
$[yyyymm-1/24]。取年月日：
$[yyyymmdd-1/24]。取前一天且前一小時：
$[yyyymmdd-1-1/24]
前/後 N 分鐘
分鐘
可用格式：
$[hh24miss±N/24/60]$[yyyymmddhh24miss±N/24/60]$[mi±N/24/60]$[自訂時間格式±N/24/60]
不同時間格式的取定時時間的前15分鐘：
$[yyyy-15/24/60]$[yyyymm-15/24/60]$[yyyymmdd-15/24/60]$[hh24-15/24/60]$[mi-15/24/60]
複雜組合位移
天+小時
$[yyyymmdd±N±M/24]，N為天位移量，M為小時位移量。樣本：擷取前一天的前一小時 →
$[yyyymmdd-1-1/24]說明執行小時分鐘的位移計算時，可能存在跨天問題。跨天時間的參數處理方式，詳情請參見調度參數往前取一個小時，如何處理跨天參數替換的問題。
對月末日期執行月位移計算時，若目標月份沒有對應日期，結果將自動校準為該月的最後一天。例如：當前為2025-03-31，執行減1月位移操作，由於2月沒有31號，取值為2025-02-28。
通過引擎函數二次變換
當調度參數的內建格式化和位移無法直接產生最終需要的值時（如擷取上月的最後一天），可通過使用目標節點的計算引擎內建的函數或通過賦值節點在調用參數時，對時間參數進行二次變換。
參考：調度參數傳回值二次處理的典型情境。
字串拼接
此方法用於構建內建文法不支援的、但有規律的日期文字。它將調度參數產生的日期部分與固定的常量字串進行組合。
案例1：動態擷取每月的第一天。
情境：無論任務在哪天運行，都需要一個代表當月第一天的字串，格式為
yyyymm01。實現：
提取年月部分：使用
${yyyymm}擷取當前業務日期的年月部分（例如，如果業務日期是20231027，則結果為202310）。拼接常量：將提取出的年月與字串
'01'進行拼接。參數調用：
first_day_of_month=${yyyymm}01
結果：當任務運行時，
${first_day_of_month}將被替換為20231001。
案例2：擷取yyyy-mm-dd hh24:mi:ss格式的時間。
情境：擷取一個
yyyy-mm-dd hh24:mi:ss格式的時間，如：2023-11-01 02:30:45。實現：
設定兩個參數：分別為
datetime1和datetime2，並且分別賦值為datetime1=$[yyyy-mm-dd]，datetime2=$[hh24:mi:ss-1/24/60]。拼接參數：將
datetime1和datetime2通過空格拼接。參數調用：pt=
${datetime1}${datetime2}。
結果：當任務運行時，
${datetime1}${datetime2}將被替換為：2023-11-01 02:30:45。
系統內建參數
DataWorks支援以下系統參數，可用於配置調度參數的取值。但該方式靈活性差，時間格式固定，建議優先使用支援靈活變換的自訂時間參數。
內建參數 | 定義 |
$bizdate | 業務日期，格式為 該參數的應用較為廣泛，日常調度中預設任務預期已耗用時間的前一天為業務日期。 |
$cyctime | 任務的定時時間，格式為 |
$gmtdate | 當前日期，格式為 該參數預設取當天日期，執行補資料操作時輸入的日期為 |
$bizmonth | 業務月份，格式為
|
$jobid | 任務所屬的商務程序ID。 |
$nodeid | 節點ID。 |
$taskid | 節點產生的執行個體ID。 |
實際情境下的參數替換樣本
調度參數的替換值在執行個體產生時即被固定，與執行個體的實際啟動時間無關。此原則適用於所有情境。
情境一：正常調度
在常規的自動調度情境下，參數的替換邏輯與其兩大時間基準（業務日期和定時時間）直接對應。
${...}(業務日期)：其值由執行個體自身的“業務日期”決定。$[...](定時時間)：其值由執行個體自身的“定時時間”決定。
樣本：假設一個天調度任務A，定時時間為每天 00:00，並配置了兩個參數：
yesterday=${yyyymmdd}today=$[yyyymmddhh24miss]
對於其中一個執行個體的替換邏輯如下表所示：
執行個體的定時時間 | 執行個體的業務日期 | 參數：yesterday=${yyyymmdd} | 參數：today=$[yyyymmddhh24miss] |
|
|
|
|
情境二：補資料
在手動執行補資料操作時，參數的替換會根據“手動選擇的業務日期”發生變化，尤其定時時間
${...}（業務日期）：其基準時間為手動選擇的業務日期。$[...]（定時時間）：其基準時間為手動選擇的業務日期+1天。
樣本：假設對上述同一個任務A，手動執行補資料，選擇的業務日期為 2025-03-15。
手動選擇的業務日期 | 參數：yesterday=${yyyymmdd} | 參數：today=$[yyyymmddhh24miss] |
|
|
|
常見問題
使用調度參數的常見問題參見：調度參數常見問題。