DolphinScheduler API 集成实战指南：从令牌认证到工作流全生命周期管理

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如果你正在搭建自动化数据平台想让外部系统数据中台、监控告警、CI/CD 流水线与调度引擎联动而不是在页面上一次次手工点击那么 DolphinScheduler API 就是你需要的遥控器。Apache DolphinScheduler 是新一代数据编排平台支持用低代码方式编排高吞吐的工作流而它提供的 RESTful API 覆盖了项目、工作流、任务、实例、数据源与权限管理的全部能力。本文将沿着一条从零创建每日数据汇总工作流的主线带你完整走通 DolphinScheduler API 接口调用的每一步从令牌认证到实例监控全程配真实可用的请求示例。一、为什么你需要 API 而不是鼠标点击很多团队在使用 DolphinScheduler 时工作流都是靠 UI 手动配置的。一旦规模上来痛点就非常明显重复劳动几十个项目、上百条工作流靠手工创建既慢又容易出错难以自动化发布流水线无法自动部署工作流版本难以追踪无法联动外部系统如数据治理平台无法按需触发或查询调度状态。用 API 调用的方式上述问题可以一并解决。下表对比了两种方式的差异对比维度页面操作API 调用创建项目/工作流逐条手工配置脚本批量创建与第三方系统集成不支持通过 token 鉴权直连触发与状态查询依赖人工盯页面定时轮询或回调可审计性无请求留痕、审计日志DolphinScheduler 的 API 控制器代码集中在dolphinscheduler-api模块官方 Swagger 文档会随服务启动自动生成方便随时查阅全部接口定义。二、动手前的三项准备2.1 环境搭建拿到一个可用的服务最简单的方式是使用源码自带的 Docker Compose 一键起服务git clone https://gitcode.com/GitHub_Trending/dol/dolphinscheduler cd dolphinscheduler docker compose -f deploy/docker/docker-compose.yml up -d服务启动后API Server 默认监听12345端口前端页面地址为http://localhost:12345/dolphinscheduler/ui。首次登录使用默认账号admin/dolphinscheduler123。2.2 令牌认证给 API 配一把钥匙DolphinScheduler API 支持 Token、SessionCookie与 Basic 三种认证方式其中Token 认证最适合脚本和第三方集成。官方文档路径docs/docs/zh/guide/api/open-api.md。获取 Token 的步骤登录控制台进入安全中心 → 令牌管理点击令牌管理创建令牌选择失效时间并指定操作人用户生成后拷贝 Token 字符串并提交。之后所有 API 请求在 Header 中携带token即可token: 上一步生成的Token字符串 Accept: application/json2.3 认识你的接口字典Swagger 文档服务启动后直接打开 Swagger 页面即可浏览全部 DolphinScheduler API 接口http://{api server ip}:12345/dolphinscheduler/swagger-ui/index.html?languagezh_CNlangcn页面左侧按功能模块access token、alert group、process definition 等分组右侧列出每个接口的 HTTP 方法、路径与参数说明。后续所有接口路径均以这里为准。三、主线实战用 API 搭建每日数据汇总工作流这一节是全篇主线。我们将用纯 API 调用完成创建项目 → 创建工作流 → 上线发布 → 触发执行 → 查询状态五个步骤跑通一条完整链路。第一步创建项目curl -X POST http://localhost:12345/dolphinscheduler/projects \ -H Content-Type: application/json \ -H token: YOUR_TOKEN \ -d { projectName: daily-report, description: 每日数据汇总项目 }响应中的code为0即代表成功{ code: 0, msg: success, data: { code: 123456789, name: daily-report, description: 每日数据汇总项目 } }在 Postman 中的完整效果如下返回200 OK与msg: success即表示创建成功请记录返回的data.code它就是后续所有接口都要用到的projectCode。第二步创建工作流定义工作流定义是整个编排的核心一个定义内可以包含多个任务节点并通过preTasks声明依赖关系。创建接口为curl -X POST http://localhost:12345/dolphinscheduler/projects/{projectCode}/workflow-definition \ -H Content-Type: application/json \ -H token: YOUR_TOKEN \ -d { name: daily_summary, description: 每日数据汇总流程, globalParams: [{\prop\:\bizDate\,\value\:\${system.datetime}\}], locations: {\数据抽取\:{\x\:100,\y\:100}}, tasks: [ { name: 数据抽取, taskType: SQL, params: { type: MYSQL, datasource: 1, sql: SELECT * FROM orders WHERE dt ${bizDate} } }, { name: 数据汇总, taskType: SHELL, params: { rawScript: python3 /opt/summary.py ${bizDate} }, preTasks: [数据抽取] } ] }对应源码在 dolphinscheduler-api/.../WorkflowDefinitionController.java其RequestMapping(projects/{projectCode}/workflow-definition)下注册了创建、复制、发布、版本管理等整套子接口。第三步上线发布刚创建的工作流处于下线状态需要先发布才能被调度。调用发布接口curl -X POST http://localhost:12345/dolphinscheduler/projects/{projectCode}/workflow-definition/{code}/release \ -H Content-Type: application/json \ -H token: YOUR_TOKEN \ -d {releaseState: ONLINE}第四步触发执行发布后通过 Executor 控制器立即触发一次运行接口路径为projects/{projectCode}/executors/start-workflow-instancecurl -X POST http://localhost:12345/dolphinscheduler/projects/{projectCode}/executors/start-workflow-instance \ -H Content-Type: application/json \ -H token: YOUR_TOKEN \ -d { workflowDefinitionCode: 987654321, failureStrategy: CONTINUE, warningType: NONE, warningGroupId: , execType: START_PROCESS, runMode: RUN_MODE_SERIAL, processInstancePriority: MEDIUM, workerGroup: default, version: 1 }第五步查询实例状态执行后可以轮询实例列表确认运行结果curl -X GET http://localhost:12345/dolphinscheduler/projects/{projectCode}/workflow-instances?pageNo1pageSize10 \ -H token: YOUR_TOKEN实例状态字段如RUNNING_EXECUTION、SUCCESS、FAILURE可在控制台首页的统计面板中直观核对至此一条建项目 → 建流程 → 发布 → 触发 → 监控的完整闭环已经用纯 API 跑通。四、核心接口模块速查表围绕主线案例把最常用的接口按模块整理如下方便日常开发时快速查阅。4.1 认证与会话方法路径用途POST/login用户名密码登录换取 SessionPOST/signOut注销会话相关/access-tokensToken 的创建、查询、删除登录接口示例curl -X POST http://localhost:12345/dolphinscheduler/login \ -H Content-Type: application/json \ -d {userName:admin,userPassword:dolphinscheduler123}4.2 项目方法路径用途POST/projects创建项目GET/projects分页查询项目列表GET/projects/{code}查询项目详情PUT/projects/{code}更新项目DELETE/projects/{code}删除项目GET/projects/list查询所有项目无分页查询项目列表curl -X GET http://localhost:12345/dolphinscheduler/projects/list -H token: YOUR_TOKEN用 Postman 发送该请求响应会返回项目列表与 Swagger 中的接口描述一一对应4.3 工作流定义与任务定义模块方法路径用途工作流POST/projects/{projectCode}/workflow-definition创建工作流工作流GET/projects/{projectCode}/workflow-definition分页查询工作流PUT/projects/{projectCode}/workflow-definition/{code}更新定义工作流POST/projects/{projectCode}/workflow-definition/{code}/release上线/下线工作流GET/projects/{projectCode}/workflow-definition/{code}/versions版本列表工作流DELETE/projects/{projectCode}/workflow-definition/{code}删除定义任务GET/projects/{projectCode}/workflow-definition/{code}/tasks查询定义内任务任务GET/projects/{projectCode}/task-definition查询任务定义列表4.4 工作流实例与任务实例方法路径用途GET/projects/{projectCode}/workflow-instances分页查询实例GET/projects/{projectCode}/workflow-instances/{id}实例详情GET/projects/{projectCode}/workflow-instances/{id}/tasks实例下的任务列表GET/projects/{projectCode}/workflow-instances/{id}/view-gantt甘特图数据GET/projects/{projectCode}/task-instances分页查询任务实例POST/projects/{projectCode}/executors/execute对实例执行重跑/暂停等操作4.5 数据源、用户与监控模块方法路径用途数据源POST/datasources创建数据源数据源GET/datasources分页查询数据源POST/datasources/connect测试连接用户POST/users创建用户用户POST/users/{id}/grant-project授权项目监控GET/projects/analysis/task-state-count任务状态统计监控GET/monitor/servers服务节点监控数据源 API 覆盖 MySQL、PostgreSQL、Hive、Spark、ClickHouse、Doris、StarRocks 等二十余种类型创建时通过type字段指定即可。五、响应规范与错误码避坑所有 DolphinScheduler API 接口统一返回如下结构的 JSON{ code: 0, msg: success, data: {} }code 0成功code ! 0失败msg中附带可读的错误描述。code的定义集中在dolphinscheduler-api模块的Status枚举中常用值如下code含义处理建议0成功正常处理10000服务端异常查看服务端日志10001请求参数无效核对参数名与格式10013用户名或密码错误检查登录凭据10016数据源连接失败检查数据源地址与账号10018项目不存在确认 projectCode 是否正确10019项目已存在先查询再决定是否创建完整枚举可见源码 dolphinscheduler-api/.../enums/Status.java。六、进阶技巧与高频坑位6.1 用脚本批量创建任务避免逐个请求import requests BASE http://localhost:12345/dolphinscheduler HEADERS {token: YOUR_TOKEN, Content-Type: application/json} def create_project(name, desc): resp requests.post(f{BASE}/projects, json{ projectName: name, description: desc }, headersHEADERS) resp.raise_for_status() return resp.json()[data][code] # 批量创建多个项目 for item in [(report_a, 报表A), (report_b, 报表B)]: print(create_project(*item))注意控制请求频率大批量操作建议加入短暂间隔如time.sleep(0.1)避免打满 API Server 线程池。6.2 高可用架构下的调用要点在集群部署Master Worker API 多节点环境下API 是无状态的前端任意节点均可处理请求可通过负载均衡暴露统一入口。调度与容错细节可参考项目架构文档 docs/docs/zh/architecture 下的设计说明。6.3 常见坑位排查清单现象大概率原因解决办法返回 10013token 无效或已过期重新生成 token检查失效时间返回 10001Content-Type 未设置为 application/json请求头补齐Accept与Content-Type返回 10018projectCode 传成了字符串名称使用创建项目时返回的数字 code创建任务失败preTasks引用了不存在的任务名先创建前置任务再声明依赖触发执行无响应工作流未上线或版本号不符先调用 release 接口上线核对 version七、收尾让调度平台真正成为可编程的基础设施本文通过创建项目 → 定义工作流 → 发布 → 触发 → 监控这条主线完整覆盖了 DolphinScheduler API 接口调用的核心路径令牌认证、常用接口速查、统一响应规范与错误码、批量脚本与避坑清单。如果你已经掌握了这些内容下一步建议打开 Swagger 文档逐个试调本项目中尚未用到的接口为你的团队封装一套 Python/Java 的 API Client统一鉴权与错误处理将工作流的创建与发布接入 CI/CD实现代码即调度。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），仅供参考