DolphinScheduler API 实战指南:从获取 Token 到排错,跑通 8 类核心接口

DolphinScheduler API 实战指南:从获取 Token 到排错,跑通 8 类核心接口【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinschedulerApache DolphinScheduler 是一个数据编排平台,核心价值是用低代码方式创建和调度高性能工作流。它的管理能力全部开放成了 RESTful 接口:建项目、定义任务、连线工作流、触发执行、查实例、看统计,都能通过 HTTP 调用完成。这篇文章不逐条罗列接口,而是按你实际接入的先后顺序,带你把整条链路走一遍。动手之前:先搞定认证和请求约定三种身份验证方式怎么选所有请求都发往同一个基础地址,请求体用 JSON,编码 UTF-8:http://{host}:{port}/dolphinscheduler/api身份验证有几种,按场景挑一个即可:方式怎么工作适合谁Token 认证请求头带token: access-token自动化脚本、第三方系统集成Session 认证登录后保存 Cookie,后续请求自动携带模拟浏览器操作Basic 认证用户名密码基础认证临时调试、简单集成Token 认证最常用,也是后文所有示例的默认方式。如何获取 Access Token 并发起首个请求用管理员账号登录一次,拿到会话 Cookie,再向令牌接口申请:# 1. 登录,响应会种下会话 Cookie(保存它) curl -c cookies.txt -X POST \ http://localhost:12345/dolphinscheduler/api/login \ -d userNameadminuserPasswordpassword # 2. 为 userId1 的用户创建一个令牌,expireTime 填到期时间 curl -b cookies.txt -X POST \ http://localhost:12345/dolphinscheduler/api/access-tokens?userId1expireTime2027-01-01%2000:00:00拿到令牌字符串后,把它塞进token请求头,就能调任意受保护接口了。注意令牌有有效期,过期后请求会直接失败,重新申请一个即可。相关控制器在 AccessTokenController.java,想核对参数可以翻源码。全链路实操:建项目、配任务、跑起来、看监控接口可以按业务链路分成五步。每一步只给一个最典型的调用,你照抄就能用。第 1 步:创建项目并拿到 projectCode项目是最顶层的隔离单元,后面所有任务和工作流都挂在某个项目下,所以先建它:curl -X POST http://localhost:12345/dolphinscheduler/api/v2/projects \ -H Content-Type: application/json \ -H token: your-access-token \ -d { projectName: etl-daily, description: 每日数据加工项目 }{ code: 0, msg: success, data: { code: 1000001, name: etl-daily, description: 每日数据加工项目, createTime: 2026-09-11 10:30:00, updateTime: 2026-09-11 10:30:00 } }code为 0 表示成功,data.code是系统生成的项目编码,记下来,后文路径里反复用到。项目的增删改查都在/v2/projects下:GET /v2/projects分页查列表,GET /v2/projects/{projectCode}看详情,PUT和DELETE分别对应更新和删除。第 2 步:定义任务,再把它们串成工作流任务和工作流是两类定义,但创建工作流时可以一次性把任务带进去。下面的示例里,工作流包含一个 SQL 任务和一个 Spark 任务,后者声明依赖前者:curl -X POST http://localhost:12345/dolphinscheduler/api/projects/1000001/workflow-definition \ -H Content-Type: application/json \ -H token: your-access-token \ -d { name: daily-etl, description: 每日抽取-转换流程, globalParams: [{\prop\:\bizDate\,\value\:\${system.datetime}\}], tasks: [ { name: 抽取, taskType: SQL, params: { type: MYSQL, datasource: 1, sql: SELECT * FROM source_table WHERE biz_date ${bizDate} } }, { name: 转换, taskType: SPARK, params: { programType: SQL, deployMode: cluster, appResource: hdfs://path/to/etl.jar, mainArgs: --date ${bizDate} }, preTasks: [抽取] } ] }几个容易踩的点:globalParams是字符串形式的 JSON 数组,不是对象,序列化时容易漏掉这一层引号;preTasks用任务名表达依赖,DAG 就是靠它连出来的;建好后如果不想立即执行,先保持下线状态,用POST /projects/{projectCode}/workflow-definition/{code}/release正式发布。单独维护任务时,走projects/{projectCode}/task-definition这组接口:POST 创建、GET 列表(可用taskType过滤)、GET /{code}查详情、PUT 更新、DELETE 删除。控制器源码在 dolphinscheduler-api 的 controller 目录,参数定义和这里一一对应。第 3 步:按任务需要配好数据源SQL 类任务的datasource字段引用的是数据源编码,所以跑 SQL 前得先把连接建好:curl -X POST http://localhost:12345/dolphinscheduler/api/datasources \ -H Content-Type: application/json \ -H token: your-access-token \ -d { name: mysql_prod, type: MYSQL, address: [\jdbc:mysql://10.0.0.10:3306/demo?useSSLfalse\,\root\,\pwd\] }列表接口支持按类型过滤:GET /datasources?searchValtypeMYSQLpageNo1pageSize20。平台覆盖 MySQL、PostgreSQL、Oracle、Hive、Spark、ClickHouse、Doris、StarRocks 等常见类型,建源前先确认类型名与任务里声明的一致。第 4 步:触发执行,操控工作流与任务实例工作流发布后,执行动作集中在实例接口上。查询走/v2/workflow-instances,支持按状态、执行人、时间窗过滤:curl -X GET http://localhost:12345/dolphinscheduler/api/v2/workflow-instances?pageNo1pageSize10stateTypeRUNNING \ -H token: your-access-token要对某个实例做操作,向它的 execute 端点发 POST,用executeType指定动作。STOP(停止)和PAUSE(暂停)是日常最常用的两个值,完整枚举还有重跑、从失败处恢复、只跑失败任务等,定义见 ExecuteType.java:curl -X POST http://localhost:12345/dolphinscheduler/api/v2/workflow-instances/3001/execute?executeTypeSTOP \ -H token: your-access-token细粒度到单个任务时,用任务实例接口(/v2/projects/{projectCode}/task-instances):列表和详情都是 GET,出问题后两个动作最实用——POST /{id}/rerun:重跑这个任务;POST /{id}/kill:强杀卡住的任务。删掉历史实例释放查询范围:DELETE /v2/workflow-instances/{id}和对应的任务实例 DELETE。第 5 步:看统计,确认系统在健康跑状态统计接口按时间窗聚合,适合接到自己的报表或告警里:curl -X GET http://localhost:12345/dolphinscheduler/api/v2/statistics/task-state-count?startDate2026-09-01endDate2026-09-11 \ -H token: your-access-token/workflow-state-count结构相同,查的是工作流维度;projectCode参数可选,不传就是全局口径。配合实例列表的状态过滤,任务堆积、失败率突增都能第一时间发现。顺带一提:用户与权限接口管理类操作集中在/users:POST 创建、GET 列表、PUT /{id}更新、DELETE /{id}删除。关键动作是授权——POST /users/{id}/grant-project把项目使用权授给某个用户,否则该用户建好项目也操作不了。如果你打算用 API 做批量自动化,建议给脚本单独开一个低权限账号,再用令牌认证,别直接用 admin 的令牌跑日常脚本。排错速查:错误码与高频坑DolphinScheduler 的响应统一包在code/msg/data里,先看code:错误码含义处理建议0成功—10000参数错误对照接口定义检查必填项和格式10001数据库错误检查后端库连接,稍后重试10002重复操作同名资源已存在,换名或先删10003权限不足确认令牌对应用户是否被授权了目标项目10004资源不存在projectCode / 实例 id 抄错是最常见原因10005系统繁忙指数退避后重试,或错峰执行排错时的几个高频坑:令牌过期:表现为突然全部 10003/401 类失败,先检查 expireTime,别怀疑代码;globalParams 套娃:它要求字符串里再嵌一段 JSON,手动拼请求体时最容易在这里翻车;projectCode 传错:实例、任务接口路径里都带 projectCode,和项目 code 不是一个体系(一个是数字 id 一个是长编码),混淆会直接 10004;重复创建:10002 出现时,通常是你重试了同一个 POST,加幂等判断或先查后建。处理响应时建议把分支写死,别用字符串匹配msg:// 统一处理入口:只看 code public void handle(Result result) { if (result.getCode() 0) { process(result.getData()); } else if (result.getCode() 10003) { throw new SecurityException(权限不足: result.getMsg()); } else if (result.getCode() 10004) { throw new IllegalArgumentException(资源不存在,检查 projectCode/id: result.getMsg()); } else { throw new RuntimeException(API 调用失败: result.getMsg()); } }进阶:批量调用的性能与稳定性脚本跑通了之后,量上来再考虑这几件事:连接复用:用带连接池的 HTTP 客户端,避免每次请求都重新建连;批量优先:能用批量端点就不循环单条调用,批次之间留 100ms 左右间隔,给服务端喘息;本地缓存:项目列表、数据源列表这类低频变更的数据,缓存几分钟足够,别每个任务都查一遍;重试策略:只对幂等的 GET 和 10005(系统繁忙)做指数退避重试,POST 创建类请求失败先查是否已建成,避免 10002;异步化:批量导入定义这类耗时操作放后台线程,主流程只做提交和轮询。升级与版本兼容提醒接口整体保持向后兼容,但老版本路径(如不带/v2前缀的旧接口)在新版本中会逐渐淡出。升级前建议做三件事:清点脚本里用到的全部路径,对照新版说明确认仍可用;在测试环境跑一遍核心链路(建项目→建工作流→执行→查统计);关注发布说明里与参数默认值相关的变更,这类变更不报错但行为会变。下一步该做什么从 admin 账号申请一个专用令牌,有效期设成和你们的安全策略一致;用本文第 1~2 步的示例,在测试环境建一个最小项目,跑通一个两节点工作流;给统计接口加一层轮询或告警,失败率超阈值就通知到人;把 10003/10004 两个高频错误码的处理逻辑写进客户端,别等线上踩到;需要核对某个接口的精确参数时,直接翻 dolphinscheduler-api 模块下的控制器源码,那里和线上行为完全一致。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考