参数配置

日常进行数据开发的过程中，为了使任务自动周期运行时能动态适配环境变化，离线开发提供了参数配置的功能，参数的应用场景十分广泛。例如在同步任务中将增量数据写入Hive表的天分区，需要在分区填写栏支持根据天变化的时间变量；例如在多个Spark SQL任务中需要用到公司统一规定的常量...多个场景都会利用到参数配置的功能。

参数配置可分为「运行参数」和「任务上下游参数」两大类，离线任务目前支持五种运行参数：自定义参数、工作流参数（工作流任务类型）、项目参数、全局参数、基于全局参数的偏移量。

运行参数

离线任务目前支持五种运行参数：自定义参数、工作流参数（工作流任务类型）、项目参数、全局参数、基于全局参数的偏移量。

创建运行参数

一、自定义参数

生效范围：当前任务内

创建方式：在任务开发界面点击「添加运行参数」，参数类型选择“自定义参数”，填写参数名称、参数值、注释

二、项目级参数

生效范围：当前项目内

创建项目参数：在「项目管理->项目设置->项目参数」中添加项目参数，目前支持添加常量类型的参数。

使用项目参数：在IDE中通过${参数名称}进行参数声明，声明后在运行参数下会生成参数信息，参数信息中参数类型选择“项目参数”。

三、全局参数

生效范围：平台内所有租户产品项目下所有任务

创建全局参数：超级管理员和控制台**管理员**可以在「控制台 -> 全局配置 -> 全局参数管理」中进行创建

全局参数下支持以下几种参数类型

（1）常量

（2）时间

时间参数是指定时间参数取值时，对参数值进行增减的日期基准。

当「日期基准」选择「自然日」时

是基于自然的时间参数，例如$[yyyymmdd]；

当「日期基准」选择「自定义日期」时

是基于自定义日期的时间参数，例如基于一份交易日历以任务运行时间为基准取最近的一个交易日。如图，可以自定义日期格式，并在上传的文件中填写对应格式的日期。

举例说明，例如设置一个自定义日期时间参数为t_date，时间格式为yyyyMMdd，上传文件日期分别是20220601、20220602、20220603、20220617、20220620。

自定义日期1. 请按定义的日期格式填写;2. 日期上限1000个;3. 从第二行开始解析;
20220601
20220602
20220603
20220617
20220620

1、${t_date} = yyyyMMdd取的是当前交易日：

• 任务执行当天不是个交易日，比如今天是6月15日，自定义日期文件中不存在该交易日，则${t_date} = null
• 任务执行当天是个交易日，比如今天是6月17日，则${t_date} = 20220617

2、${t_date} = yyyyMMdd - n，则取的是以当前日期为基准，日期文件里的历史最近第n天。

• 今天是6月15日，n=1，${t_date} = 20220603；
• 今天是6月17日，n=1，${t_date} = 20220603；
• 今天是6月17日，n=2，${t_date} = 20220602；

3、${t_date} = yyyyMMdd + n，则取的是以当前日期为基准，日期文件里的未来最近第n天。

• 今天是6月18日，n=1，${t_date} = 20220620；
• 今天是6月18日，n=2，${t_date} = null；
• 今天是6月17日，n=1，${t_date} = 20220620；

（3）按计划时间查找参数值

自定义全局参数支持计划时间查找参数值。和「自定义日期」一样，按照计划时间查找参数值，也需要上传一份文件，如下图所示

随着计划时间的变化，参数值也会根据表格里的对应关系发生变化。

设置一个按计划时间查找参数值t_date：

• 当计划时间为2023-02-21 00:00:00，参数值${t_date}=20230220
• 当计划时间为2023-02-22 00:00:00，参数值${t_date}=20230219
• 当计划时间为2023-02-23 00:00:00，参数值${t_date}=null

计划时间(yyyyMMddhhmmss)	参数值
20230221000000	20230220
20230222000000	20230219

::tip

离线开发自带如下几个全局参数：

${bdp.system.bizdate} --业务日期，业务日期默认为计划运行日期的前一天，格式：yyyyMMdd

${bdp.system.bizdate2} --业务日期，格式：yyyy-MM-dd

${bdp.system.cyctime} --计划时间，格式：yyyyMMddHHmmss

${bdp.system.premonth} --上个月（以计划时间为基准），格式：yyyyMM

${bdp.system.currmonth} --当前月（以计划时间为基准），格式：yyyyMM

${bdp.system.runtime} --当前时间，即任务实际运行的时间，格式：yyyyMMddHHmmss

:::

使用运行参数

自定义参数

在任务开发界面点击「添加运行参数」，填写参数名称后再在IDE中通过${参数名称}引用。

基于全局参数的偏移量

基于全局参数的偏移以“#”识别全局参数和偏移量内容：${全局参数名称}#${偏移量正负整数}。

下面将会举例说明，全局参数的偏移量如何使用

参数名称	参数类型	参数值	映射值	操作
param1	基于全局参数的偏移	param0#-1	-	删除

1、当全局参数param0为常量a时，全局参数的偏移不影响参数值

param0#-1=a

param0#+1=a

2、当全局参数param0为基于自然日的全局参数时，假设今天是20221010，实例的计划时间是20221010000000

param0#-1 = 20221009

param0#+1 = 20221011

3、当全局参数param0为基于自定义日期的全局参数时，假设今天是20221010，实例的计划时间是20221010000000，上传自定义日期如下表

自定义日期1. 请按定义的日期格式填写;2. 日期上限1000个;3. 从第二行开始解析;
20221001
20221018
20221019

param0#-1 = 20221001

param0#+1 = 20221018

param0#+5或者param0#-5等超出自定义日期的偏移量，将会报错

4、当全局参数param0为按计划时间查找参数值的全局参数时，假设今天是20221010，实例的计划时间是20221010000000，上传计划时间和参数值对应如下表

计划时间(yyyyMMddhhmmss)	参数值
20221001000000	20220303
20221010000000	a
20221018000000	20220101
20221019100000	2022

param0=a

param0#-1 =20220303

param0#+1 = 20220101

param0#+2 = 2022

param0#+5或者param0#-5等超出表中计划时间外的偏移量，将会报错

工作流参数、项目参数、全局参数的使用

先在工作流参数、项目参数、全局参数中创建参数，在IDE中可以直接通过${参数名称}进行参数声明，声明后会在运行参数下生成参数信息，再去选择对应的参数类型。

例如在任务中声明一个参数test，如果该参数存在于工作流参数或项目参数或全局参数，在右侧运行参数列表中会出现“test”参数，再去指定参数所属的参数类型。

更多使用技巧

时间基准线

在对自定义参数进行增减之前，需明确取值的时间基准，离线开发支持3种基准线，在右侧的参数面板中分别使用$[] 、${}、 $()3种不同的括号，区分3种时间基准，下面举例说明：

实例的业务日期：2022-05-31 实例的计划运行时间：2022-06-01 12:10:00 实例的实际运行时间：2022-06-01 12:13:31

基准线	引用方式	举例
右侧面板输入	参数替换结果
计划时间	$[]	$[yyyy-MM-dd HH:mm:ss]	2022/6/1 12:10
业务日期	${}	${yyyy-MM-dd}	2022/5/31
运行时间	$()	$(yyyy-MM-dd HH:mm:ss)	2022/6/1 12:13

如下图所示：

时间增减

• 基于计划时间取值的时间增减如下，基于业务日期、运行时间的时间增减方式类似，不再列出
• 后N年：$[add_months(yyyyMMdd,12*N)]，输出yyyyMMdd
• 前N年：$[add_months(yyyyMMdd,-12*N)]，输出yyyyMMdd
• 后N月：$[add_months(yyyyMMdd,N)]，输出yyyyMMdd
• 前N月：$[add_months(yyyyMMdd,-N)]，输出yyyyMMdd
• 后N周：$[yyyyMMdd+7*N]，输出yyyyMMdd
• 前N周：$[yyyyMMdd-7*N]，输出yyyyMMdd
• 后N天：$[yyyyMMdd+N]，输出yyyyMMdd
• 前N天：$[yyyyMMdd-N]，输出yyyyMMdd
• 后N小时：$[hh24miss+N/24]，输出yyyyMMddHHmmss
• 前N小时：$[hh24miss-N/24]，输出yyyyMMddHHmmss
• 后N分钟：$[hh24miss+N/24/60]，输出yyyyMMddHHmmss
• 前N分钟：$[hh24miss-N/24/60]，输出yyyyMMddHHmmss

tip

将上述基于计划时间取值的时间增减方式，[] 修改为 {} 或者 () ，可实现基于业务日期或运行时间进行增减

分隔符

在时间增减的基础上，可增加各时间元素之间的分隔符，如下例：

后N年：$[add_months(yyyyMMdd,12*N,-)]，输出yyyy-MM-dd，在完成日期加减后，后面可输入 `,-` 其中的 `-` 表示各元素的分隔符，例如$[add_months(yyyyMMdd,12*N,-)]

此规则适用于时间增减的所有格式。

format函数

系统参数结合时间增减，可满足绝大多数场景的参数需求，但一些特殊场景中，需要定义一些特定的输出格式（例如输出MM-dd）、时间增减等信息，此时可使用format函数来支持。

format函数的使用方法：$[format(yyyyMMddHHmmss+Nunit,'formatString')]

• $[]可替换为${}和$()，修改时间基准为业务日期和任务实际运行时间
• +Nunit，是在做时间增减
  • +表示增加，-表示减少
  • N表示数量，正整数
  • unit表示单位，支持y/M/d/H/m/s/w，分别为：年/月/日/时/分/秒/周，N和unit之间无需字符连接
• formatString为输出格式，分为3类
  • 普通yyyyMMdd等字符：需符合 Joda-Time标准
  • UnixTimestamp10：10位时间戳格式
  • ISODate：输出ISODate格式，例如 2020-06-07T16:11:30Z
• 使用举例：
  • 业务日期减1天，输出MM-dd格式： ${format(yyyyMMddHHmmss-1d,'MM-dd')}
  • 业务日期减3天，输出MMdd yyyy格式： ${format(yyyyMMddHHmmss-3d,'MMdd yyyy')}
  • 计划时间3周后，输出Unix10位时间戳： $[format(yyyyMMddHHmmss+3w,'UnixTimestamp10')]

tip

format函数各部分区分大小写

适用范围

运行参数适用于全部任务类型，可应用于如下领域：

脚本编写类：SQL/Python/Shell、同步任务脚本模式，脚本整体均可使用；

同步任务（向导）：分区、过滤语句、字段映射等

资源上传类：参数输入框

任务上下游参数

info

该功能仅专业版、旗舰版支持

概述

任务运行结束产出的一些结果可能会需要在下游任务中使用，为避免重复计算和维护上的方便，用户可以使用任务上下游参数的功能。

例如A任务是B任务的上游，在A任务中配置的输出参数，可以在B任务中配置输入参数获取到。

支持创建任务上下游参数的任务类型目前有：SparkSQL、HiveSQL、Shell、Python（其中通过资源包引用创建的Python任务不支持设置输出参数）、同步任务（仅有输入参数）、工作流及其上述类型的子节点、Shell on agent任务。

在上述任务的「任务参数 - > 任务上下游参数」中可以分别添加输入参数和输出参数，如下图所示

输出参数

输出参数简介

任务输出参数支持的类型有常量、自定义运行参数和计算结果三种类型。

常量：例如“abc”“12323”等数字或字符串常量

自定义运行参数：例如设置一个“key”，将本任务的自定义运行参数结果传给下游任务。可以将上下游任务共同的参数进行统一管理；

计算结果：对任务的输出表进行取值，例如SQL任务“select a,b from table1 where pt = 20211111”、Python任务“print(a)”、Shell任务“echo a”。平台会把任务输出参数内容写入HDFS文件中。

存储计算结果的文件命名规则：output${参数名称}${任务id}_${计划时间}，存储目录：${租户id}/${项目标识}。

同一任务的临时运行/同一实例多次运行会以最新的文件覆盖旧文件。

配置输出参数

在「任务参数-> 输出参数」点击「添加输出参数按钮」新增一栏空行，如下图。

参数名称：支持填写1-64字符，只支持大小写英文、数字及下划线；不可与已经配置的任务上下游参数重名；

类型：可选常量、自定义运行参数、计算结果（默认）；

内容：根据「类型」选择的结果进行内容填写。

• 类型选择“计算结果”时，“内容”为文本框，可填写1-1024字符，三种任务的输出参数取值填写格式如下：

SQL任务：select 字段 from 表 where 筛选条件

Python任务：print(内容)

Shell任务：echo 内容

• 类型选择“常量”时，“内容”为文本框，1-256字符。
• 类型选择“自定义运行参数”时为下拉框，可选范围为当前任务配置的自定义运行参数。

输入参数

输入参数简介

• 上游任务配置了输出参数，运行产生结果后，即可在下游任务中使用。

• 输入参数配置前提：当前任务存在上游依赖任务，且上游任务已配置输出参数并提交。

配置输入参数

如下图，在“spark12344”任务中分别配置了常量输出参数 “value”、计算结果“key”、自定义运行参数“linrong1”，并进行提交；

并在‘spark12355’任务中，将‘spark12344’配置为上游依赖任务，如下图

此时可在‘spark1235’任务中「任务参数 -> 任务上线游参数 -> 输入参数」中引入‘spark12344’中的输出参数：在来源任务处选中‘spark12344’，并选中想要引入的输入参数，填写在‘spark12355’中的参数名称，如下图

输入参数的在任务中的引用方式和全局参数、自定义参数一致，通过${输入参数名称}的方式引入，如下图所示：

tip

当输出参数为计算结果，select语句查询后包含多个值时，可以通过数组的方式${key}[0][1]进行取值，代表输入参数的第0行，第1列