DataWorks调度参数如何动态配置与传递？

什么是调度参数？

调度参数是一种在任务运行时，能够被系统自动替换为特定值的“占位符”。

核心思想： 你在任务（如 Shell 脚本、SQL 脚本）中不写固定的值，而是写一个类似 ${param} 的占位符，当 DataWorks 调度系统执行这个任务时，会根据任务的运行时间、依赖关系等信息，自动计算并替换 ${param} 为一个具体的值。

举个例子： 假设你每天需要执行一个 SQL 任务,统计昨天的用户订单数据。

• 没有调度参数（硬编码）： 你每天都要手动修改 SQL 语句，把 WHERE dt = '2025-10-26' 改成 WHERE dt = '2025-10-27',这非常繁琐且容易出错。
• 使用调度参数： 你在 SQL 中写成 WHERE dt = '${bizdate}'，你设置一个名为 bizdate 的调度参数，其值为 date_add(current_date(), -1)，这样，每天任务运行时，系统会自动计算昨天的日期，并替换 ${bizdate},你再也不用手动修改任务了。

调度参数的类型

DataWorks 的调度参数主要分为以下几类，从简单到复杂,应用场景也各不相同。

系统内置参数

这些是 DataWorks 调度系统预先定义好的参数，无需用户创建，可以直接在任务中使用,它们提供了任务运行时的上下文信息。

使用场景：

• bizdate：用于定义 T+1 任务的业务日期，如 ods_${bizdate} 表。
• yyyy-MM：用于按月分区表的调度，如 dwd_${yyyy-MM}。
• cycle：在 Shell 脚本中,根据不同的调度周期执行不同的逻辑。

自定义参数

当系统内置参数无法满足需求时，你可以创建自己的参数，自定义参数分为两种：全局参数 和 节点参数。

a) 全局参数

• 定义位置： 在 运维中心 -> 调度配置 -> 全局参数 中定义。
• 作用范围： 整个工作空间的所有任务（只要任务有权访问）。
• 特点： 适合定义一些所有任务都可能用到的公共变量，
  • 项目名称：project_name=my_project
  • MaxCompute 访问地址：odps_endpoint=http://service.cn-shanghai.maxcompute.aliyun-inc.com/api
  • 常用日期格式：date_format=yyyy-MM-dd

b) 节点参数

• 定义位置： 在 任务开发 -> 任务的“调度配置”页签 -> 参数 中定义。
• 作用范围： 仅限当前任务及其下游任务（如果下游任务引用了该参数）。
• 特点： 灵活性更高，可以定义与特定任务逻辑相关的变量,且不会污染全局命名空间。

自定义参数的值可以是什么？

• 常量值： 如 param_name='hello'。
• 系统内置函数： 这是自定义参数的精髓所在，你可以使用类似 SQL 的函数来动态计算值。
  • date_add(current_date(), -1)：计算昨天。
  • date_format(current_date(), 'yyyyMMdd')：格式化当前日期。
  • concat('dt=', date_add(current_date(), -1))：拼接字符串。
  • if(DAYOFWEEK(current_date())=2, date_add(current_date(), -3), date_add(current_date(), -1))：如果今天是周一，则取上周五的数据,否则取昨天。

如何使用调度参数？

在代码中引用

在任务代码（SQL、Shell、Python 等）中，直接使用 ${参数名} 的格式即可。

示例 1：SQL 任务

-- 查询昨天的订单数据
SELECT
    user_id,
    order_id,
    amount
FROM
    orders
WHERE
    dt = '${bizdate}'; -- DataWorks 会自动替换 ${bizdate} 为昨天的日期，如 '2025-10-26'

示例 2：Shell 任务

#!/bin/bash
# 定义变量
ods_db="ods_db"
dwd_db="dwd_db"
bizdate=${bizdate} # 接收调度系统传入的参数
echo "今天是 ${sysdate}"
echo "处理业务日期 ${bizdate} 的数据"
# 执行数据导入命令
python /home/admin/dwd_order.py --date ${bizdate}
echo "任务执行成功"

在依赖中引用

DataWorks 的任务依赖关系也支持使用调度参数，这对于实现复杂的 T+N 调度链路至关重要。

场景： 任务 B 依赖任务 A，且 B 需要使用 A 的输出数据。

假设：

• 任务 A：每天处理 bizdate 的数据，输出表 ods_user_${bizdate}。
• 任务 B：每天处理 bizdate 的数据，但需要读取 A 处理好的数据。

在 DataWorks 中，你不能直接写 ods_user_${bizdate}，因为调度系统无法确定 ${bizdate} 的具体值，这时就需要使用 依赖参数。

配置方法： 在任务 B 的 “节点依赖” 配置中，设置对任务 A 的依赖，并指定 “依赖参数” 为 bizdate。

工作原理： 当任务 B 在 2025-10-27 运行时：

1. 调度系统发现 B 依赖 A。
2. 它会计算 A 的运行时间，因为 A 的 bizdate 是 date_add(current_date(), -1)，A 会在 2025-10-27 处理 2025-10-26 的数据。
3. 调度系统会自动将 A 的运行日期（2025-10-27）作为参数传递给 A。
4. 在 B 的依赖关系中，系统知道 B 的 bizdate 参数值（2025-10-26）与 A 的处理逻辑（bizdate）是对应的。
5. 调度系统会确保 A 在 2025-10-27 成功运行后，才会启动 B，B 的代码中 ${bizdate} 的值就是 2025-10-26，可以正确读取到 A 生成的 ods_user_20251026 表。

高级依赖参数： DataWorks 还支持更复杂的依赖关系,如：

• 昨天的任务实例：@{yesterday_task_name},获取昨天同一时间运行的任务实例的输出。
• 上一周期的任务实例：@{pre_task_name}，获取上一个调度周期（如上一个小时）的任务实例的输出。

这些通常与补数据、实例重跑等高级场景结合使用。

最佳实践与注意事项

1. 命名规范： 参数名使用小写字母、下划线和数字，避免使用特殊字符，如 project_name、ods_table_name。
2. 优先使用节点参数： 如果参数只被单个任务或少数几个任务使用，优先使用节点参数,避免全局参数过多导致管理混乱。
3. 避免硬编码： 养成“参数化”的习惯，将所有可能变化的值（如日期、表名、路径）都定义为调度参数。
4. 测试参数： 在发布任务前，务必在 “运维中心 -> 手动触发 -> 补数据” 功能中，用不同的日期测试任务,确保参数被正确替换。
5. 理解业务日期 vs. 系统日期：
   • bizdate 通常是业务日期，代表数据本身的时间,比如订单的下单日期。
   • sysdate 是任务运行的时间。
   • 对于 T+1 任务，bizdate 一般是 date_add(sysdate, -1)。
6. 函数的兼容性： 自定义参数中使用的函数是 DataWorks 调度系统支持的函数集，它可能与你代码中（如 MaxCompute SQL）的函数集略有不同,请参考官方文档。
7. 谨慎使用全局参数： 修改全局参数会影响所有引用它的任务，修改前请评估影响范围,并通知相关同事。

掌握调度参数是高效使用 DataWorks 的必备技能,希望这份详细的解释能帮助你更好地理解和应用它！