首页
/ DolphinScheduler API文档：完整接口参考手册

DolphinScheduler API文档：完整接口参考手册

2026-02-04 04:44:35作者：盛欣凯Ernestine
dolphinscheduler
Apache 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接口，支持通过编程方式管理任务调度和工作流。本文档提供DolphinScheduler所有API接口的详细参考，帮助开发者快速集成和使用。

API基础信息

认证方式

DolphinScheduler API支持多种认证方式：

认证方式 说明 适用场景
Token认证 使用Access Token进行身份验证 自动化脚本、第三方集成
Session认证 基于Cookie的会话认证 Web UI交互
Basic认证 用户名密码基础认证 简单集成场景

请求格式

  • Content-Type: application/json
  • 响应格式: JSON
  • 编码: UTF-8

基础URL

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

核心API接口分类

1. 项目管理API

项目管理API用于创建、查询、更新和删除项目。

// 项目控制器基础路径
@RestController
@RequestMapping("/v2/projects")
public class ProjectV2Controller {
    
    @ApiOperation("创建项目")
    @PostMapping
    public Result createProject(@RequestBody ProjectCreateRequest createRequest) {
        // 实现逻辑
    }
    
    @ApiOperation("查询项目列表")
    @GetMapping
    public Result<PageInfo<ProjectVO>> queryProjectList(
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
}

主要接口：

  • POST /v2/projects - 创建新项目
  • GET /v2/projects - 查询项目列表
  • GET /v2/projects/{projectCode} - 查询项目详情
  • PUT /v2/projects/{projectCode} - 更新项目信息
  • DELETE /v2/projects/{projectCode} - 删除项目

2. 工作流定义API

工作流定义API用于管理工作流的创建、版本控制和部署。

@RestController
@RequestMapping("projects/{projectCode}/workflow-definition")
public class WorkflowDefinitionController {
    
    @ApiOperation("创建工作流定义")
    @PostMapping
    public Result createWorkflowDefinition(
            @PathVariable("projectCode") long projectCode,
            @RequestBody WorkflowDefinitionCreateRequest createRequest) {
        // 实现逻辑
    }
    
    @ApiOperation("查询工作流定义列表")
    @GetMapping
    public Result queryWorkflowDefinitionList(
            @PathVariable("projectCode") long projectCode,
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam(value = "userId", required = false) Integer userId,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
}

主要接口：

  • POST /projects/{projectCode}/workflow-definition - 创建工作流
  • GET /projects/{projectCode}/workflow-definition - 查询工作流列表
  • PUT /projects/{projectCode}/workflow-definition/{code} - 更新工作流
  • DELETE /projects/{projectCode}/workflow-definition/{code} - 删除工作流
  • POST /projects/{projectCode}/workflow-definition/{code}/release - 发布工作流

3. 任务定义API

任务定义API用于管理具体任务的配置和执行。

@RestController
@RequestMapping("projects/{projectCode}/task-definition")
public class TaskDefinitionController {
    
    @ApiOperation("创建任务定义")
    @PostMapping
    public Result createTaskDefinition(
            @PathVariable("projectCode") long projectCode,
            @RequestBody TaskDefinitionCreateRequest createRequest) {
        // 实现逻辑
    }
    
    @ApiOperation("查询任务定义列表")
    @GetMapping
    public Result queryTaskDefinitionList(
            @PathVariable("projectCode") long projectCode,
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam(value = "taskType", required = false) String taskType,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
}

主要接口：

  • POST /projects/{projectCode}/task-definition - 创建任务
  • GET /projects/{projectCode}/task-definition - 查询任务列表
  • GET /projects/{projectCode}/task-definition/{code} - 查询任务详情
  • PUT /projects/{projectCode}/task-definition/{code} - 更新任务
  • DELETE /projects/{projectCode}/task-definition/{code} - 删除任务

4. 工作流实例API

工作流实例API用于监控和管理运行中的工作流实例。

@RestController
@RequestMapping("/v2/workflow-instances")
public class WorkflowInstanceV2Controller {
    
    @ApiOperation("查询工作流实例列表")
    @GetMapping
    public Result queryWorkflowInstanceList(
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam(value = "executorName", required = false) String executorName,
            @RequestParam(value = "host", required = false) String host,
            @RequestParam(value = "stateType", required = false) String stateType,
            @RequestParam(value = "startDate", required = false) String startDate,
            @RequestParam(value = "endDate", required = false) String endDate,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
    
    @ApiOperation("启停工作流实例")
    @PostMapping("/{workflowInstanceId}/execute")
    public Result executeWorkflowInstance(
            @PathVariable("workflowInstanceId") Integer workflowInstanceId,
            @RequestParam("executeType") ExecuteType executeType) {
        // 实现逻辑
    }
}

主要接口：

  • GET /v2/workflow-instances - 查询工作流实例列表
  • GET /v2/workflow-instances/{id} - 查询工作流实例详情
  • POST /v2/workflow-instances/{id}/execute - 执行工作流实例操作
  • DELETE /v2/workflow-instances/{id} - 删除工作流实例

5. 任务实例API

任务实例API用于监控和管理具体的任务执行情况。

@RestController
@RequestMapping("/v2/projects/{projectCode}/task-instances")
public class TaskInstanceV2Controller {
    
    @ApiOperation("查询任务实例列表")
    @GetMapping
    public Result queryTaskInstanceList(
            @PathVariable("projectCode") long projectCode,
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam(value = "executorName", required = false) String executorName,
            @RequestParam(value = "host", required = false) String host,
            @RequestParam(value = "stateType", required = false) String stateType,
            @RequestParam(value = "startDate", required = false) String startDate,
            @RequestParam(value = "endDate", required = false) String endDate,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
}

主要接口：

  • GET /v2/projects/{projectCode}/task-instances - 查询任务实例列表
  • GET /v2/projects/{projectCode}/task-instances/{id} - 查询任务实例详情
  • POST /v2/projects/{projectCode}/task-instances/{id}/rerun - 重跑任务实例
  • POST /v2/projects/{projectCode}/task-instances/{id}/kill - 杀死任务实例

6. 数据源管理API

数据源API用于管理各种类型的数据源连接。

@RestController
@RequestMapping("datasources")
public class DataSourceController {
    
    @ApiOperation("创建数据源")
    @PostMapping
    public Result createDataSource(@RequestBody DataSourceCreateRequest createRequest) {
        // 实现逻辑
    }
    
    @ApiOperation("查询数据源列表")
    @GetMapping
    public Result queryDataSourceList(
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam(value = "type", required = false) String type,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
}

支持的数据源类型：

  • MySQL、PostgreSQL、Oracle
  • Hive、Spark、Flink
  • ClickHouse、Doris、StarRocks
  • Kafka、Redis、Elasticsearch

7. 用户和权限API

用户权限API用于管理系统用户、角色和权限控制。

@RestController
@RequestMapping("/users")
public class UsersController {
    
    @ApiOperation("创建用户")
    @PostMapping
    public Result createUser(@RequestBody UserCreateRequest createRequest) {
        // 实现逻辑
    }
    
    @ApiOperation("查询用户列表")
    @GetMapping
    public Result queryUserList(
            @RequestParam(value = "searchVal", required = false) String searchVal,
            @RequestParam("pageNo") Integer pageNo,
            @RequestParam("pageSize") Integer pageSize) {
        // 实现逻辑
    }
}

主要接口：

  • POST /users - 创建用户
  • GET /users - 查询用户列表
  • PUT /users/{id} - 更新用户信息
  • DELETE /users/{id} - 删除用户
  • POST /users/{id}/grant-project - 授予项目权限

8. 监控和统计API

监控API提供系统运行状态和性能指标的查询功能。

@RestController
@RequestMapping("/v2/statistics")
public class StatisticsV2Controller {
    
    @ApiOperation("查询任务状态统计")
    @GetMapping("/task-state-count")
    public Result queryTaskStateCount(
            @RequestParam(value = "startDate") String startDate,
            @RequestParam(value = "endDate") String endDate,
            @RequestParam(value = "projectCode", required = false) Long projectCode) {
        // 实现逻辑
    }
    
    @ApiOperation("查询工作流状态统计")
    @GetMapping("/workflow-state-count")
    public Result queryWorkflowStateCount(
            @RequestParam(value = "startDate") String startDate,
            @RequestParam(value = "endDate") String endDate,
            @RequestParam(value = "projectCode", required = false) Long projectCode) {
        // 实现逻辑
    }
}

监控指标：

  • 任务执行状态统计
  • 工作流运行状态统计
  • 系统资源使用情况
  • 队列任务堆积情况

API使用示例

示例1：创建项目

curl -X POST "http://localhost:12345/dolphinscheduler/api/v2/projects" \
  -H "Content-Type: application/json" \
  -H "token: your-access-token" \
  -d '{
    "projectName": "数据分析平台",
    "description": "用于大数据分析任务调度",
    "userName": "admin"
  }'

响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "code": 1000001,
    "name": "数据分析平台",
    "description": "用于大数据分析任务调度",
    "userName": "admin",
    "createTime": "2024-01-15 10:30:00",
    "updateTime": "2024-01-15 10:30:00"
  }
}

示例2：创建工作流

curl -X POST "http://localhost:12345/dolphinscheduler/api/projects/1000001/workflow-definition" \
  -H "Content-Type: application/json" \
  -H "token: your-access-token" \
  -d '{
    "name": "每日数据ETL流程",
    "description": "每日定时执行的数据抽取转换加载流程",
    "globalParams": "[{\"prop\":\"bizDate\",\"value\":\"${system.datetime}\"}]",
    "tasks": [
      {
        "name": "数据抽取",
        "taskType": "SQL",
        "description": "从源数据库抽取数据",
        "params": {
          "type": "MYSQL",
          "datasource": 1,
          "sql": "SELECT * FROM source_table WHERE biz_date = '${bizDate}'"
        }
      },
      {
        "name": "数据转换",
        "taskType": "SPARK",
        "description": "使用Spark进行数据清洗转换",
        "params": {
          "programType": "SQL",
          "mainClass": "",
          "sparkVersion": "SPARK3",
          "deployMode": "cluster",
          "appResource": "hdfs://path/to/etl-job.jar",
          "mainArgs": "--date ${bizDate}"
        },
        "preTasks": ["数据抽取"]
      }
    ]
  }'

示例3：查询工作流实例

curl -X GET "http://localhost:12345/dolphinscheduler/api/v2/workflow-instances? \
  pageNo=1&pageSize=10&stateType=RUNNING&startDate=2024-01-15&endDate=2024-01-16" \
  -H "token: your-access-token"

错误码参考

DolphinScheduler使用统一的错误码体系：

错误码 说明 解决方案
0 成功 -
10000 参数错误 检查请求参数格式
10001 数据库错误 检查数据库连接状态
10002 重复操作 避免重复提交相同请求
10003 权限不足 检查用户权限设置
10004 资源不存在 检查资源ID是否正确
10005 系统繁忙 稍后重试或扩容系统

最佳实践

1. 认证管理

// 获取Access Token
public String getAccessToken(String username, String password) {
    String auth = Base64.getEncoder().encodeToString((username + ":" + password).getBytes());
    // 调用认证接口获取token
    return token;
}

// 使用Token发起请求
public Result callApiWithToken(String endpoint, Object request) {
    HttpHeaders headers = new HttpHeaders();
    headers.set("token", accessToken);
    headers.setContentType(MediaType.APPLICATION_JSON);
    
    HttpEntity<Object> entity = new HttpEntity<>(request, headers);
    return restTemplate.exchange(baseUrl + endpoint, HttpMethod.POST, entity, Result.class);
}

2. 错误处理

public void handleApiResponse(Result result) {
    if (result.getCode() == 0) {
        // 成功处理
        processSuccess(result.getData());
    } else {
        // 错误处理
        switch (result.getCode()) {
            case 10000:
                throw new IllegalArgumentException("参数错误: " + result.getMsg());
            case 10003:
                throw new SecurityException("权限不足: " + result.getMsg());
            default:
                throw new RuntimeException("API调用失败: " + result.getMsg());
        }
    }
}

3. 批量操作优化

// 批量创建任务避免频繁调用
public void batchCreateTasks(List<TaskDefinition> tasks) {
    int batchSize = 50;
    for (int i = 0; i < tasks.size(); i += batchSize) {
        List<TaskDefinition> batch = tasks.subList(i, Math.min(i + batchSize, tasks.size()));
        createTaskBatch(batch);
        Thread.sleep(100); // 避免请求过于频繁
    }
}

性能优化建议

  1. 连接池配置: 使用HTTP连接池减少连接建立开销
  2. 请求合并: 对批量操作使用批量接口
  3. 缓存策略: 对频繁查询的数据添加本地缓存
  4. 异步处理: 对耗时操作使用异步调用方式
  5. 重试机制: 实现指数退避的重试策略

版本兼容性

DolphinScheduler API保持向后兼容性，但建议：

  • 使用最新的API版本（v2）
  • 在升级时测试现有集成功能
  • 关注官方发布的版本变更说明

总结

DolphinScheduler提供了完整且强大的API体系，覆盖了任务调度的全生命周期管理。通过合理使用这些API，开发者可以构建高度自动化的数据调度平台，实现与现有系统的无缝集成。

建议在实际使用前：

  1. 仔细阅读相关接口的详细文档
  2. 进行充分的测试验证
  3. 实现适当的错误处理和重试机制
  4. 监控API调用性能和稳定性

通过本文档的指导，您应该能够快速上手并使用DolphinScheduler的API功能来满足您的业务需求。

dolphinscheduler
Apache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code
项目地址：https://gitcode.com/GitHub_Trending/dol/dolphinscheduler
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
docsdocs
暂无描述
Dockerfile
718
4.56 K
pytorchpytorch
Ascend Extension for PyTorch
Python
580
710
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
419
356
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
963
956
atomcodeatomcode
Claude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started
Rust
646
108
Oohos_react_native
React Native鸿蒙化仓库
C++
341
386
kernelkernel
deepin linux kernel
C
28
16
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.62 K
951
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件，通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求，让密码技术应用更简单，同时探索后量子等先进算法创新实践，构建密码前沿技术底座！
C
1.09 K
589
MindSpeed-MMMindSpeed-MM
华为昇腾面向大规模分布式训练的多模态大模型套件，支撑多模态生成、多模态理解。
Python
141
223