企业官网建设流程全解析

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

Apache DolphinScheduler 把项目、工作流、任务的管理全部开放为一套 RESTful 接口：创建、触发、监控、清理，都能用 API 调用完成。这份手册带你从发出第一个请求，到完整跑通一条 ETL 工作流。

接入第一步：拿到 Token，发出第一个请求

⚠️ 所有接口都挂在 API 服务后面，基础 URL 形如：

http://{host}:{port}/dolphinscheduler/api

单机部署默认端口是 12345，按实际部署值替换。认证有三种方式，选哪种取决于你是谁：

从零发出第一个请求，按这四步走：

1. 登录换会话：POST /login，表单参数userName和userPassword，成功后响应会写入 Session Cookie。
2. （脚本场景）创建 Access Token：POST /access-tokens，传userId和expireTime（格式yyyy-MM-dd HH:mm:ss）。给其他用户建 Token 需要管理员权限，给自己建则用普通账号即可。
3. 拼 URL：基础 URL + 接口路径，路径变量（如projectCode）用真实值替换。
4. 带上凭证发请求：带 Cookie 或在 Header 里传token: 你的Token值，Content-Type 为application/x-www-form-urlencoded（多数接口接收的是表单参数而非 JSON Body，这点后面会专门提醒）。

最小可运行的登录示例：

curl -X POST "http://localhost:12345/dolphinscheduler/api/login" \ -d "userName=admin&userPassword=dolphinscheduler123"

返回"code":0就说明通了，后续接口都可以照这个模式发。

接口全景：按资源生命周期找端点

接口全部集中在 dolphinscheduler-api/ 的controller包下。与其平铺 30 多个控制器，不如按资源的生命周期分四层来记：定义 → 运行 → 基础设施 → 观测。

资源定义层：项目 / 工作流 / 任务定义

创建工作流是最容易踩坑的接口：它接收的是表单参数，而taskDefinitionJson、taskRelationJson是塞在参数里的 JSON 字符串。任务定义长这样：

[ { "name": "shell_extract", "taskType": "SHELL", "taskParams": { "rawScript": "echo 'etl start'" }, "workerGroup": "default", "failRetryTimes": 2, "timeoutFlag": "CLOSE" } ]

依赖关系用taskRelationJson表达，preTaskCode为0表示起点：

[ { "preTaskCode": 0, "postTaskCode": 18213456789012346 } ]

taskType支持SHELL、SQL、SPARK、FLINK、PYTHON、DATAX等几十种，任务参数结构见各 task-plugin 模块的文档。

运行控制层：触发、停止、重跑

基础设施层：数据源、用户、权限

可观测层：状态、统计、日志

场景走通：从建项目到跑通一条 ETL 工作流

下面用一个真实场景串起来：建项目 → 建工作流 → 上线 → 触发 → 看结果。按顺序执行即可。

第 1 步：登录，保存会话 Cookie

curl -X POST "http://localhost:12345/dolphinscheduler/api/login" \ -d "userName=admin&userPassword=dolphinscheduler123" -c /tmp/ds.txt

返回{"code":0,...}即登录成功，Session 写入/tmp/ds.txt。

第 2 步：创建一个 Access Token

curl -X POST "http://localhost:12345/dolphinscheduler/api/access-tokens" \ -b /tmp/ds.txt -d "userId=1&expireTime=2027-01-01 00:00:00"

返回{"code":0,"data":{"id":1,"token":"a1b2c3d4...","expireTime":"2027-01-01 00:00:00"}}。记下token字段，后面所有请求都用它代替 Cookie。

第 3 步：创建项目

curl -X POST "http://localhost:12345/dolphinscheduler/api/projects" \ -H "token: a1b2c3d4..." -d "projectName=data_etl&description=ETL调度项目"

返回{"code":0,"data":{"code":18213456789012345,"name":"data_etl",...}}。data.code是雪花算法生成的项目编码，后面所有路径里的projectCode都用它，注意不是自增主键 ID。

第 4 步：创建工作流定义（单个 SHELL 任务）

curl -X POST "http://localhost:12345/dolphinscheduler/api/projects/18213456789012345/workflow-definition" \ -H "token: a1b2c3d4..." \ --data-urlencode "name=daily_etl" \ --data-urlencode "taskDefinitionJson=[{\"name\":\"shell_extract\",\"taskType\":\"SHELL\",\"taskParams\":{\"rawScript\":\"echo 'extract ok'\"},\"workerGroup\":\"default\"}]" \ --data-urlencode "taskRelationJson=[{\"preTaskCode\":0,\"postTaskCode\":18213456789012346}]"

返回{"code":0,"data":{"code":18213456789012346,"name":"daily_etl","releaseState":"OFFLINE"}}。工作流创建后默认是OFFLINE，此时还不能触发，必须先上线。

第 5 步：上线工作流

curl -X PUT "http://localhost:12345/dolphinscheduler/api/projects/18213456789012345/workflow-definition/18213456789012346/release" \ -H "token: a1b2c3d4..." -d "releaseState=ONLINE"

返回{"code":0,"data":{"releaseState":"ONLINE"}}，定义进入可调度状态。

第 6 步：触发执行

curl -X POST "http://localhost:12345/dolphinscheduler/api/projects/18213456789012345/executors/start-workflow-instance" \ -H "token: a1b2c3d4..." \ -d "workflowDefinitionCode=18213456789012346&scheduleTime=2026-09-11 00:00:00&failureStrategy=CONTINUE&warningType=NONE"

返回{"code":0,"data":[201]}，data里就是新产生的工作流实例 ID。

第 7 步：轮询实例状态

curl "http://localhost:12345/dolphinscheduler/api/projects/18213456789012345/workflow-instances/201" \ -H "token: a1b2c3d4..."

返回{"code":0,"data":{"id":201,"state":"SUCCESS","startTime":"2026-09-11 10:00:01","endTime":"2026-09-11 10:00:03"}}，state从RUNNING_EXECUTION变为SUCCESS就算跑通了。要看具体输出，拿任务实例 ID 去GET /log拉日志。

跑通之后建议加一层重试包装：对 429 和 5xx 做指数退避重试（1s、2s、4s……封顶 30s），网络抖动和限流都能自愈；成功响应则不要重试，避免触发重复执行。

排错速查：错误码与高频坑

所有业务响应都长这样：{"code":业务码,"msg":说明,"data":数据}，code为0表示成功，HTTP 状态码正常是 200。认证失败和限流走的是 HTTP 状态码，别漏了看。

错误码速查

高频踩坑

🔧 这几个坑新手基本都会撞一次：

• Token 过期后没刷新，一直 401。Token 创建时就定死了expireTime，服务端每次请求都用当前时间校验，过期即 401，没有"续期"概念。长跑脚本要么把有效期设长，要么在失败分支里重建 Token。
• 给创建工作流接口塞 JSON Body。它收的是表单参数，taskDefinitionJson是"参数里的 JSON 字符串"。curl 必须用--data-urlencode，直接-d '{...}'整个 Body 会报 10001。
• 批量触发没限频，撞 429。API 服务内置了全局 + 租户双级 QPS 限流（按 Token 维度），循环狂发start-workflow-instance很容易被拒。批量场景改用batch-start-workflow-instance，或请求间隔加 sleep。
• 把项目 ID 当 projectCode 用。路径变量要的是雪花编码，GET /projects返回里id和code是两个字段，用错那个会得到 10018。
• 忘上线就触发。新建工作流是OFFLINE状态，跳过 release 直接 start 会失败，上线这步别省。

调优清单：让调用又快又稳

⚡ 接口本身没有太多可调项，稳定主要靠客户端纪律：

• 用 HTTP 连接池复用连接（keep-alive），别每次请求新建 TCP 连接
• 批量触发走批量接口，或请求间加间隔，主动避开 429
• projectCode、workflowDefinitionCode这类编码存下来本地缓存，编码不会变，别反复查询
• 列表查询永远带pageNo/pageSize，不要为了"拿全量"把 pageSize 设到几千
• 对 429 和 5xx 实现指数退避重试，对 2xx 的成功响应绝不重试
• 升级版本前先回归一遍现有集成，RESTful 路径总体保持向后兼容，但个别参数默认值可能调整

接下来去哪

完整参数清单不必死记，每个接口都带 Swagger 注解，启动 API 服务后可直接在界面里浏览调试。建议从 dolphinscheduler-api/ 的 controller 目录读起，再配合 官方文档 里的部署与配置章节，遇到具体任务类型参数时查对应 task-plugin 模块。

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler