常见的数据研发场景中,各类型节点的代码需要根据调度周期动态赋值(例如日期时间),替换变量后再进行计算。DataWorks的调度参数配置功能可以满足该业务场景的需求。

背景信息

仅在调度运行任务时,调度参数才会被替换。任务在数据开发界面运行(①)或高级运行(②),都不会根据页面右侧的参数配置来替换调度参数,您需要手动为代码中的变量(③或④)赋值常量手动赋值
如果您需要测试调度参数的替换情况,请务必使用开发环境冒烟测试,详情请参见测试调度参数开发环境测试
如果您变更了代码中的变量,或者需要重新为变量赋值,请务必使用高级运行高级运行
您在配置参数后,即可赋予周期调度运行的任务自动解析出所需值。目前参数分为系统参数和自定义参数(推荐)两大类。
说明

参数类型

目前调度参数支持系统内置变量和自定义参数:
  • 系统内置变量可以在代码中直接使用,包括${bdp.system.bizdate}${bdp.system.cyctime}
  • 自定义参数需要在调度参数赋值处,给该变量赋值自定义参数后,在代码中调用变量名。
调度参数分类如下。调度参数分类
参数类型 适用节点 调用方式 参数赋值 参数编辑框示例
系统内置变量 :主要包括业务时间bdp.system.bizdate和定时时间bdp.system.cyctime 所有节点 在代码中引用变量${bdp.system.bizdate}${bdp.system.cyctime} 无需赋值
非系统参数:自定义参数(推荐使用) ODPS SQL节点和数据同步节点 在代码中引用${key1}${key2} 调度参数赋值:key1=value1 key2=value2 赋值示例如下:
  • 常量参数赋值:key1="abc" key2=1234
  • 变量参数赋值:key1=${yyyymmdd}--取业务时间

    key2=$[yyyymmddhh24:mi:ss]--取定时时间

PyODPS节点 全局变量中增加一个名为args的字典对象:args=['key1'] args=['key2']。其中key1key2为变量名。
Shell节点 在代码中引用变量$1,$2 ... 调度参数赋值:value1 value2 赋值示例如下:
  • 常量参数赋值:"abc" 1234
  • 变量参数赋值:${yyyymmdd}---取业务时间

    $[yyyymmddhh24:mi:ss]---取定时时间

下图以ODPS SQL节点为例,为您展示如何为系统参数和自定义参数的赋值情况,以及如何在代码中进行调用。其中左侧区域为代码调用区,右侧区域为参数赋值区。赋值

自定义参数需要在调度配置 > 基础属性 > 参数中进行赋值。调度参数使用注意事项如下:

例如,time①=②$[yyyymmdd③hh24:mi:ss]time1=$[yyyymmdd] ④time2=$[hh24:mi:ss](①②③④为空格所在位置)。
注意
  • 调度参数的等号(=)两端不可以加空格,即示例中的①②处。
  • 调度参数赋值中不支持空格,即示例中的③处。
  • 两个调度参数间用一个空格分隔,即示例中的④处。

系统参数

DataWorks提供了两个系统参数,定义如下:
  • ${bdp.system.cyctime}:定义为一个实例的定时运行时间,默认格式为yyyymmddhh24miss

    仅运行时间可以取值到具体的小时、分钟,取值与自定义参数cyctime一致。

  • ${bdp.system.bizdate}:定义为一个实例计算时对应的业务日期,业务日期默认为运行日期的前一天,默认格式为yyyymmdd。取值与自定义参数bizdate一致。

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

自定义参数

调度参数赋值支持的自定义参数包括常量系统内置参数(bizdate和cyctime等)${…}$[…]
说明 不同节点类型在代码中引用参数的方式请参见上文的 参数类型
系统内置参数(bizdate和cyctime)${…}$[…]的说明如下:
  • 系统内置参数列表
    参数 描述
    $jobid 任务所属的业务流程ID。使用示例:jobid=$jobid
    $nodeid 节点ID。使用示例:nodeid=$nodeid
    $taskid 任务ID,即节点实例ID。使用示例:taskid=$taskid
    $bizdate 业务日期,格式为yyyymmdd

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

    $cyctime 任务的定时时间,格式为yyyymmddhh24miss

    如果未给天任务定时,则默认定时时间为当天0点整(精确到时分秒,通常小时、分钟级调度任务使用)。使用示例:cyctime=$cyctime

    $gmtdate 当前日期,格式为yyyymmdd

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

    $bizmonth 业务月份,格式为yyyymm
    • 如果业务日期的月份和当前月份一致,$bizmonth=业务日期月份-1
    • 如果业务日期的月份和当前月份不一致,$bizmonth=业务日期月份
  • ${...}自定义参数

    根据$bizdate参数自定义时间格式,其中yyyy表示4位的年份、yy表示2位的年份、mm表示月、dd表示天。您可以任意组合参数,例如${yyyy}${yyyymm}${yyyymmdd}${yyyy-mm-dd}等。

    $bizdate精确到年月日,因此${……}自定义参数只能表示到年月日级别。

    下表为获取加减周期的方法。
    获取加减周期 方法
    后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}
    (yyyy)加N年 ${yyyy+N}年
    (yyyy)减N年 ${yyyy-N}年
    (yy)加N年 ${yy+N}年
    (yy)减N年 ${yy-N}年
  • $[...]自定义参数

    根据$cyctime参数自定义时间格式,其中yyyy表示4位的年份、yy表示2位的年份、mm表示月、dd表示天、hh24表示小时(12进制使用hh)、mi表示分钟、ss表示秒。您可以任意组合参数,例如$[yyyymmdd]$[yyyy-mm-dd]$[hh24miss]$[hh24:mi:ss]$[yyyymmddhh24miss]等。

    $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-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节点为例,为您介绍在节点编辑页面右侧调度配置模块,进行参数赋值时支持的参数赋值方式。

    例如,当前时间为2019年11月1日,任务定时每天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月1日(当前月份),则datetime6=201910
    • 如果选择的业务时间为2019年11月2日(当前月份),则datetime6=201910
    • 如果选择的业务时间2019年10月31日(非当前月份),则datetime6=201910

$[]和${}自定义参数的区别

  • $bizdate:业务日期,默认为当前时间减一天。
  • $cyctime:任务定时调度时间。如果未给天任务定时,则默认定时时间为当天0点整(精确到时分秒,通常小时、分钟级调度任务使用)。

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

  • 如果{}参数,则以bizdate为基准参与运算,补数据时选择的业务日期和参数替换结果保持一致。
  • 如果是[]参数,则以cyctime为基准参与运行,和Oracle的时间运算方式一致。执行补数据时,参数替换结果为选择的业务日期+1天。

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

$cyctime=20190720103000为例:
  • $[yyyy]=2019, $[yy]=19, $[mm]=07, $[dd]=20, $[yyyy-mm-dd]=2019-07-20, $[hh24:mi:ss]=10:30:00, $[yyyy-mm-dd] $[hh24:mi:ss]=2019-07-20 10:30:00
  • $[hh24:mi:ss-1/24]=09:30:00
  • $[yyyy-mm-dd] $[hh24:mi:ss-1/24/60]=2019-07-20 10:29:00
  • $[yyyy-mm-dd] $[hh24:mi:ss-1/24] = 2019-07-20 09:30:00
  • $[add_months(yyyymmdd,-1)]=2019-06-20
  • $[add_months(yyyymmdd,-12*1)]=2018-07-20
  • $[hh24]=10
  • $[mi]=30
${}自定义参数示例如下:
  • ODPS SQL节点代码中pt=${datetime},节点调度参数配置为datetime=${yyyy-mm-dd}。假设运行日期是2019年7月20日,则节点执行时${yyyy-mm-dd}替换的时间为pt=2019-07-19
  • ODPS SQL节点代码中pt=${datetime},节点调度参数配置为datetime=${yyyymmdd-2}。假设运行日期是2019年7月20日,则节点执行时${yyyymmdd-2}替换的时间为pt=20190717
  • ODPS SQL节点代码中pt=${datetime},节点调度参数配置为datetime=${yyyymm-2}。假设运行日期是2019年7月20日,则节点执行时${yyyymm-2}替换的时间为pt=201905
  • ODPS SQL节点代码中pt=${datetime},节点调度参数配置为datetime=${yyyy-2}。假设运行日期是2019年7月20日,则节点执行时${yyyy-2}替换的时间为pt=2017

ODPS SQL节点配置中为多个参数赋值时,需要使用空格进行分隔。例如startdatetime=$bizdate enddatetime=${yyyymmdd+1} starttime=${yyyy-mm-dd} endtime=${yyyy-mm-dd+1}

您可以通过业务时间维度查看${}$[]自定义参数的区别,详情请参见自定义参数的区别

测试调度参数

您在节点编辑页面单击运行高级运行,设置的变量值都会直接赋值给代码中的变量,不能校验右侧调度配置模块中配置的参数是否符合预期。

因为调度参数在进行调度时,才会自动替换。如果您需要在页面直接进行测试,请单击节点编辑页面的在开发环境进行冒烟测试图标。通过手动输入业务日期模拟节点自动调度的场景,获取当前业务日期下调度参数的替换值。开发环境冒烟测试
说明
  • 在开发环境进行冒烟测试时,每次修改调度参数后,都需要重新保存、提交至开发环境,代码才会更新。
  • 在开发环境进行冒烟测试时,会生成实例产生实例费。

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

  1. 在当前页面,单击左上角的图标图标,选择全部产品 > 运维中心
  2. 在左侧导航栏,单击周期运维任务 > 周期任务

您可以在周期任务页面查看相应节点在生产环境的依赖关系、调度配置等状态。

每次发布节点至生产环境后,您可以该页面查看节点的配置是否符合预期。例如,查看调度参数的取值情况。

在周期任务中,您可以检查周期任务每天生成的周期实例,查看实例的调度参数替换值是否符合预期。周期实例中的调度参数在实例生成时已经进行替换,如果业务逻辑获取数据时出现问题,请右键单击实例名称,选择节点详情查看上下游节点参数的替换情况。

如果您在数据开发页面修改、提交了调度参数,并发布至生产环境,请首先检查周期任务中的执行参数是否符合预期。
注意
  • 请勿重跑已经运行成功或失败的实例,修改调度参数后需要重新生成实例。
  • 如果是发布后即时生成的实例修改了调度周期,该任务在生产环境未运行的实例会被替换,调度参数为该节点在生产环境最新的调度参数。详情请参见实时转实例

不同节点的引用示例

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

    配置Shell节点参数的操作和ODPS SQL一致,只是规则不同。

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

  • 为避免侵入代码,PyODPS节点不会在代码中替换${param_name}的字符串,但会在执行代码前,在全局变量中增加一个名为args的字典对象,调度参数可以在此获取。
    例如,在节点的调度配置 > 基础属性 > 参数中,输入def=${yyyymmdd},则可以通过下图的方式在代码中获取该参数。PyODPS