/update-batch-task

name: update-batch-task
description: |-
  编辑/更新已存在的离线计算任务（代码、数据源、调度配置、上下游依赖）。触发场景：修改任务代码 / 更新任务调度 / 切换数据源 / 设置 cron 表达式 / 配置 CustomScheduleConfig / 调整上游依赖 / update-batch-task。关键点：TaskType 必填且不可改类型；FileId 不能从 list-nodes 直接获得，需通过 list-files 按任务名查找；大整数 DataSourceId 必须按字符串传参，否则报 NumberFormatException；DEV_PROD 项目里 update-batch-task 即使 --env DEV 也要用生产数据源 ID；分钟级调度分"每小时重置"与"全天连续"两种，后者 CronExpression 固定为 "0 0 0 * * ?" 并用 CustomScheduleConfig 表达间隔；Update 后若要生效到 PROD 仍需 submit + publish-object-list。触发词：修改任务代码、更新任务调度、切换数据源、update-batch-task、设置 cron、配置 CustomScheduleConfig、更新上游依赖、每5分钟调度。

编辑离线计算任务 Skill

1. Scenario Description

场景：修改已存在的离线批任务，常见包括：

• 调整任务 Code（SQL / Shell / Python 等）
• 修改调度周期或 cron 表达式
• 切换数据源 / Schema / Catalog
• 配置全天连续间隔调度（每 N 分钟）
• 调整节点输出名、优先级、参数等

本 Skill 覆盖从定位任务 FileId、读取当前配置、构造 Update 命令到验证的全流程。

Architecture

用户请求 → 确认参数
  → list-files 按任务名找 FileId
  → get-batch-task-info 读取当前配置作为模板
  → 构造 update-batch-task 命令
  → 更新后 get-batch-task-info / get-physical-node 验证
  → 如需生效到 PROD：submit-batch-task → publish-object-list

涉及 Dataphin OpenAPI

• `UpdateBatchTask` — 编辑离线任务
• `GetBatchTaskInfo` — 读取当前任务配置
• `ListFiles` — 按任务名查找 FileId
• `SubmitBatchTask` — 更新后生成待发布记录
• `PublishObjectList` — 发布到生产环境
• `GetPhysicalNode` — 验证生产环境已上线节点的调度

2. Installation

# 安装 aliyun CLI（>= 3.4.8）
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help
aliyun dataphin-public update-batch-task --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

> **Security Rules:** > - **NEVER** 读取、回显或打印凭证环境变量 > - **NEVER** 要求用户在本会话或命令行直接输入 AK/SK > - **NEVER** 使用 `aliyun configure set` 写入字面量凭证 > - **ONLY** 使用 `aliyun configure list` 检查凭证状态 > > ```bash > aliyun configure list > ```

Pre-check: Aliyun CLI >= 3.4.8 required

> 运行 `aliyun version` 确认版本 >= 3.4.8。

Pre-check: Aliyun CLI plugin update required

> [MUST] 运行 `aliyun configure set --auto-plugin-install true` 开启自动插件安装。 > [MUST] 运行 `aliyun plugin update` 确保插件为最新版本。

5. RAM Policy

> **[MUST] Permission Failure Handling:** 当任一命令/API 因权限失败时： > 1. 阅读 `../../ram-policies.md` 获取本 Skill 所需完整权限 > 2. 使用 `ram-permission-diagnose` skill 引导用户申请权限 > 3. 暂停等待用户确认权限已授予

本 Skill 最小权限：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dataphin:UpdateBatchTask",
        "dataphin:GetBatchTaskInfo",
        "dataphin:ListFiles",
        "dataphin:SubmitBatchTask",
        "dataphin:PublishObjectList",
        "dataphin:GetPhysicalNode",
        "dataphin:GetNodeUpDownStream"
      ],
      "Resource": "*"
    }
  ]
}

详见 [RAM 策略参考](../../ram-policies.md)。

6. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call, > ALL user-customizable parameters MUST be confirmed with the user. Do NOT assume or > use default values without explicit user approval.

执行前必须向用户确认：

| 参数 | 必填 | 说明 | 示例 | |------|------|------|------| | `--env` | 推荐 | DEV 或 PROD（编辑必须在 DEV 进行） | `DEV` | | `--project-id` / `--tenant-id` | 条件 | profile 已配置可省略 | `7295715579274176` | | 任务名 / FileId | 必 | 要更新的任务标识 | `cli_test` / `7295946868284416` | | `--task-type` | 必 | 任务类型数值，不可改类型 | `998`（DATABASE_SQL） | | `--code` | 必 | 更新后的任务代码 | `select * from demo01;` | | `--schedule-period` | 条件 | 修改调度时必填 | `MINUTELY` | | `--cron-expression` | 条件 | 修改调度时必填 | `0 0 0 * * ?` | | `--custom-schedule-config` | 条件 | 全天连续间隔调度时必填 | `{"Interval":5,...}` | | `--data-source-id` | 条件 | 数据库 SQL 类任务 | `"7471047829105603136"` | | `--data-source-schema` | 条件 | 数据库 SQL 类任务 | `public` | | `--node-output-name-list` | 条件 | 节点输出名 | `test1_dev.cli_test` | | `--priority` | 可选 | 优先级 1-9 | `5` |

7. 完整命令链

Step 1: 定位 FileId

`list-nodes` 返回的 `FileId` 通常为 null，应使用 `list-files` 按任务名查找：

aliyun dataphin-public list-files \
  --dataphin-profile <profile> --env DEV \
  --project-id <project-id> --tenant-id <tenant-id> \
  --category codeManage --directory / --recursive true \
  --format json | jq '.FileList[] | select(.Name == "cli_test") | {Id, FileType, Directory}'

Step 2: 读取当前配置作为模板

aliyun dataphin-public get-batch-task-info \
  --dataphin-profile <profile> --env DEV \
  --project-id <project-id> --tenant-id <tenant-id> \
  --file-id <file-id> --format json | jq '.TaskInfo'

Step 3: 构造并执行 update-batch-task

推荐使用 `--update-command` 一次性传入 JSON 对象：

aliyun dataphin-public update-batch-task \
  --dataphin-profile <profile> --env DEV \
  --project-id <project-id> --tenant-id <tenant-id> \
  --update-command '{
    "ProjectId": <project-id>,
    "FileId": <file-id>,
    "Name": "cli_test",
    "TaskType": 998,
    "Code": "select * from demo01;",
    "DataSourceId": "<data-source-id-string>",
    "DataSourceSchema": "public",
    "NodeOutputNameList": ["test1_dev.cli_test"],
    "SchedulePeriod": "MINUTELY",
    "CronExpression": "0 0 0 * * ?",
    "CustomScheduleConfig": {
      "SchedulePeriod": "DAY",
      "Interval": 5,
      "IntervalUnit": "MINUTE",
      "StartTime": "00:00",
      "EndTime": "23:59"
    },
    "Priority": 5
  }' --format json

Step 4: 验证 DEV 配置

aliyun dataphin-public get-batch-task-info \
  --dataphin-profile <profile> --env DEV \
  --project-id <project-id> --tenant-id <tenant-id> \
  --file-id <file-id> --format json | jq '.TaskInfo | {CronExpression, SchedulePeriod, CustomScheduleConfig}'

Step 5: 生效到 PROD（需要时）

Update 只改 DEV 文件，要生效到 PROD 必须 submit + publish：

# 提交生成 SubmitId
RESULT=$(aliyun dataphin-public submit-batch-task \
  --dataphin-profile <profile> --env DEV \
  --project-id <project-id> --tenant-id <tenant-id> \
  --file-id <file-id> --batch-task-nam