調度參數是DataWorks任務調度時使用的參數，可根據您配置的調度參數取值規則，在每次任務運行時自動替換為真實的取值，實現任務調度時間內參數的動態替換。本文為您介紹調度參數支持的格式及相關使用。

背景信息

您可在代碼中通過${變量名}的方式定義變量，并在調度配置 > 參數界面，通過調度參數表達式為代碼中的變量賦值，實現調度場景下的代碼動態入參。部分節點的調度參數配置存在差異（例如，通用Shell節點中的變量只能以$1、$2、$3...命名），詳情請參見各類型節點的調度參數配置示例。
說明 調度參數支持賦值常量，即每次進行任務調度時，該參數傳入同一個值。本文主要基于通過調度參數實現代碼動態入參場景進行說明。
本文為您介紹：了解調度參數支持的格式后，您可根據業務需求配置并使用調度參數，詳情請參見后續：配置及使用調度參數。

概念介紹

調度參數通常會被用于指代某些動態時間的場景，此場景下，您可基于業務日期和定時時間進行調度參數的取值設置。配置調度參數前，您可先了解這兩個時間概念，便于后續設置調度參數取值。
概念描述
業務日期

指昨天，在離線計算場景下，交易日期為業務發生的日期。DataWorks默認取調度時間內，任務預期調度運行時間的前一天（即昨天）的日期為業務日期，精確到天。例如，今天統計前一天的營業額，此處的前一天，指交易發生的日期，也就是業務日期。

定時時間

指今天，即某業務數據加工任務的預期執行時間。DataWorks默認取調度時間內，任務預期調度運行的時間點（即今天）為定時時間，精確到秒。任務預期執行時間，與實際開始執行時間并非完全一致。任務實際開始執行時間受多方因素影響。

調度參數支持的格式

通常，調度參數用于獲取不同的時間數據，您可根據業務需求，選擇基于業務日期或定時時間獲取相應時間數據。
說明 DataWorks提供了部分內置變量，其格式固定，為了使用更加靈活，建議您通過以下方式自定義時間格式。
取值方式參數格式參數示例相關參考
基于業務日期獲取時間數據。通常，使用大括號${...}，結合yyyy、yy、mm及dd自定義組合生成時間參數，獲取業務日期前后多少年、月、天。
說明 業務日期為定時時間所在日期-1。即${yyyymmdd}的取值與$[yyyymmdd-1]取值一致。
可通過${yyyymmdd}、${yyyy-mm-dd}等${...}自定義時間格式獲取，例如：
  • ${yyyymmdd±N}
  • ${yyyymmdd±7*N}
  • ${yy±N}
  • ${mm}
  • ${yyyy-mm-dd±N}
更多賦值示例，請參見自定義參數${...}。
基于定時時間獲取時間數據。通常，使用中括號$[...]，結合yyyy、yy、mm、dd、hh24、mi及ss自定義組合生成時間參數，獲取定時時間前后多少年、月、天、小時、分鐘、秒。可通過$[yyyymmddhh24miss]等$[...]自定義時間格式獲取。例如，取前一天的前一小時，參數表達式為$[yyyymmdd-1-1/24]。
調度參數無法覆蓋的場景（即通過上述表達式無法直接獲取預期格式的參數賦值），您可先通過上述方式獲取時間格式數據，再執行下表操作獲取相應時間。
場景示例操作說明相關參考
通過引擎函數將時間格式的內容加工為時間戳。在代碼中使用引擎函數獲取目標時間。調度參數返回值二次處理的典型場景
${mm}01：獲取每月1號。通過純字符串拼接，獲取目標時間。無

注意事項

  • ${…}參數相關。
    取N年前、N月前的時間數據需使用${…}參數。
    • ${…}參數只能精確到年月日，因此${…}參數不支持${yyyy-mm-dd-1/24}用法。
    • 如需對年份、月份進行計算，建議使用${…}參數。例如，${yyyy-N}、${mm-N}。
  • $[…]參數相關。
    • 取N小時前、N分鐘前的時間數據需使用$[…]參數。
      • $[…]參數基于時分秒進行替換，無法根據$[yyyy-N]、$[mm-N]時間格式獲取多少年前、多少月前的時間數據。單獨取年份、月份，請使用${…}參數。
      • 如需獲取精確到秒的時間數據時，建議使用$[…]參數。例如，$[yyyy-mm-dd-1-1/24]。
    • $[...]調度參數替換值不隨實例實際運行時間改變。

      $[...]根據實例定時時間取值，調度參數替換值在實例生成時已確定，因此調度參數的替換值不會隨著實例實際運行時間而改變。詳情請參見附錄：調度參數與業務日期、定時時間、實際運行時間的關系。

    說明
    • $[...]取小時參數時，支持取不同時間格式。
    • hh24代表根據24小時制時間格式取值，hh代表根據12小時制時間格式取值。
  • ${bizdate}變量名說明。

    部分節點代碼會自帶一個${bizdate}變量名，該變量名無特殊含義。您可根據業務需求自定義代碼中的變量名。

  • 取小時、分鐘時間的跨天問題處理。

    取多少小時、分鐘，可能存在跨天問題，跨天時間的參數處理，詳情請參見調度參數往前取一個小時，如何處理跨天參數替換的問題。

附錄：參數列表

自定義參數${...}及$[...]的功能差異，詳情請參見${…}和$[…]參數的功能差異。
  • 自定義參數${...}
    常用取值示例如下。
    日期加減周期獲取方式
    前/后N年${yyyy±N}
    前/后N月${yyyymm±N}
    前/后N周${yyyymmdd±7*N}
    前/后N天${yyyymmdd±N}
    年月日加/減N天${yyyymmdd±N}
    加/減N年（yyyy格式）${yyyy±N}年
    加/減N年（yy格式）${yy±N}年
    重要
    • 單獨獲取多少月前、多少年前等時間數據，建議使用${...}參數。
    • ${…}參數僅支持對天、月、年時間進行加減。
  • 自定義參數$[...]
    常用取值示例如下。
    時間加減周期獲取方式
    后N年$[add_months(yyyymmdd,12*N)]
    前N年$[add_months(yyyymmdd,-12*N)]
    后N月$[add_months(yyyymmdd,N)]
    前N月$[add_months(yyyymmdd,-N)]
    前/后N周$[yyyymmdd±7*N]
    前/后N天$[yyyymmdd±N]
    前/后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]
    hh24表示小時（12進制使用hh），由于$cyctime精確到時分秒，因此$[…]參數可以精確到時分秒。您可以結合引擎函數，獲取更多參數取值，詳情請參見調度參數返回值二次處理的典型場景。
    重要
    • 獲取多少小時、多少分鐘前等時間數據請使用$[...]參數。
    • 調度參數替換值在實例生成時已經確定，因此調度參數的替換值不會隨著實例實際運行時間而改變。
  • 系統內置參數
    DataWorks支持下表的系統參數，可用于設置調度參數的取值。但該方式靈活性差，建議參考上文描述，使用自定義參數的方式設置調度參數取值。
    內置參數定義
    $bizdate業務日期，格式為yyyymmdd，與自定義參數${yyyymmdd}取值一致。

    該參數的應用較為廣泛，日常調度中默認任務預期運行時間的前一天為業務日期。

    $cyctime任務的定時時間，格式為yyyymmddhh24miss，與自定義參數$[yyyymmddhh24miss]取值一致。
    $gmtdate當前日期，格式為yyyymmdd。

    該參數默認取當天日期，執行補數據操作時輸入的日期為業務日期+1。

    $bizmonth業務月份，格式為yyyymm。
    • 如果業務日期的月份與當前月份一致，則$bizmonth=業務日期月份-1。
    • 如果業務日期的月份與當前月份不一致，則$bizmonth=業務日期月份。
    $jobid任務所屬的業務流程ID。
    $nodeid節點ID。
    $taskid節點產生的實例ID。

附錄：調度參數與業務日期、定時時間、實際運行時間的關系

關系類別說明及示例
調度參數與實際運行時間的關系調度參數替換值在實例生成時已確定，因此，調度參數的替換值不會隨著實例實際運行時間的改變而產生變化。
調度參數與任務定時時間的關系當調度參數取小時、分鐘時，參數替換值由實例的定時時間決定，即由節點調度配置的定時調度時間決定。定時時間
例如，當前節點為小時調度節點，并且設置定時調度時間為00：00~23：59，每小時調度一次，則：
  • 第一個小時實例定時時間為0點，小時的參數取值為00。
  • 第二個小時實例定時時間為1點，小時的參數取值為01。
調度參數與業務日期、定時時間的關系與業務日期、定時時間關系

附錄：關于夏令時說明

DataWorks可保障在進入和退出夏令時當天，任務能夠正確運行。進入與退出夏令時切換產品側的解決方案詳情，請參見場景：夏令時切換對調度任務運行的影響。為避免夏令時切換對您任務執行造成額外理解成本，建議實施夏令時的地域優先查看此文檔。

后續：配置及使用調度參數

了解調度參數支持的時間格式后，您可基于業務需求配置并使用調度參數，詳情請參見配置并使用調度參數。