暂停/恢复任务实例 Skill

1. Scenario Description

场景：周期任务在某个业务日期的实例尚未运行（WAIT_SCHEDULE），但需要阻止其在到达调度时间点时被拉起；或已暂停后需要恢复调度。典型用途：

• 小时任务某个时点的实例暂时不想跑（如 20:45 实例先暂停，待数据就绪后再恢复）
• 实例等待调度时临时挂起，避免占用资源或误触发

本 Skill 按「任务名 + 业务日期 + 运行时点（DueTime）」定位实例，执行 OperateInstance --operation PAUSE（暂停）或 RESUME（恢复），并给出验证方法。

Architecture

用户请求 → 确认参数 → list-instances 按 bizdate 查询
  → 按 DueTime 筛选目标时点实例 → operate-instance PAUSE/RESUME
  → get-physical-instance 验证 SchedulePaused → 输出结论

涉及 Dataphin OpenAPI：

• ListProjects — 枚举项目（同名任务可能跨项目）
• ListInstances — 按任务名 + 业务日期查实例，输出 DueTime（毫秒时间戳）
• OperateInstance — 触发 PAUSE / RESUME
• GetPhysicalInstance — 验证 NodeInfo.SchedulePaused

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

详见 CLI 安装指南。

3. Environment Variables

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

4. Authentication

Pre-check: Credentials Required

Security Rules:

• NEVER 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志）
• NEVER 要求用户在本会话或命令行直接输入 AK/SK
• NEVER 使用 aliyun configure set 写入字面量凭证
• ONLY 使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。

如果没有有效 profile，请在此停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在会话外配置（终端执行 aliyun configure，或在 shell profile 中设置环境变量）
3. 重新运行 aliyun configure list 确认有效后再继续

Pre-check: Aliyun CLI >= 3.4.8 required

运行 aliyun version 确认版本 >= 3.4.8。若未安装或版本过低，从 https://aliyuncli.alicdn.com 安装/升级（见 references/cli-installation-guide.md）。

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: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read ../../ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

本 Skill 涉及的最小权限：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dataphin:ListProjects",
        "dataphin:ListInstances",
        "dataphin:OperateInstance",
        "dataphin:GetPhysicalInstance"
      ],
      "Resource": "*"
    }
  ]
}

详见 RAM 策略参考。

6. Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

执行前必须向用户确认以下参数：

7. Observability

版本 {version}（Shell 变量 SKILL_VERSION）来自套件 references/manifest.json 的 version 字段，与 session-id 一同继承父技能 §7。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

本 Skill 属于 alibabacloud-dataphin-skills 套件，继承父 Skill alibabacloud-dataphin-skills 的 session-id，子 Skill 不再重新生成。

所有调用 Alibaba Cloud API 的 aliyun 命令必须携带：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

其中 {session-id} 替换为父 Skill 生成的 32 位小写十六进制字符串。

8. Core Workflow

8.1 计算业务日期

# 优先使用真实系统日期，不要依赖会话上下文时间
TODAY=$(date "+%Y%m%d")
# macOS
BIZDATE=$(date -v-1d "+%Y%m%d")
# Linux 用：BIZDATE=$(date -d "-1 day" "+%Y%m%d")
echo "today=$TODAY bizdate=$BIZDATE"

关键：Dataphin 默认 bizdate = T-1。用户说「当日 20:45 运行的实例」时，该实例的业务日期通常是昨天（T-1），而不是今天。若用今日作为 bizdate 查不到实例，请回退到 T-1。

8.2 定位目标实例

已知项目 ID

ENV=PROD
PROJECT_ID="<project-id>"
TASK_NAME="<task-name>"
BIZDATE="<biz-date>"

aliyun dataphin-public list-instances \
  --env "$ENV" \
  --project-id "$PROJECT_ID" \
  --schedule-type NORMAL \
  --search-text "$TASK_NAME" \
  --min-biz-date "$BIZDATE" \
  --max-biz-date "$BIZDATE" \
  --page 1 --page-size 50 \
  --format json \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
  | jq -r '.PageResult.Data[]? | "\(.Id)\t\(.NodeInfo.Name)\t\(.DueTime)\t\(.StatusList|join(","))"'

按运行时点筛选（小时任务）

DueTime 是毫秒时间戳。将其转为 HH:MM 后筛选目标时点：

TARGET_HHMM="20:45"

aliyun dataphin-public list-instances \
  --env "$ENV" \
  --project-id "$PROJECT_ID" \
  --schedule-type NORMAL \
  --search-text "$TASK_NAME" \
  --min-biz-date "$BIZDATE" \
  --max-biz-date "$BIZDATE" \
  --page 1 --page-size 50 \
  --format json \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
  | jq -r '.PageResult.Data[]? | "\(.Id)\t\(.DueTime)"' \
  | while IFS=$'\t' read -r ID DUE; do
      HM=$(date -r $((DUE/1000)) "+%H:%M")
      if [[ "$HM" == "$TARGET_HHMM" ]]; then
        echo "$ID $HM"
      fi
    done

Linux 上 date -r 改为 date -d @<秒>。

未知项目 ID（跨项目搜索）

PROJECTS=$(aliyun dataphin-public list-projects \
  --env "$ENV" \
  --page-no 1 --page-size 100 \
  --format json \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
  | jq -r '.PageResult.ProjectList[] | "\(.Id) \(.Name)"')

while read -r PID PNAME; do
  aliyun dataphin-public list-instances \
    --env "$ENV" \
    --project-id "$PID" \
    --schedule-type NORMAL \
    --search-text "$TASK_NAME" \
    --min-biz-date "$BIZDATE" \
    --max-biz-date "$BIZDATE" \
    --page 1 --page-size 50 \
    --format json \
    --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
    | jq -r --arg pid "$PID" --arg pname "$PNAME" \
        '.PageResult.Data[]? | "\(.Id)\t\(.NodeInfo.Name)\t\(.DueTime)\t\($pid)\t\($pname)\t\(.StatusList|join(","))"'
done <<< "$PROJECTS"

如果匹配到多条实例，必须向用户展示并确认唯一目标，不要直接全部暂停。

8.3 HITL 确认

在执行写操作前，向用户确认：

即将对以下实例执行 $OPERATION（PAUSE / RESUME）：

• 实例 ID：t_xxxx
• 任务名：cli_test
• 节点 ID：n_xxxx
• 项目：test1_dev (7295715579274176)
• 环境：PROD
• 业务日期：20260629
• 运行时点：20:45

确认执行？（yes/no）

8.4 触发暂停/恢复

ENV=PROD
PROJECT_ID="<project-id>"
INSTANCE_ID="<instance-id>"
OPERATION=PAUSE   # 恢复时改为 RESUME

aliyun dataphin-public operate-instance \
  --env "$ENV" \
  --project-id "$PROJECT_ID" \
  --operation "$OPERATION" \
  --instance-id-list "{\"Id\":\"$INSTANCE_ID\"}" \
  --format json \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

返回 Success=true 且 InstanceStatusList[].Status == "SUCCESS" 仅表示运维指令已下发，必须继续验证。

RESUME 语义：恢复调度后实例回到 WAIT_SCHEDULE，到点（DueTime）会被调度自动拉起执行。

• 若需立即手动触发执行，不要用 RESUME（它只恢复调度等待），应改用 --operation RERUN（见同套件子 skill rerun-task-instance，经套件入口路由加载）。
• RESUME 不改变实例已有的 StatusList（如仍为 WAIT_SCHEDULE），只把 SchedulePaused 从 true 切回 false。

8.5 验证

aliyun dataphin-public get-physical-instance \
  --env "$ENV" \
  --project-id "$PROJECT_ID" \
  --instance-id "$INSTANCE_ID" \
  --format json \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
  | jq '.Instance | {Id, StatusList, SchedulePaused:.NodeInfo.SchedulePaused, DueTime, BizDate}'

验证要点：get-physical-instance 返回结构是 .Instance（不是顶层）。PAUSE 成功的判据是 .Instance.NodeInfo.SchedulePaused == true，而不是 StatusList 变为 PAUSED。暂停后实例 StatusList 仍可能显示 WAIT_SCHEDULE，这是正常的——它表示实例仍在等待，但调度已被挂起，不会被拉起。

9. Success Verification Method

• operate-instance 返回 Success=true 且 InstanceStatusList[].Status == "SUCCESS"，说明指令下发成功。
• get-physical-instance 确认：
  • PAUSE 后：.Instance.NodeInfo.SchedulePaused == true
  • RESUME 后：.Instance.NodeInfo.SchedulePaused == false
• RESUME 后 StatusList 仍为 WAIT_SCHEDULE 属正常：表示实例已回到正常等待调度状态，到点会自动执行；判据是 SchedulePaused=false，不是 StatusList 变化。
• 若 SchedulePaused 未变化，检查 --project-id / --env 是否与实例匹配。

10. Cleanup

本 Skill 仅切换实例调度状态，不创建新的 Dataphin 资源，无需清理。 若需要恢复，执行 --operation RESUME 即可。

11. Command Tables

详见 相关命令索引。

12. Best Practices

1. 业务日期默认 T-1：用户说「当日运行的实例」时，bizdate 通常是昨天。用今日查不到实例应回退到 T-1。
2. 小时任务按 DueTime 筛选：一个 bizdate 可能展开成多个时点实例（如 0 45 8,20 * * ? → 08:45 / 20:45），必须按 DueTime 选定，不能凭 bizdate 唯一定位。
3. PAUSE 验证看 SchedulePaused：暂停后 StatusList 可能仍是 WAIT_SCHEDULE，判据是 NodeInfo.SchedulePaused=true。
4. 实例与项目必须匹配：operate-instance 的 --project-id 必须是实例所属项目，否则报 DPN.OP.ProjectNotExist。
5. 大整数 ID 作为字符串传递：--instance-id-list 的 Id 值必须用引号包裹。
6. 恢复用 RESUME：暂停后如需继续调度，用 --operation RESUME，不要用 RERUN（RERUN 是重新执行，不是恢复调度）。

13. Reference Links