调度参数是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]。
    • $[...]调度参数替换值不随实例实际运行时间改变。

      $[...]根据实例定时时间取值，调度参数替换值在实例生成时已确定，因此调度参数的替换值不会随着实例实际运行时间而改变。详情请参见附录：调度参数与业务日期、定时时间、实际运行时间的关系。

  • ${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。
调度参数与业务日期、定时时间的关系 与业务日期、定时时间关系

附录：关于夏令时说明

夏令时支持现转实例引擎和参数分区计算在进入和退出夏令时当天能正确运行。
  • 以美国西部时间为例：进入夏令时会产生23个实例，当天3:00往前偏移10分钟的结果是1:50。
  • 以美国西部时间为例：退出夏令时会产生24个实例，当天3:00往前偏移10分钟的结果是2:50。
进入夏令时当天的日周月调度节点，如果设置的运行时间正好是被跳过的时间段，则当天生成的实例运行时间会是当天的0点整。

后续：配置及使用调度参数

了解调度参数支持的时间格式后，您可基于业务需求配置并使用调度参数，详情请参见配置并使用调度参数。