调度参数是DataWorks任务调度时使用的参数,调度参数会根据任务调度的业务时间及调度参数的取值格式自动替换取值,实现在任务调度时间内参数的动态取值。节点的调度参数需在调度配置基础属性参数中配置。本文为您介绍调度参数的主要类型、注意事项和典型的配置示例。

注意事项

  • 节点配置调度参数并发布生产环境自动调度后,调度系统会根据任务运行的业务时间自动替换调度参数的取值。但在数据开发界面测试运行时不经过调度系统,所以直接点击运行高级运行时需要给代码中的引用的调度参数手动赋值。

    例如,使用调度参数bdp.system.bizdate时,调度运行任务时此参数会被替换为当前任务运行的具体的业务时间,但是在数据开发页面通过运行按钮调测代码时,bdp.system.bizdate参数不会替换为业务时间,您需要手动为此参数设置一个具体的时间常量数据,详情可参见开发环境测试调度参数

  • 在数据开发页面测试调度参数的替换情况,请务必使用开发环境冒烟测试。详情可参见开发环境测试调度参数
  • 如果您变更了代码中的变量,或者需要重新为变量赋值常量,请务必使用高级运行

    使用高级运行时,每次运行前均需要为代码中的变量赋值常量,可保障每次运行时代码中的变量取值均为正确的赋值取值。而使用运行时,仅第一次运行时有弹窗出现需要您为变量赋值,后续运行时均不会弹出赋值弹窗,取用第一次的赋值取值,可能会导致取值错误。

  • ${…}参数$[…]参数的用法注意事项:
    • 取N小时前、N分钟前的时间数据需用$[…]参数

      ${…}参数只能精确到年月日,因此${…}参数不支持${yyyy-mm-dd-1/24}等用法。需要精确到秒时,建议使用$[…]参数,例如,$[yyyy-mm-dd-1-1/24]。

    • 取N年前、N月前的时间数据需用${…}参数

      $[…]参数不支持$[yyyy-N]、$[mm-N]等这种直接进行年月数据计算的用法。如果需要对年份、月份进行计算,建议使用${…}参数,例如,${yyyy-N}、${mm-N}。

调度参数类型概述

调度参数通过赋值方式分为 系统内置变量自定义参数(推荐)两大类。 参数类型

系统内置变量

  • 细分类型
    细分类型 定义 对比说明
    ${bdp.system.bizdate} 实例计算时对应的业务日期,业务日期默认为运行日期的前一天,默认格式为yyyymmdd 取值可精确到天。

    定时时间和业务日期的计算公式为:定时时间所在日期=业务日期+1,业务日期默认为运行日期的前一天。

    ${bdp.system.cyctime} 实例的定时运行时间,默认格式为yyyymmddhh24miss 取值可精确到小时、分钟、秒。
  • 赋值引用要求
    无需手动赋值,参数可以在代码中直接引用。 系统内置变量

自定义参数:系统内置参数

  • 细分类型
    表 1. 内置参数列表
    内置参数 定义
    $bizdate 业务日期,格式为yyyymmdd

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

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

    该参数默认为当天日期,补数据时传入的是业务日期+1

    $bizmonth 业务月份,格式为yyyymm
    • 如果业务日期的月份和当前月份一致,$bizmonth=业务日期月份-1
    • 如果业务日期的月份和当前月份不一致,$bizmonth=业务日期月份
    $jobid 任务所属的业务流程ID。
    $nodeid 节点ID。
    $taskid 任务ID,即节点实例ID。
  • 赋值引用要求(ODPS SQL节点、离线同步节点、PyODPS节点)赋值要求
    • 需要在调度配置 > 基础属性中的参数中赋值,需使用多个调度参数时,各个参数间使用一个空格分隔。
    • 赋值的格式为:key1=value1 key2=value2,其中key1key2是自定义的参数名称,value1value2是系统内置参数,DataWorks当前可用的系统内置参数列表可参见上述表格表 1
    • 引用格式为:
      • ODPS SQL节点、EMR类型节点和离线数据同步节点

        直接引用${key1}${key2},其中key1key2是自定义的参数名称。例如,dt=${key1}

      • PyODPS节点

        在全局变量中增加一个名为args的字典对象:args=['key1'] args=['key2']。其中key1key2是自定义的参数名称。

    • 赋值引用要求(通用Shell节点)
      • 赋值格式为:value1 value2,其中value1value2是系统内置参数,DataWorks当前可用的系统内置参数列表可参见上述表格表 1
      • 引用格式

        在代码中引用变量$1,$2 ...

      说明 EMR Shell节点和EMR Spark Shell节点,请参考ODPS SQL节点引用方式。

自定义参数:${…}参数

  • 参数定义
    ${...}参数是基于系统内置参数 $bizdate、自定义参数格式的时间参数。通过:
    • yyyy表示4位的年份,取值为$bizdate的年份。
    • yy表示2位的年份,取值为$bizdate的年份。
    • mm表示月,取值为$bizdate的月份。
    • dd表示天,取值为$bizdate的天。
    可以任意组合参数,例如 ${yyyy}${yyyymm}${yyyymmdd}${yyyy-mm-dd}等。
    说明 由于 $bizdate精确到年月日,因此 ${…}参数只能精确到年月日,因此 ${…}参数不支持${yyyy-mm-dd-1/24}等用法。需要精确到秒时,建议使用 $[…]参数,例如,$[yyyy-mm-dd-1-1/24]。
  • 赋值引用要求(ODPS SQL节点、离线同步节点、PyODPS节点、EMR类型节点)赋值要求
    • 需要在调度配置 > 基础属性 > 参数中进行赋值,赋值后可在代码中引用自定义参数的变量名。
    • 赋值的格式为:key1=value1 key2=value2,其中key1key2是自定义的参数名称,value1value2是自定义的日期取值。下表为常见的日期取值案例。
      日期加减周期 value值
      后N年 ${yyyy+N}
      前N年 ${yyyy-N}
      后N月 ${yyyymm+N}
      前N月 ${yyyymm-N}
      后N周 ${yyyymmdd+7*N}
      前N周 ${yyyymmdd-7*N}
      后N天 ${yyyymmdd+N}
      前N天 ${yyyymmdd-N}
      年月日加N天 ${yyyymmdd+N}
      年月日减N天 ${yyyymmdd-N}
    • 引用格式为:
      • ODPS SQL节点、EMR类型节点和离线数据同步节点

        直接引用${key1}${key2},其中key1key2是自定义的参数名称。例如,dt=${key1}

      • PyODPS节点

        在全局变量中增加一个名为args的字典对象:args=['key1'] args=['key2']。其中key1key2是自定义的参数名称。

  • 赋值引用要求(通用Shell节点)
    • 赋值格式为:value1 value2,其中value1value2是自定义的日期取值
    • 引用格式

      在代码中引用变量$1,$2 ...

    说明 EMR Shell节点和EMR Spark Shell节点,请参考ODPS SQL节点引用方式。

自定义参数:$[…]参数

  • 参数定义
    $[...]参数是基于系统内置参数 $cyctime、自定义参数格式的时间参数。通过:
    • yyyy表示4位的年份,取值为$cyctime的年份。
    • yy表示2位的年份,取值为$cyctime的年份。
    • mm表示月,取值为$cyctime的月份。
    • dd表示天,取值为$cyctime的天。
    • hh24表示小时(12进制使用hh),取值为$cyctime的小时。
    • mi表示分钟,取值为$cyctime的分钟。
    • ss表示秒,取值为$cyctime的秒。
    可以任意组合参数,例如 $[yyyymmdd]$[yyyy-mm-dd]$[hh24miss]$[hh24:mi:ss]$[yyyymmddhh24miss]等。
    说明 由于 $cyctime精确到时分秒,因此 $[…]参数可以精确到时分秒。
  • 赋值引用要求(ODPS SQL节点、离线同步节点、PyODPS节点、EMR类型节点)赋值要求
    • 需要在调度配置 > 基础属性 > 参数中进行赋值,赋值后可在代码中引用自定义参数的变量名。
    • 赋值的格式为:key1=value1 key2=value2,其中key1key2是自定义的参数名称,value1value2是自定义的日期取值。下表为常见的日期取值案例。
      时间加减周期 value取值
      后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-7*N]
      后N天 $[yyyymmdd+N]
      前N天 $[yyyymmdd-N]
      后N小时 $[hh24miss+N/24]
      前N小时 $[hh24miss-N/24]
      后N分钟 $[hh24miss+N/24/60]
      前N分钟 $[hh24miss-N/24/60]
    • 引用格式为:
      • ODPS SQL节点、EMR类型节点和离线数据同步节点

        直接引用${key1}${key2},其中key1key2是自定义的参数名称。例如,dt=${key1}

      • PyODPS节点

        在全局变量中增加一个名为args的字典对象:args=['key1'] args=['key2']。其中key1key2是自定义的参数名称。

  • 赋值引用要求(通用Shell节点)
    • 赋值格式为:value1 value2,其中value1value2是系统内置参数,DataWorks当前可用的系统内置参数列表可参见上述表格表 1
    • 引用格式

      在代码中引用变量$1,$2 ...

    说明 EMR Shell节点和EMR Spark Shell节点,请参考ODPS SQL节点引用方式。

自定义参数:常量参数

  • 分类明细:包含数字常量(例如123)和字符常量(例如"abc")。
    说明 如果需要赋值为带有空格的常量,您可以自定义两个参数,引用参数时通过空格拼接引用这两个参数和空格。
  • 赋值引用要求(ODPS SQL节点、离线同步节点、PyODPS节点)赋值要求
    • 需要在调度配置 > 基础属性 > 参数中进行赋值,赋值后可在代码中引用自定义参数的变量名。
    • 赋值格式为:key1=value1 key2=value2,其中key1key2是自定义的参数名称,value1value2是自定义的常量,如key1="abc" key2=1234
    • 引用格式为:
      • ODPS SQL节点、EMR类型节点和离线数据同步节点

        直接引用${key1}${key2},其中key1key2是自定义的参数名称。例如,dt=${key1}

      • PyODPS节点

        在全局变量中增加一个名为args的字典对象:args=['key1'] args=['key2']。其中key1key2是自定义的参数名称。

  • 赋值引用要求(Shell节点)
    • 赋值格式为:value1 value2,其中value1value2自定义的常量,如"abc" 1234
    • 引用格式

      在代码中引用变量$1,$2 ...

自定义参数应用对比

以当前时间为2019年11月01日,任务定时每天00:00运行为例,下表为各自定义参数赋值情况的对比。
参数类型 代码引用方式 调度参数赋值 调度替换值
${yyyymmdd} pt=${datetime1} datetime1=${yyyymmdd} datetime1=20191031
$[yyyymmddhh24miss] pt=${datetime2} datetime2=$[yyyymmddhh24miss] datetime2=201911010000
$bizdate(业务时间) pt=${datetime3} datetime3=$bizdate datetime3=20191031
$cyctime(定时时间,精确到分秒) pt=${datetime4} datetime4=$cyctime datetime4=20191101000000
$gmtdate(当前时间,精确到天) pt=${datetime5} datetime5=$gmtdate datetime5=20191101
$bizmonth(业务月份) pt=${datetime6} datetime6=$bizmonth 当业务时间是当前月份时,$bizmonth的值为上个月的月份。当业务时间不是当前月份时,$bizmonth的值为业务时间的月份。示例如下:
  • 如果当前时间为2019年11月01日(当前月份),则datetime6=201910
  • 如果选择的业务时间为2019年11月02日(当前月份),则datetime6=201910
  • 如果选择的业务时间2019年10月31日(非当前月份),则datetime6=201910

${…}和$[…]参数的区别

比较项 ${…}参数 $[…]参数
时间基准 $bizdate的时间为基准参与运算。$bizdate为业务日期,默认为当前时间减一天。 $cyctime的时间为基准参与运算。$cyctime为任务定时调度时间。

例如,定时时间为当天的00:30,即yyyy-mm-dd 00:30:00

补数据使用 补数据时选择的业务日期和参数替换结果保持一致。 和Oracle的时间运算方式一致。执行补数据时,参数替换结果为选择的业务日期+1天。

例如,补数据选择的业务日期为20190720,则执行时cyctime替换结果为20190721

时间精确度 精确到天 精确到秒

不支持${yyyy-mm-dd-1/24}等用法,建议使用$[yyyy-mm-dd-1-1/24]。

以当前时间为2019年07月20日10时30分00秒,使用ODPS SQL节点为例,${…}和$[…]参数的时间取值示例如下。
说明 ODPS SQL节点配置中为多个参数赋值时,需要使用空格进行分隔。例如 startdatetime=$bizdate enddatetime=${yyyymmdd+1} starttime=${yyyy-mm-dd} endtime=${yyyy-mm-dd+1}
时间 ${…}参数 $[…]参数
年份:2019年
  • 调度依赖中的参数赋值:datetime=${yyyy}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${yyyy}=2019
  • 调度依赖中的参数赋值:datetime=$[yyyy]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[yyyy]=2019
年份:19年
  • 调度依赖中的参数赋值:datetime=${yy}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${yy}=19
  • 调度依赖中的参数赋值:datetime=$[yy]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[yy]=19
年份:2018年
  • 调度依赖中的参数赋值:datetime=${yyyy-1}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${yyyy-1}=2018
不支持
月份
  • 调度依赖中的参数赋值:datetime=${mm}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${mm}=07
  • 调度依赖中的参数赋值:datetime=$[mm]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[mm]=07
日期(天)
  • 调度依赖中的参数赋值:datetime=${dd}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${dd}=19
  • 调度依赖中的参数赋值:datetime=$[dd]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[dd]=20
日期:2019年06月20日
  • 调度依赖中的参数赋值:datetime=${yyyy-mm-dd-29}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${yyyy-mm-dd-29}=2019-06-20
  • 调度依赖中的参数赋值:datetime=$[add_months(yyyymmdd,-1)]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[dadd_months(yyyymmdd,-1)]=2019-06-20
日期2019年07月19日
  • 调度依赖中的参数赋值:datetime=${yyyy-mm-dd}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${yyyy-mm-dd}=2019-07-19
  • 调度依赖中的参数赋值:datetime=$[yyyy-mm-dd-1]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[yyyy-mm-dd-1]=2019-07-19
日期:2018年07月20日
  • 参数赋值:datetime=${yyyy-mm-dd-364}
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=${yyyy-mm-dd}=2019-07-20
  • 调度依赖中的参数赋值:datetime=$[add_months(yyyymmdd,-12*1)]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[dadd_months(yyyymmdd,-12*1)]=2018-07-20
时间:10:30:00 不支持
  • 调度依赖中的参数赋值:datetime=$[hh24:mi:ss]
  • 代码中引用:pt=${datetime}
  • 参数实际替换结果:pt=$[hh24:mi:ss]=10:30:00
时间:2019-07-20 10:30:00 不支持
  • 调度依赖中的参数赋值:

    需要自定义两个参数datetime1和datetime2,两个参数间使用一个空格分隔。

    datetime1=$[yyyy-mm-dd] datetime2=$[hh24:mi:ss]
  • 代码中引用:pt=${datetime1} ${datetime2}
  • 参数实际替换结果:
    • datetime1=$[yyyy-mm-dd]=2019-07-20
    • datetime2=$[hh24:mi:ss]=10:30:00
    则pt=2019-07-20 10:30:00
时间:2019-07-20 10:29:00 不支持
  • 调度依赖中的参数赋值:

    需要自定义两个参数datetime1和datetime2,两个参数间使用一个空格分隔。

    datetime1=$[yyyy-mm-dd] datetime2=$[hh24:mi:ss-1/24/60]
  • 代码中引用:pt=${datetime1} ${datetime2}
  • 参数实际替换结果:
    • datetime1=$[yyyy-mm-dd]=2019-07-20
    • datetime2=$[hh24:mi:ss-1/24/60]=10:29:00
    则pt=2019-07-20 10:29:00
时间:2019-07-20 08:30:00 不支持
  • 调度依赖中的参数赋值:

    需要自定义两个参数datetime1和datetime2,两个参数间使用一个空格分隔。

    datetime1=$[yyyy-mm-dd] datetime2=$[hh24:mi:ss-1/24]
  • 代码中引用:pt=${datetime1} ${datetime2}
  • 参数实际替换结果:
    • datetime1=$[yyyy-mm-dd]=2019-07-20
    • datetime2=$[hh24:mi:ss-1/24]=08:30:00
    则pt=2019-07-20 08:30:00

不同类型节点使用调度参数示例

  • ODPS SQL节点、离线数据节点示例、EMR类型节点使用示例。赋值
    • 如果使用系统调度参数,无需在右侧的调度配置界面为变量赋值,在代码中直接引用系统参数即可。
    • 如果使用自定义参数,需要在右侧的调度配置界面以变量名=自定义参数的方式为变量赋值,在代码中引用变量名。
  • PyODPS节点示例。

    为避免侵入代码,PyODPS节点不会在代码中替换${param_name}的字符串,但会在执行代码前,在全局变量中增加一个名为args的字典对象,调度参数可以在此获取。

    例如,在节点的 调度配置 > 基础属性 > 参数中,输入 def=${yyyymmdd},则可以通过下图的方式在代码中获取该参数。 PyODPS
  • 通用Shell节点示例。Shell

    Shell节点中的变量不允许自定义命名,只能以$1,$2,$3...命名。参数到达第10个后,请使用${10}的方式声明变量。

开发环境测试调度参数

使用调度参数时,在数据开发阶段,您可以数据开发页面使用冒烟测试,确认参数的取值是否是预期的取值,测试时您需要手动替换参数为常量。
  • 使用冒烟测试
    您可以单击代码编辑页面的 在开发环境进行冒烟测试,通过手动输入业务日期模拟节点自动调度的场景,获取当前业务日期下调度参数的替换值,通过冒烟测试的结果检查确认调度参数的取值是否是预期的取值。 开发环境冒烟测试
    说明
    • 在开发环境进行冒烟测试时,每次修改调度参数后,都需要重新保存、提交至开发环境,代码才会更新。
    • 在开发环境进行冒烟测试时,会生成实例产生实例费。
  • 手动替换参数
    任务在数据开发界面 运行(①)或 高级运行(②),都不会根据页面右侧的参数配置来替换调度参数,您需要手动为代码中的变量(③或④)赋值 常量手动赋值

在运维中心页面查看参数替换情况

节点的任务代码完成开发提交发布后,在周期任务中,周期实例中的调度参数在实例生成时已经进行替换,您可以在运维中心 > 周期运维任务 > 周期任务页面查看节点的调度参数取值是否正确。

如果您在数据开发页面修改、提交了调度参数,并发布至生产环境,请首先检查周期任务中的执行参数是否符合预期。

常见问题