任务参数

日常数据开发的过程中，为了使任务自动周期运行时能动态适配环境变化能力。在开发功能内提供了参数配置的功能，您可以在脚本中通过输入${自定义变量}或在参数配置中新增配参数，用作在任务实际执行时动态替换取值。

当前产品内提供两种参数类型：任务参数、任务组参数

  • 任务组参数：操作配置在任务组上，作用范围是任务组内的所有任务。
  • 任务参数：操作配置在任务内，作用范围仅是该任务。

基本概念

分类概念名称含义示意
参数定义自定义参数指用户在代码中，自定义输入，引用的参数。其格式固定为 ${自定义参数名}${my_param}
参数赋值常量指固定不变的取值，比如字符串和数字，用于给自定义参数赋值abcd 或 1234
参数赋值系统内置参数指由系统内置的一系列参数表达式，用来方便用户获取需要通过计算获取的动态的信息，比如任务实例的计划时间sys_plan_datetime
参数赋值系统内置时间函数指由系统内置的一系列函数表达式，用于对时间做一些常用的转换计算add_months(yyyy-MM-dd HH:mm:ss,N)

配置参数

任务组

  • 作用范围：当前任务组下的所有任务
  • 创建方式：在任务组页面点击「参数」tab，点击「新建」后，在弹窗内填写参数名称、参数值。

任务参数

  • 作用范围：当前任务
  • 创建方式： 方式一：在脚本中输入${自定义参数}后，会将自定义参数自动添加至「参数」弹窗内。 方式二：点击参数弹窗，在弹窗内输入信息。

注意：最新版本将原先任务内的外置区域的参数，和调度配置中的参数，统一合并在「参数」中进行配置。

  • 参数名称：如果用户是在脚本中通过输入${自定义变量}的方式添加的，这类参数属于自动解析的，无需用户输入，且不支持用户修改；若用户通过点击「新建」，则支持用户手动输入参数名称

  • 取值来源：支持用户切换任务/或任务组两种来源类型输入参数取值。

  • 参数取值：参数取值决定了用户在运行参数时，系统用什么值进行替换。

    • 若取值来源是任务组：则参数取值为用户在任务组上配置的值，不支持用户在这里进行修改。
    • 若取值来源是任务：则需要用户手动输入/修改参数取值。

  • 加密取值：若点击加密取值则参数取值会变更为加密形式展示

  • 是否忽略：如果用户仅是希望在调度运行中将脚本中的${自定变量}作为普通脚本内容，不替换值时，可以点击忽略。

运行参数

临时运行

用户点击开发右上角「运行」时，会触发临时运行操作。

系统会基于脚本中的${自定义变量}信息，在弹窗中让用户输入本次临时运行时的参数取值，便于用户验证执行结果是否符合预期。

注意：临时运行时的执行参数取值仅针对本次临时运行生效。

调度运行

用户点击提交，将任务提交至生产环境时。系统会按照用户在「参数」配置中的配置信息去做相应的参数替换后去执行具体的任务实例。

参数引用和赋值

  • 所有任务类型中，均使用 ${}占位符来标注该位置为可变参数、需要替换，替换只替换相应的占位符的取值

    • 假定 dt 参数的取值是 2023-09-22
    • 代码中使用如下写法：where pt=${dt}，代码会被替换成 where pt=2023-09-22
    • 代码中使用如下写法：where pt='${dt}' ，代码会被替换成 where pt='2023-09-22'

  • 给用户定义参数赋值，分为常量和变量两种方式

    • 常量：直接输入，不需要任何修饰
    • 变量：包含系统内置参数和系统内置时间函数两类，直接使用名称

参数使用示例

以Lakehouse SQL任务为例，在数据开发界面，编写如下代码：

SELECT
  table1.*
FROM
  table1
WHERE
  city = '${city}'
  AND t = '${time}'
  AND bizdate = '${lastDay}';

在上面的代码示例中，系统会识别出 city、lastDay 和 format 三个参数。在实际执行时可以给其赋值，比如：

参数名称参数赋值
cityShanghai
time$[yyyy-MM-dd HH:mm:ss]
lastDayadd_days('yyyy-MM-dd', -1)

假定任务的触发执行时间是2023-09-20 18:00:00，对参数进行赋值替换后，会实际执行如下代码：

SELECT
  table1.*
FROM
  table1
WHERE
  city = 'Shanghai'
  AND t = '2023-09-20 18:00:00'
  AND bizdate = '2023-09-19';

支持的内置参数

系统支持如下内置参数：

参数名描述示例
bizdateformat格式为yyyyMMdd假定基准时间为 2023-09-22 18:00:00 bizdate 替换为 20230921
sys_biz_day业务日期，比计划时间少一天，format格式为yyyy-MM-dd假定基准时间为 2023-09-22 18:00:00 sys_biz_day 替换为 2023-09-21
sys_biz_datetime业务时间，比计划时间少一天，format格式为yyyy-MM-dd HH:mm:ss假定基准时间为 2023-09-22 18:00:00 sys_biz_datetime 替换为 2023-09-21 18:00:00
sys_plan_day计划日期，format格式为yyyy-MM-dd假定基准时间为 2023-09-22 18:00:00 sys_plan_day 替换为 2023-09-22
sys_plan_datetime计划时间，format格式为yyyy-MM-dd HH:mm:ss假定基准时间为 2023-09-22 18:00:00 sys_plan_datetime 替换为 2023-09-22 18:00:00
sys_plan_timestamp计划时间戳，linux13位时间戳，到毫秒假定基准时间为 2023-09-22 18:00:00 sys_plan_timestamp 替换为 1695463200000
sys_task_id任务id 注：仅在任务调度运行时才支持替换假定任务id为1002 sys_task_id 替换为1002
sys_task_name任务名 注：仅在任务调度运行时才支持替换假定任务名为demo_task sys_task_name 替换为demo_task
sys_task_owner任务负责人 注：仅在任务调度运行时才支持替换假定任务负责人为UAT_TEST sys_task_owner 替换为UAT_TEST

系统内置参数在对用户给定的自定义参数赋值时，可直接使用。如下所示，在代码中直接写 ${param} 来引用参数，给 param 赋值时，可以使用 sys_plan_day 作为右值。

在Python节点使用内置参数

首先在Python节点编写代码如下，定义任务ID、任务名称、任务所有者三个自定义参数并打印：

print("sys_task_id is:")

print('${task_id}')

print("sys_task_name is:")

print('${task_name}')

print("sys_task_owner is:")

print('${task_owner}')

然后点击“参数”将对应的系统参数赋值给自定义参数：

最后返回Python节点，查看运行结果：

2024-06-18 09:44:04 INFO sys_task_id is:

2024-06-18 09:44:04 INFO 11182021

2024-06-18 09:44:04 INFO sys_task_name is:

2024-06-18 09:44:04 INFO qiliang_20240617133043

2024-06-18 09:44:04 INFO sys_task_owner is:

2024-06-18 09:44:04 INFO qiliang

支持的内置时间表达式

系统支持的内置时间表达式，主体是各种时间处理函数，比如常用的yyyyMMdd的组合。时间函数表达式参照 ISO-8601 标准，区分大小写。

时间表达式

表达式描述例子
yyyy四位数年份2023
yy两位数年份23
MM两位数月份09
dd两位数日期22
HH小时18
mm分钟59
ss秒49
.SSS毫秒数377
ZZ时区+08:00
使用方式：$[时间表达式]

上述组合示例：$[yyyy-MM-dd]、$[yyyy-MM-dd HH:mm:ss]、$[yyyy-MM-dd HH:mm:ss.SSSZZ]、$[yyyyMMddHHmmss]，$[HHmmss],$[MM] 等，也就是每一个元素为最小单位，按相应的顺序组合即可，比如直接拼接、用 - 分隔，用 / 分隔等。

时间表达式的增减量

为了满足对相应的时间进行增减的需求，系统支持了时间的增减量，定义如下：

偏移数量单位(缩写)单位(全写)描述示例
整型数字，用正负值标识增或者减msmilli/millisecond毫秒400ms
ssec/second秒400s
mmin/minute分钟3m
hhour小时1h
dday天2d
monmonth月1mon
yyear年-1y
使用方式: $[时间表达式,增减量]

与时间表达式使用方式类似，需要传入第二个参数，表明要增减的数量和单位，在表达式后用英文逗号分隔。比如：$['yyyy-MM-dd HH','-1d']表示减一天，$['yyyy-MM-dd HH','-1h']表示减一小时，$['yyyy-MM-dd HH','1h']表示加一小时，以此类推。

支持的内置时间函数

在时间表达式之外，系统还支持基于时间进行复杂计算，称之为内置时间函数。列表如下：

时间函数返回值描述示例
timestamp()时间戳当前计划时间的时间戳timestamp()
day_of_week(String duration)第几天计算后的日期在当前周的第几天，比如返回1表示第一天,day_of_week('-1d')] /$[day_of_week()]
last_day_of_month(String format,String duration)当月最后一天的时间格式字符串计算后的日期所在的当月的最后一天，格式根据传入的format返回，默认yyyy-MM-ddlast_day_of_month() /last_day_of_month('yyyy-MM-dd','-1mon')
last_day_of_week(String format,String duration)当周最后一天的时间格式字符串计算后的日期所在的当周的最后一天，格式根据传入的format返回，默认yyyy-MM-ddlast_day_of_week() /last_day_of_week('yyyy-MM-dd','-1w')

单偏移量函数/表达式

函数返回值描述示例
day_of_week(String duration)第几天计算后的日期在当前周的第几天返回值 int，1 对应星期一，7 对应星期日例如：当前时间是2025-08-25 10:00:00 使用：day_of_week('-1d') ，对应是7 day_of_week() 对应是1
week_of_month(String duration)第几周计算后的日期所在的月份以及所在周在当月的第几周week 的开始是以周一开始，每年的第一个星期是在该年第一个大于3天（不包括3）的星期。week_of_month('-1mon') week_of_month()
week_of_year(String duration)第几周计算后的日期所在的年份以及所在周在当年的第几周week 的开始是以周一开始，每年的第一个星期是在该年第一个大于3天（不包括3）的星期。week_of_year('-1y') week_of_year()
first_day_of_month(String format,String duration)当月第一天的时间格式字符串计算后的日期所在的当月的第一天，格式根据传入的format返回，默认yyyy-MM-ddfirst_day_of_month() first_day_of_month('yyyy-MM-dd','-1mon')
last_day_of_month(String format,String duration)当月最后一天的时间格式字符串计算后的日期所在的当月的最后一天，格式根据传入的format返回，默认yyyy-MM-ddlast_day_of_month() last_day_of_month('yyyy-MM-dd','-1mon')
first_day_of_week(String format,String duration)当周第一天的时间格式字符串计算后的日期所在的当周的第一天，格式根据传入的format返回，默认yyyy-MM-dd每周的第一天开始为周一，最后一天为周日first_day_of_week() first_day_of_week('yyyy-MM-dd','-1w')
last_day_of_week(String format,String duration)当周最后一天的时间格式字符串计算后的日期所在的当周的最后一天，格式根据传入的format返回，默认yyyy-MM-dd第一天为周一，最后一天为周日last_day_of_week() last_day_of_week('yyyy-MM-dd','-1w')

多偏移量函数/表达式（多个）

函数返回值描述示例
$[format, String[] offset]format后的字符串根据传入的format和增减量，基于当前计划时间进行时间字符串格式化例如：当前时间是2025-08-25 10:00:00 使用： $[yyyyMMdd HH:mm:ss] 对应结果是：2025-08-25 10:00:00 $[yyyyMMdd HH:mm:ss,-1d,-2h]对应结果是：202-08-24 08:00:00
biz_format(String format, String[] offset)format后的字符串根据传入的format和增减量，基于当前计划时间当天的0点0时0分，进行时间字符串格式化biz_format(yyyyMMdd HH:mm:ss, -1d) biz_format(yyyyMMdd HH:mm:ss)biz_format(yyyyMMdd HH:mm:ss, -1y,-1d)
timestamp(String[] offset)毫秒时间戳基于当前计划时间根据传入的增减量，获取对应时间的时间戳timestamp()timestamp(-1d)timestamp(-1w,-1h)
biz_timestamp(String[] offset)毫秒时间戳基于当前计划时间，先取当前天的0点0时0分，再根据传入的增减量，获取对应时间的时间戳biz_timestamp()biz_timestamp(-1d)biz_timestamp(-1w,-1h)
unix_timestamp(String[] offset)秒时间戳基于当前计划时间根据传入的增减量，获取对应时间的秒时间戳unix_timestamp()unix_timestamp(-1d)unix_timestamp(-1w,-1h)
biz_unix_timestamp(String[] offset)秒时间戳基于当前计划时间，先取当前天的0点0时0分，再根据传入的增减量，获取对应时间的秒时间戳biz_unix_timestamp()biz_unix_timestamp(-1d)biz_unix_timestamp(-1w,-1h)
get_day_of_week(String format, int whichDay, String[] offset)format格式化后的时间字符串基于当前的时间，根据传入的增减量对时间进行操作后，获取对应时间所在周的周几，并返回相应的时间例如：当前时间2025-08-25 00:00:00 使用：get_day_of_week('yyyy-MM-dd', 2, -1d)， 表示我要取2025-08-25 减一天后，也就是2025-08-24所在周的周二，最后返回2025-08-19

验证是否支持全量的参数功能

如上文所述，任务参数在灰度开放，可以使用如下方式来验证是否支持：

1、编写SQL

SELECT '${lastDay}';

2、执行代码，给 lastDay 赋值为 add_days('yyyy-MM-dd', -1)

3、检查参数替换、任务执行返回结果是否正常。如果正常（假定当前是2023-11-12，返回值是2023-11-11），则说明在灰度范围内、支持全量的参数功能，否则说明不支持。

附：常用参数

返回值内置参数写发
当天bizdata，$[yyyy-MM-dd]
昨天$[yyyy-MM-dd,-1d]
上周二get_day_of_week(‘yyyy-MM-dd’,2)
上个月$[yyyy-MM-dd,1mon]
当月第一天first_day_of_month()
当月最后一天last_day_of_month()
去年当天$[yyyy-MM-dd,-1y]
去年昨天$[yyyy-MM-dd,-1y,-1d]
任务开发与调度
动态表任务
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.

联系我们
预约咨询
微信咨询
电话咨询