按任务名获取离线（batch）任务详情 skill
调用 CLI / SDK 前，继承父技能 §7 初始化的 session-id 与套件 references/manifest.json 中的 version；直接加载时先完成父层初始化。API 命令统一附带 --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"，使用父技能名称与同一会话、版本。
适用场景
- 用户只给了离线任务的名称（如
zh_down），未给file-id，需要拿到任务代码 / 调度 / 上游 / DagId 等详情 - 编辑、提交、补数据前先读当前配置作为模板（参考 update-batch-task.md §"读取当前配置"）
- 排查
NodeWithoutUpstream等问题时需要看TaskInfo.UpStreamList
Dataphin 没有"按名称直接 get 任务"的单步 API，必须先在目录树里反查 FileId，再拿 FileId 取详情。
核心命令
| 步骤 | 命令 | 关键产物 |
|---|---|---|
| 1. 列目录树按 Name 反查 | aliyun dataphin-public list-files --category codeManage --recursive true --directory / --env DEV | 任务的 Id（即 FileId） |
| 2. 用 FileId 取详情 | aliyun dataphin-public get-batch-task-info --file-id <Id> | TaskInfo.Code / TaskType / SchedulePeriod / CronExpression / UpStreamList / DagId 等 |
标准两步操作
TENANT_ID=<tenant-id>
PROJECT_ID=<project-id>
TASK_NAME=zh_down
# 1) 在 codeManage 目录树里递归找同名非目录文件，取 Id
FILE_ID=$(aliyun dataphin-public list-files \
--tenant-id $TENANT_ID --project-id $PROJECT_ID \
--category codeManage --directory "/" --recursive true --env DEV \
--output json \
| jq -r --arg n "$TASK_NAME" \
'.FileList[] | select(.Name == $n and .FileType != "directory") | .Id' \
| head -n1)
echo "FileId = $FILE_ID"
# => <file-id>
# 2) 用 FileId 拉任务详情
aliyun dataphin-public get-batch-task-info \
--tenant-id $TENANT_ID --project-id $PROJECT_ID \
--file-id $FILE_ID --output json
返回结构关键字段（节选）：
{
"TaskInfo": {
"FileId": 7274117084921600,
"Name": "zh_down",
"NodeId": "n_7943347812720771072",
"TaskType": 10, // 10=Shell, 1=Python, 5=Hive_SQL, 21=MaxCompute_SQL ...
"SchedulePeriod": "DAILY",
"CronExpression": "0 0 0 * * ?",
"Priority": 5,
"Code": "echo 1", // ★ 任务代码
"DagId": "d_7859751600056107008", // 项目级常量，可推根节点
"UpStreamList": [], // 显式上游（不含自动挂载的虚拟根节点）
"ParamList": [],
"OwnerName": "SuperAdmin",
"Published": true
},
"Code": "OK", "Success": true
}
常用过滤套路
- 只拿代码：
... | jq -r '.TaskInfo.Code' - 拿 NodeId（运维/补数据用）：
... | jq -r '.TaskInfo.NodeId' - 拿 DagId（推根节点用）：
... | jq -r '.TaskInfo.DagId' - 同名匹配多个 → 加 Directory 二次精确：
select(.Name == $n and .Directory == "/舟衡/") - 模糊匹配查近名：
.FileList[] | select(.Name | test("zh_down"; "i"))
✗ 不要用的方式（历史踩坑）
| 方式 | 为什么不行 |
|---|---|
aliyun dataphin-public list-nodes --search-text <name> | 该接口入参严格（必传 --node-biz-type / --node-sub-biz-type-list），且对部分 FileType 不返回；实测频繁返回 DPN.Commons.InternalError |
把任务 Name 当 --file-id 传 | --file-id 只接受数字 Id，不接受字符串名 |
不带 --recursive true 列目录 | 默认只返回当前目录第一层，藏在子目录（如 /舟衡/）的任务找不到 |
--env PROD 找开发态任务 | DEV/PROD 是两套环境标识，开发中的任务通常只在 DEV 可见 |
常见坑
--directory要写根/+--recursive true，否则只看到一层目录--category必传codeManage：离线 SQL/Shell/Python 任务、即席查询、管道分别对应不同 category；离线 batch 任务只在codeManage下Content字段在 list-files 永远是 null：代码必须从get-batch-task-info的TaskInfo.Code取，不要指望 list-files 直接拿到- 同名任务：项目内允许不同目录下同名，jq 出多条时用
Directory字段消歧 - 目录类型干扰：必须
select(.FileType != "directory")，否则可能拿到目录节点的 Id 导致get-batch-task-info报错
相关 skill / 命令
- find-tenant-root-node.md — 拿到
DagId后推算虚拟根节点 Name - update-batch-task.md — 读出 TaskInfo 作为 Update payload 模板
- submit-batch-task.md — 提交前确认任务状态
aliyun dataphin-public get-batch-task-versions --file-id <Id>— 查历史版本列表aliyun dataphin-public get-batch-task-info-by-version --file-id <Id> --version <v>— 取指定历史版本详情