手把手教你用Postman调试DolphinScheduler 3.x创建任务API（附数据库查Code指南）
手把手教你用Postman调试DolphinScheduler 3.x创建任务API（附数据库查Code指南）
在分布式任务调度系统的日常运维中，API调试是开发者和运维人员必须掌握的硬核技能。DolphinScheduler作为一款开源的分布式易扩展可视化工作流任务调度平台，其API的灵活调用能极大提升自动化运维效率。本文将带您从零开始，完整走通创建任务API的调试全流程，重点解决两个核心痛点：如何正确构造包含taskDefinitionJsonObj等复杂参数的Postman请求，以及如何从数据库准确获取必需的code参数（包括工作流code、项目code等）。无论您使用的是MySQL还是PostgreSQL数据库，或是部署在K8s环境中，都能在本指南中找到对应的解决方案。
1. 环境准备与数据库连接
1.1 确认数据库类型与连接信息
在开始API调试前，我们需要先获取DolphinScheduler的元数据信息。这些信息通常存储在后台数据库中，因此第一步是确认您的部署环境使用的是哪种数据库：
# 查看K8s部署配置（假设使用Helm部署） kubectl get configmap -n dolphinscheduler dolphinscheduler-config -o yaml | grep -i "database"对于K8s部署，数据库配置通常在values.yaml文件中。关键配置项包括：
| 配置项 | 示例值 | 说明 |
|---|---|---|
| database.type | postgresql | 数据库类型 |
| database.host | postgresql.dolphinscheduler.svc.cluster.local | 数据库主机地址 |
| database.port | 5432 | 数据库端口 |
| database.username | admin | 数据库用户名 |
| database.password | dolphinscheduler123 | 数据库密码 |
| database.database | dolphinscheduler | 数据库名称 |
1.2 数据库连接与查询
根据不同的数据库类型，使用对应的客户端工具连接数据库：
MySQL连接示例：
mysql -h 数据库地址 -P 端口 -u 用户名 -p密码 数据库名PostgreSQL连接示例：
psql -h 数据库地址 -p 端口 -U 用户名 -d 数据库名连接成功后，执行以下SQL查询获取必要的code信息：
-- 查询项目列表 SELECT id, name, code FROM t_ds_project; -- 查询工作流定义 SELECT id, name, code, project_code FROM t_ds_process_definition; -- 查询任务定义 SELECT id, name, code, process_definition_code FROM t_ds_task_definition;注意：在实际操作中，建议将这些查询结果保存到本地文本文件中，后续API调用时会频繁用到这些code值。
2. Postman请求配置详解
2.1 创建新请求与认证配置
- 打开Postman，创建一个新的
POST请求 - 设置请求URL为：
http://<DS服务地址>:<端口>/dolphinscheduler/projects/<project_code>/task-definition/save-single - 在
Headers中添加以下内容：
| Key | Value |
|---|---|
| Content-Type | application/json |
| token | <您的会话token> |
获取token的方法：
- 通过UI登录后从浏览器Cookie中获取
sessionId - 或者调用登录API获取：
curl -X POST http://<DS服务地址>:<端口>/dolphinscheduler/users/login \ -H "Content-Type: application/json" \ -d '{"userName":"admin", "userPassword":"dolphinscheduler123"}'2.2 请求体构造
创建任务API的核心在于正确构造taskDefinitionJsonObj参数。以下是一个完整的请求体示例：
{ "processDefinitionCode": "1234567890123", "upstreamCodes": "9876543210987", "taskDefinitionJsonObj": { "code": "", "delayTime": 0, "description": "", "environmentCode": -1, "failRetryInterval": 1, "failRetryTimes": 0, "flag": "YES", "name": "测试任务", "taskParams": { "rawScript": "echo 'Hello DolphinScheduler'", "localParams": [], "resourceList": [] }, "taskPriority": "MEDIUM", "taskType": "SHELL", "timeout": 0, "timeoutFlag": "CLOSE", "timeoutNotifyStrategy": null, "workerGroup": "default" } }关键参数说明：
processDefinitionCode: 工作流定义code（从数据库查询获得）upstreamCodes: 上游节点code（可选，多个用逗号分隔）taskDefinitionJsonObj中的核心字段：name: 任务名称（在UI中显示）taskType: 任务类型（如SHELL、SQL等）taskParams.rawScript: 任务执行脚本内容
3. 常见问题排查指南
3.1 错误代码与解决方案
| 错误码 | 可能原因 | 解决方案 |
|---|---|---|
| 500 | 数据库连接失败 | 检查数据库服务是否正常，网络是否通畅 |
| 401 | 未授权 | 检查token是否有效，是否已过期 |
| 400 | 参数错误 | 检查所有code值是否正确，特别是processDefinitionCode |
| 404 | 资源不存在 | 确认项目code和工作流code是否存在 |
3.2 调试技巧
日志查看：当API调用失败时，首先检查DolphinScheduler服务日志
kubectl logs -n dolphinscheduler <api-server-pod-name> -fUI对比法：在UI界面手动创建一个简单任务，通过浏览器开发者工具查看实际发送的请求参数
参数校验：使用Postman的Pre-request Script功能对参数进行预校验：
// 示例：检查必填参数是否存在 if (!pm.request.body.raw.includes('processDefinitionCode')) { throw new Error("缺少processDefinitionCode参数"); }
4. 完整工作流验证
为了确保我们的API调用真正生效，建议按照以下步骤进行端到端验证：
- API调用：在Postman中发送创建任务请求，确保返回状态码为200
- 数据库验证：查询数据库确认任务已创建
SELECT * FROM t_ds_task_definition WHERE name = '测试任务'; - UI验证：登录DolphinScheduler UI，在对应项目中检查：
- 任务节点是否出现在工作流定义中
- 任务参数是否正确显示
- 执行测试：手动触发工作流执行，观察任务执行日志
提示：对于生产环境，建议先在一个测试项目中完整走通整个流程，再应用到正式环境。