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），僅供參考