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

背景信息

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

参数类型

目前调度参数支持系统参数和自定义参数两种形式：
  • 系统参数可以在代码中直接使用。
  • 自定义参数需要在调度参数赋值处，给该变量赋值自定义参数后，在代码中调用变量名。
参数类型 适用节点 调用方式 参数赋值 参数编辑框示例
系统参数 ：主要包括业务时间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']。其中key1和key2为变量名。
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