基础属性：调度参数

注意事项

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

  例如，使用调度参数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}和定时时间参数${bdp.system.cyctime}。
  系统内置变量的详情可参见系统内置变量。
• 自定义参数：
  • 需要在调度配置 > 基础属性 > 参数中进行赋值，赋值后可在代码中引用自定义参数的变量名。
  • 包括系统内置参数、${…}参数、$[…]参数和常量参数。
  自定义参数的详情可参见自定义参数：系统内置参数、自定义参数：${…}参数、自定义参数：$[…]参数和自定义参数：常量参数。

系统内置变量

• 细分类型

  细分类型	定义	对比说明
  ${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，其中key1、key2是自定义的参数名称，value1、value2是系统内置参数，DataWorks当前可用的系统内置参数列表可参见上述表格表 1。
  • 引用格式为：
    • ODPS SQL节点和离线数据同步节点

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

    • PyODPS节点

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

  • 赋值引用要求（Shell节点）
    • 赋值格式为：value1 value2，其中value1、value2是系统内置参数，DataWorks当前可用的系统内置参数列表可参见上述表格表 1。
    • 引用格式

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

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

• 参数定义
  ${...}参数是基于系统内置参数$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节点）
  • 需要在调度配置 > 基础属性 > 参数中进行赋值，赋值后可在代码中引用自定义参数的变量名。
  • 赋值的格式为：key1=value1 key2=value2，其中key1、key2是自定义的参数名称，value1、value2是自定义的日期取值。下表为常见的日期取值案例。

    日期加减周期	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节点和离线数据同步节点

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

    • PyODPS节点

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

• 赋值引用要求（Shell节点）
  • 赋值格式为：value1 value2，其中value1、value2是自定义的日期取值
  • 引用格式

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

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

• 参数定义
  $[...]参数是基于系统内置参数$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节点）
  • 需要在调度配置 > 基础属性 > 参数中进行赋值，赋值后可在代码中引用自定义参数的变量名。
  • 赋值的格式为：key1=value1 key2=value2，其中key1、key2是自定义的参数名称，value1、value2是自定义的日期取值。下表为常见的日期取值案例。

    时间加减周期	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节点和离线数据同步节点

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

    • PyODPS节点

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

• 赋值引用要求（Shell节点）
  • 赋值格式为：value1 value2，其中value1、value2是系统内置参数，DataWorks当前可用的系统内置参数列表可参见上述表格表 1。
  • 引用格式

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

自定义参数：常量参数

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

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

    • PyODPS节点

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

• 赋值引用要求（Shell节点）
  • 赋值格式为：value1 value2，其中value1、value2自定义的常量，如"abc" 1234。
  • 引用格式

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

自定义参数应用对比

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

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

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

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

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

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

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

开发环境测试调度参数

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

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

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

常见问题

• 如何处理表的分区格式中需要空格的情况？
• 如何处理0点运行的实例，计算结果变为当天的23点，实际应当是前一天的23点的情况？
• 调试调度参数时，DataWorks支持哪些运行方式？
• 如何处理无法解析自定义参数，导致任务运行失败的情况？
• 如何定义调度参数的时区？