调度参数是DataWorks任务调度时使用的参数,调度参数会根据任务调度的业务日期、定时时间及参数的取值格式自动替换为具体的值,实现在任务调度时间内参数的动态替换。本文为您介绍调度参数的相关概况。

您可以通过以下内容了解调度参数:
  • 调度参数是根据任务调度的业务日期、定时时间进行参数取值,其取值定义详情请参见参数取值定义
  • 调度参数通过赋值方式可分为自定义参数系统内置变量两大类,详情请参见参数分类
  • 调度参数的具体参数列表,详情请参见参数列表

了解调度参数后,您可以进入调度配置界面进行参数的实际配置与使用,详情请参见配置及使用调度参数

另外,DataWorks为您提供了调度参数常用场景的相关示例:

参数取值定义

调度参数的取值定义如下表所示。
参数取值 描述
业务日期 指在调度时间内,任务预期调度运行时间的前一天(即昨天),精确到天。业务日期可通过$bizdate${yyyymmdd}获取。通常,业务日期为定时时间所在日期-1
定时时间 指在调度时间内,任务预期调度运行的时间点(即今天),精确到秒。定时时间可通过$cyctime$[yyyymmddhh24miss]获取。

参数分类

调度参数通过赋值方式分为自定义参数系统内置变量两大类。
  • 系统内置变量:在代码中直接获取业务日期与定时时间。
  • 自定义参数:支持您在代码中根据业务需求自定义变量名称,再通过调度配置 > 参数赋值区域,统一为代码中的变量赋值自定义的调度参数格式,从而动态获取不同格式的时间参数。
具体如下图所示。调度参数
说明
  • 常用类型节点均可按照上图方式定义参数并为参数赋值。通用Shell节点、Pyodps节点使用的调度参数有部分差异,详情请参见各类型节点的调度参数配置示例
  • 部分节点不支持使用调度参数,例如,HTTP触发式节点。各类型的节点是否支持使用调度参数,具体请以对应节点的帮助文档为准。
  • 自定义参数
    DataWorks支持赋值的自定义参数类别如下表所示。
    参数类别 描述 参数格式 说明
    系统内置参数 支持在赋值区域为变量赋值$bizdate$cyctime来获取业务时间与定时时间。 格式固定。
    • $bizdate的格式为yyyymmdd
    • $cyctime的格式为yyyymmddhh24miss
    不涉及
    ${..}参数 基于系统内置参数$bizdate,通过yyyyyymmdd自定义组合而生成的时间参数。 可自定义格式。

    例如,${yyyy}${yyyymm}${yyyymmdd}${yyyy-mm-dd}等。

    说明 $bizdate的取值与${yyyymmdd}一致。
    • 取N年前、N月前的时间数据需要使用${…}参数。
      说明
      • ${…}参数只能精确到年月日,因此${…}参数不支持${yyyy-mm-dd-1/24}用法。
      • 如果需要对年份、月份进行计算,建议使用${…}参数。例如,${yyyy-N}${mm-N}
    • 取N小时前、N分钟前的时间数据需要使用$[…]参数。
      说明
      • $[…]参数不支持获取$[yyyy-N]$[mm-N]等时间数据。此处N指年、月,即$[…]参数不支持通过此格式直接获取多少年前,多少月前等时间数据。
      • 如果需要获取精确到秒的时间数据时,建议使用$[…]参数。例如,$[yyyy-mm-dd-1-1/24]
    调度参数配置完成后,您可以参考测试调度参数测试调度参数来测试参数配置是否正确。
    $[...]参数 基于系统内置参数$cyctime,通过yyyyyymmddhh24miss自定义组合而生成的时间参数。 可自定义格式。

    例如,$[yyyymmdd]$[yyyy-mm-dd]$[hh24miss]$[hh24:mi:ss]$[yyyymmddhh24miss]等。

    说明 $cyctime的取值与$[yyyymmddhh24miss]一致。
    常量 支持在赋值区域为变量赋值常量。例如,"abc"1234 无固定格式。 不涉及
    自定义参数取值格式对比示例,详情请参见自定义参数取值差异对比
  • 系统内置变量
    DataWorks支持的统内置变量如下表所示。
    参数类别 参数格式 说明
    业务日期:${bdp.system.bizdate} 固定格式:yyyymmdd 无需手动赋值,参数可以在代码中直接引用。
    定时时间:${bdp.system.cyctime} 固定格式:yyyymmddhh24miss
    说明 仅公共云和专有云支持上述两个参数。

参数列表

  • 系统内置参数
    DataWorks支持的系统内置参数如下表所示。
    内置参数 定义
    $bizdate 业务日期,格式为yyyymmdd

    该参数的应用较为广泛,日常调度中默认任务预期运行时间的前一天为业务日期。

    $cyctime 任务的定时时间,格式为yyyymmddhh24miss
    $gmtdate 当前日期,格式为yyyymmdd

    该参数默认取当天日期,执行补数据操作时输入的日期为业务日期+1

    $bizmonth 业务月份,格式为yyyymm
    • 如果业务日期的月份与当前月份一致,则$bizmonth=业务日期月份-1
    • 如果业务日期的月份与当前月份不一致,则$bizmonth=业务日期月份
    $jobid 任务所属的业务流程ID。
    $nodeid 节点ID。
    $taskid 节点产生的实例ID。
  • 自定义参数${...}
    根据业务日期的系统内置参数$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}年
    其中:
    • yyyy:表示4位的年份,取值为$bizdate的年份。
    • yy:表示2位的年份,取值为$bizdate的年份。
    • mm:表示月份,取值为$bizdate的月份。
    • dd:表示天,取值为$bizdate的天。
    说明
    • 获取多少月多少年前等时间数据请使用${...}参数。
    • 由于$bizdate只支持精确到天,因此${…}参数仅支持取值到天。
    • 您可以结合引擎函数,获取更多参数取值,详情请参见调度参数返回值二次处理的典型场景
  • 自定义参数$[...]
    根据任务定时时间的系统内置参数$cyctime(今天)获取以下时间周期的取值。
    时间加减周期 获取方式
    后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]
    • $[自定义时间格式±N/24]。例如,$[hh24±N/24]
    前/后N分钟 获取该时间数据包含如下两种方式:
    • $[hh24miss±N/24/60]
    • $[自定义时间格式±N/24/60]。例如,$[mi±N/24/60]$[yyyymmddhh24miss±N/24/60]
    其中:
    • yyyy:表示4位的年份,取值为$cyctime的年份。
    • yy:表示2位的年份,取值为$cyctime的年份。
    • mm:表示月份,取值为$cyctime的月份。
    • dd:表示天,取值为$cyctime的天。
    • hh24:表示小时(12进制使用hh),取值为$cyctime的小时。
    • ss:表示秒,取值为$cyctime的秒。
    • mi:表示分钟,取值为$cyctime的分钟。
    说明
    • 获取多少小时多少分钟前等时间数据请使用$[...]参数。
    • 由于$cyctime精确到时分秒,因此$[…]参数可以精确到时分秒。
    • 您可以结合引擎函数,获取更多参数取值,详情请参见调度参数返回值二次处理的典型场景
    • 调度参数替换值在实例生成时已经确定,所以调度参数的替换值不会随着实例实际运行时间的改变而改变。
    • 当调度参数取小时、分钟时,参数替换值由实例的定时时间决定,即由节点调度配置的定时调度时间决定。
      如下示例:
      • 如果当前节点为日调度节点,并且设置定时调度时间为01:00,则小时的参数取值为01
      • 如果当前节点为小时调度节点,并且设置定时调度时间为00:00~23:59,每小时调度一次,则:
        • 第一个小时实例定时时间为0点,小时的参数取值为00
        • 第二个小时实例定时时间为1点,小时的参数取值为01
        • 以此类推。