常见的数据研发场景中,各类型的任务代码不是一次性写入后便持续不变地进行调用。需要根据需求变化、时间变化等,动态传入某些值(例如日期时间),替换变量后再进行计算。

DataWorks的参数配置功能可以满足该业务场景的需求。您在配置参数后,即可赋予周期调度运行的任务自动解析出所需值。目前参数分为系统参数和自定义参数(推荐)两大类。

说明 如果您是初次接触参数配置,建议您首先观看DataWorks V2.0数据开发功能与用法解析视频进行学习。

参数类型

参数类型 调用方式 适用类型 参数编辑框示例
系统参数 :主要包括bdp.system.bizdatebdp.system.cyctime 在调度系统中运行时,无需在编辑框设置,可以直接在代码中引用 ${bdp.system.bizdate}${bdp.system.cyctime},系统将自动替换这两个参数的取值。 全部节点类型
非系统参数:自定义参数(推荐使用) 在代码中引用${key1}和${key2},然后在参数编辑框中进行设置。例如“key1=value1 key2=value2” 非Shell节点类型
  • 常量参数param1=”abc” param2=1234
  • 变量参数param1=$[yyyymmdd],结果将基于bdp.system.cyctime的取值计算。
在代码中引用$1、$2和$3, 然后在参数编辑框中进行设置。例如“value1 value2 value3” Shell节点类型
  • 常量参数”abc” 1234
  • 变量参数$[yyyymmdd],结果将基于bdp.system.cyctime的取值计算。

由上表可见,自定义参数中的变量参数类型的取值基于系统参数。您可以灵活地通过自定义变量参数,来定义获取的部分与格式。对于非系统参数,括号使用区别如下:

  • 大括号{ }:对应业务时间,例如{yyyymmdd}将基于bdp.system.bizdate取值。
  • 中括号[ ]:对应运行时间,例如[yyyymmddhh]将基于bdp.system.cyctime取值。
说明 任务只有在生产环境才会被调度,所以调度参数只有生产环境调度运行后才会被替换。

如果您需要验证配置的调度参数在调度中替换的值是否符合预期,请使用冒烟测试功能,详情请参见开发环境冒烟测试

参数需要在调度配置 > 基本属性 > 参数中赋值(下文简称为调度变量赋值),参数配置时请注意以下问题:

  • 参数=两边不可以加空格。例如bizdate=$bizdate
  • 如果存在多个参数,需要使用空格分隔每个参数。例如bizdate=$bizdate datetime=${yyyymmdd}

系统参数

DataWorks提供了两个系统参数,定义如下:

  • ${bdp.system.cyctime}:定义为一个实例的定时运行时间,默认格式为yyyymmddhh24miss。仅有运行时间可以取到具体的小时、分钟时间。
  • ${bdp.system.bizdate}:定义为一个实例计算时对应的业务日期,业务日期默认为运行日期的前一天,默认以yyyymmdd的格式显示。

运行时间和业务日期的计算公式为运行时间=业务日期+1

如果使用系统参数,无需在编辑框设置,直接在代码中引用${bizdate}即可,系统将自动替换代码中对这个参数的引用字段。
说明 一个周期任务的调度属性,配置的是运行时间的定时规律,因此可以根据实例的定时运行时间反推业务日期,从而得知每个实例中参数的取值。

PyODPS节点的调度参数配置与普通节点稍有不同,详情请参见PyODPS节点

系统参数示例

假设您需要设置一个ODPS_SQL任务为小时调度,每天00:00-23:59时间段里每隔1小时执行一次。如果想在代码中使用系统参数,请参见下述步骤进行操作。

  1. 在代码中直接引用系统参数,节点代码如下所示:
    insert overwrite table tb1 partition(ds ='20150304') select
    c1,c2,c3
    from (
    select * from tb2
    where ds ='${bdp.system.cyctime}') t
    full outer join(
    select * from tb3
    where ds = '${bdp.system.bizdate}') y
    on t.c1 = y.c1;
  2. 完成上述步骤后,您的任务已经通过系统参数完成了分区的设置。接下来您可以设置时间属性和调度依赖,详情请参见时间属性调度依赖,本示例设置调度周期为小时。
    调度依赖
  3. 设置好周期与依赖后,提交任务,您可以在运维中心看到您的任务。从第二天开始,您的任务在运行时会产生周期实例,右键单击查看运行日志,即可看到系统参数被实际解析出来的时间。
    解析时间

    例如在2019年01月14日这天,调度系统为该任务生成了24个运行实例。业务日期应当全部为2019年01月13日(运行日期-1天),因此${bdp.system.bizdate}全部显示为20190113。运行时间则为运行日期+定时时间,因此${bdp.system.cyctime}显示为20190114000000+每个实例自己的定时时间。

    打开每个实例的运行日志后,搜索代码中的替换情况如下:

    • 第一个实例定时时间为2019-01-14 00:00:00,则bdp.system.bizdate替换的结果为20190113, bdp.system.cyctime替换的结果为20190114000000。
    • 第二个实例定时时间为2019-01-14 01:00:00,则bdp.system.bizdate替换的结果为20190113,bdp.system.cyctime替换的结果为20190114010000,即上图中显示的情况。
    • 以此类推,第24个实例定时时间为2019-01-14 23:00:00,则bdp.system.bizdate替换的结果为20190113,bdp.system.cyctime替换的结果为20190114230000。

非Shell节点自定义参数

在非Shell节点中配置调度参数,需要先在代码里${变量名}(表示引用函数),然后在调度参数的赋值中输入具体的值。

说明 SQL代码中的变量名命名只支持英文的a-z、A-Z、数字和下划线。变量名为date固定会自动赋$bizdate值(详见调度内置参数列表),不需要在调度参数配置处赋值,即便赋值了也不会替换到代码中,代码默认替换的还是$bizdate。

非Shell节点自定义参数示例

设置一个ODPS_SQL任务为按小时调度,每天在00:00-23:59的时间段中,每隔1小时执行一次。如果您想要在代码中使用关于小时的自定义变量参数thishourlasthour,则应按照如下步骤进行操作。

  1. 在代码中引用参数,代码如下所示。
    insert overwrite table tb1 partition(ds ='20150304')  select
     c1,c2,c3
    from (
     select * from tb2
     where ds ='${thishour}') t
    full outer join(
     select * from tb3
     where ds = '${lasthour}') y
    on t.c1 = y.c1;
  2. 代码中引用的变量,需要调度配置 > 基本属性 > 参数中赋值。

    自定义参数配置如下:

    • thishour=$[yyyy-mm-dd/hh24:mi:ss]
    • lasthour=$[yyyy-mm-dd/hh24:mi:ss-1/24]
    说明 yyyy-mm-dd/hh24:mi:ss参数对应cyctime时间,详请请参见自定义参数变量
    您可以直接在参数一栏中输入thishour=$[yyyy-mm-dd/hh24:mi:ss] lasthour=$[yyyy-mm-dd/hh24:mi:ss-1/24]
    参数
  3. 设置时间周期为每小时运行一次。
    调度时间
  4. 设置好周期与依赖后,提交任务,您可以在运维中心看到您的任务。从第二天开始,您的任务在运行时会产生周期实例,右键实例单击查看运行日志,即可看到自定义参数被实际解析出来的时间:由于CYCTIME为20190114010000,因此解析出来的thishour时间为2019-01-14/01:00:00,而lasthour代表上一个小时,即2019-01-14/00:00:00。
    查看任务

Shell节点自定义参数

Shell节点的参数配置和非Shell节点配置的步骤一样,只是规则有所不同:Shell节点中的变量不允许自定义命名,只能以$1,$2,$3…命名。Shell类型节点,代码中Shell语法声明:$1,调度中节点配置参数配置:$xxx(调度内置参数),即$xxx的值替换代码中的$1。
说明 在Shell节点中,参数到达第10个以后,应该使用 ${10} 的方式来声明变量。

例如设置一个Shell任务按天进行调度,每天01:00执行一次。如果想在代码中使用一个自定义常量参数myname和一个自定义变量参数ct,则可以按照如下步骤进行操作。

  1. 在代码中引用参数,代码如下。
    echo "hello $1, two days ago is $2, the system param is ${bdp.system.cyctime}";
    说明 如果使用系统参数,直接在界面运行可能会报错,建议通过开发环境冒烟测试来测试该任务的运行。
  2. 代码中引用的变量,需要在调度配置 > 基础属性 > 参数中赋值。赋值规则:参数1 参数2 参数3…(根据参数的位置,解析出来替换的变量,例如$1解析出来的值是参数1)。本示例分别给$1和$2赋值为abcd、$[yyyy-mm-dd-2]。
  3. 设置时间周期为每天1点运行。
    设置时间周期
  4. 设置好周期与依赖后,提交任务,您可以在运维中心看到您的任务。从第二天开始,您的任务在运行时会产生周期实例,右键单击查看运行日志,即可看到代码中$1被替换为常量abcd,$2被替换为2019-01-12,即运行日期的前两天,${bdp.system.cyctime}被替换为20190114010000。
    查看任务

自定义参数变量

自定义参数变量分为常量参数和变量(调度内置)参数两种。

  • 变量值为常量

    以SQL类型节点为例,代码里${变量名}, 节点配置参数项为变量名=固定值。

    • 代码:select xxxxxx type='${type}’
    • 调度变量赋值:type=‘aaa’,调度执行时,代码中会替换为type=‘aaa’
  • 变量值为变量参数

    变量参数即调度内置参数,其取值主要基于系统参数${bdp.system.bizdate}和${bdp.system.cyctime}。

    以SQL类型节点为例,代码中${变量名},节点配置参数项为变量名=调度参数。

    • 代码:select xxxxxx dt=${datetime}
    • 调度变量赋值:datetime=$bizdate

      调度执行时,如果今日是2017年07月22日,代码中会替换为dt=20170721

变量参数列表

  • $bizdate
    • 参数说明:业务日期(格式为yyyymmdd),日常调度默认为前一天的日期。
    • 示例:ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=$bizdate。今日是2017年07月22日,今天节点执行时$bizdate替换的时间即pt=20170721。
  • $cyctime
    • 参数说明:任务的定时时间,如果天任务无定时,就是当天0点整(精确到时分秒,通常是小时/分钟级调度任务使用)。
      说明
      • $[]和${}配置时间参数区别于$bizdate业务日期,默认为当前时间减一天。
      • $cyctime任务定时调度时间,如果天任务并没有设置定时,就是当天0点整(精确到时分秒,一般是小时/分钟级调度任务使用)。

        如果定时在0点30运行,以当天为例,就是yyyy-mm-dd 00:30:00。

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

        例如补数据选择业务日期为20140510,执行时cyctime替换结果是20140511。

    • 示例:假设$cyctime=20140515103000。
      • $[yyyy] = 2014, $[yy] = 14, $[mm] = 05, $[dd] = 15, $[yyyy-mm-dd] = 2014-05-15, $[hh24:mi:ss] = 10:30:00, $[yyyy-mm-dd hh24:mi:ss] = 2014-05-1510:30:00
      • $[hh24:mi:ss - 1/24] = 09:30:00
      • $[yyyy-mm-dd hh24:mi:ss -1/24/60] = 2014-05-1510:29:00
      • $[yyyy-mm-dd hh24:mi:ss -1/24] = 2014-05-15 09:30:00
      • $[add_months(yyyymmdd,-1)] = 20140415
      • $[add_months(yyyymmdd,-12*1)] = 20130515
      • $[hh24] =10
      • $[mi] =30
    • 测试$cyctime参数的方法如下所示:

      实例运行后,右键单击查看节点属性,定时时间便是该实例的周期定时时间。

      定时时间减1小时的参数执行替换结果。

  • $jobid
    • 参数说明:任务所属的工作流ID。
    • 示例:jobid=$jobid。
  • $nodeid
    • 参数说明:节点ID。
    • 示例:nodeid=$nodeid。
  • $taskid
    • 参数说明:任务ID(节点实例ID)。
    • 示例:taskid=$taskid。
  • $bizmonth
    • 参数说明:业务月份(格式为yyyymm),当业务日期的月份等于当前月份时,$bizmonth=业务日期月份-1,否则$bizmonth=业务日期月份。
    • 示例:ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=$bizmonth。

      今日是2017年07月22日,今天节点执行时$bizmonth替换的时间即pt=201706。

  • ${…}自定义参数
    • 根据$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}
  • $gmtdate
    • 参数说明:当前日期(格式为yyyymmdd),此参数默认为当天日期,补数据时传入的是业务日期+1。
    • 示例:ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=$gmtdate。今日是2017年07月22日,今天节点执行时$gmtdate替换的时间即pt=20170722。
  • ${yyyymmdd}
    • 参数说明:业务日期(格式yyyymmdd,值与$bizdate一致),yyyymmdd之间可以支持任意分隔符,例如yyyy-mm-dd。

      日常调度默认为前一天的日期。此参数格式可以自定义格式,如${yyyy-mm-dd}格式为yyyy-mm-dd。

    • 示例:
      • ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=${yyyy-mm-dd}。今日是2018年07月22日,今天节点执行时${yyyy-mm-dd}替换的时间即pt=2018-07-21。
      • ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=${yyyymmdd-2}。今日是2018年07月22日,今天节点执行时${yyyymmdd-2}替换的时间即pt=20180719。
      • ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=${yyyymm-2}。今日是2018年07月22日,今天节点执行时${yyyymm-2}替换的时间即pt=201805。
      • ODPS SQL节点代码中pt=${datetime},节点配置的参数配置为datetime=${yyyy-2}。今日是2018年07月22日,今天节点执行时${yyyy-2}替换的时间即pt=2016。
      • ODPS SQL节点配置中多个参数赋值如:startdatetime=$bizdate enddatetime=${yyyymmdd+1} starttime=${yyyy-mm-dd} endtime=${yyyy-mm-dd+1}。

参数配置常见问题

  • Q:表的分区格式为pt=yyyy-mm-dd hh24:mi:ss,但是调度参数中不允许配置空格,我该如何配置$[yyyy-mm-dd hh24:mi:ss]的格式呢?

    A:使用两个自定义变量参数 datetime=$[yyyy-mm-dd]、 hour=$[hh24:mi:ss],分别获取日期和时间,然后在代码中拼接为 pt=”${datetime} ${hour}” (注意拼接的两段自定义参数之间需要空格隔开)。

  • Q:在代码中表的分区为pt=”${datetime} ${hour}”,希望执行的时侯取上个小时的数据。使用两个自定义变量参数 datetime=$[yyyymmdd]、 hour=$[hh24-1/24],分别获取日期和时间可以满足需求。但是0点运行的实例,计算结果会变成当天的23点,实际应当是前一天的23点,怎么办?
    A:参数的计算公式稍作修改,datetime修改为$[yyyymmdd-1/24],hour的计算公式不变仍为$[hh24-1/24]。计算结果如下,即可满足需求。
    • 如果一个实例的定时时间是2015-10-27 00:00:00,减1小时就是昨天,所以$[yyyymmdd-1/24]的值是20151026,$[hh24-1/24]的值是23。
    • 如果一个实例的定时时间为2015-10-27 01:00:00的实例,减1小时还是今天,所以$[yyyymmdd-1/24]的值是20151027,$[hh24-1/24]的值是00。
DataWorks提供以下4种运行方式:
  • 数据开发页面运行:需要在参数配置页面临时赋值以保证运行。但该赋值不会保存为任务的属性,因此不会对其他3种运行方式起作用。
  • 系统自动周期运行:不需要在参数编辑框做任何配置,调度系统会根据当前实例的定时运行时间自动替换。
  • 测试运行/补数据运行:触发时需要指定业务日期,可根据上述计算公式推断定时运行时间,从而得知各实例中这两个系统参数的取值。