DS 2.0 时代 API 操作姿势

DS 2.0 时代 API 接口介绍

背景

​ 众目期待的 apache dolphinschedler 2.0 版本终于在 2021 年 12 月 17 日 发布了，要知道 2.0 版本代码重构了约 70%，从 2021 年 1 月份计划启动大 JSON 拆分，历时 11 个月到 2021 年 12 月 5 号发布 2.0.0（由于非预料 bug 而下线），终于在 12 月 17 号成功发布 2.0.1，随后半个月又发布 2.0.2 及当前的 2.0.3 版本。

​ 在 ds 2.0 版本，接口已改为具有 Restful 风格的请求方式，对应的 swagger 文档地址是 http://ip:port/dolphinscheduler/doc.html ，从swagger文档可以看到，接口分类很明确。我们本次重点介绍工作流、任务、及工作流与任务关系的部分接口。

工作流定义接口

工作流定义在当前版本有 25 个接口，接下来会介绍下比较常用的接口：

接口名称	接口地址	请求方式	功能介绍
createProcessDefinition	/dolphinscheduler/projects/{projectCode}/process-definition	POST	创建具有任务的工作流，对应界面的工作流保存，其中 taskDefinitionJson 和 taskRelationJson 不可为空，以 json 的方式填写必要的信息
createEmptyProcessDefinition	/dolphinscheduler/projects/{projectCode}/process-definition/empty	POST	创建空工作流和定时，其中 scheduleJson 为空时，只创建空工作流而不创建定时
update	/dolphinscheduler/projects/{projectCode}/process-definition/{code}	PUT	根据工作流 code 更新接口，taskDefinitionJson 和 taskRelationJson 不可为空，更新时可指定上下线状态，应用于更新后是否直接上线
updateBasicInfo	/dolphinscheduler/projects/{projectCode}/process-definition/{code}/basic-info	PUT	更新工作流的基本信息和定时信息，scheduleJson 为空时，只更新工作流基本信息
batchDeleteByCodes	/dolphinscheduler/projects/{projectCode}/process-definition/batch-delete	POST	根据工作流 code 批量删除工作流，其中 code 以英文逗号分割
deleteByCode	/dolphinscheduler/projects/{projectCode}/process-definition/{code}	DELETE	根据工作流 code 删除工作流
deleteVersion	/dolphinscheduler/projects/{projectCode}/process-definition/{code}/versions/{version}	DELETE	根据工作流 code 和 version 删除，只能删除非主表应用版本的数据
release	/dolphinscheduler/projects/{projectCode}/process-definition/{code}/release	POST	根据工作流 code 上下线工作流
releaseWorkflowAndSchedule	/dolphinscheduler/projects/{projectCode}/process-definition/{code}/release-workflow	POST	根据工作流 code 同时上下线工作流和定时
switchVersion	/dolphinscheduler/projects/{projectCode}/process-definition/{code}/versions/{version}	GET	根据工作流 code 和 version 切换到指定版本
queryProcessDefinitionByCode	/dolphinscheduler/projects/{projectCode}/process-definition/{code}	GET	根据工作流 code 查询工作流信息，包含任务和工作流任务关系
queryListPaging	/dolphinscheduler/projects/{projectCode}/process-definition	GET	分页查询工作流
queryAllByProjectCode	/dolphinscheduler/projects/{projectCode}/process-definition/all	GET	根据项目 code 查询该项目下所有工作流

任务定义接口

接口名称	接口地址	请求方式	功能介绍
save	/dolphinscheduler/projects/{projectCode}/task-definition	POST	创建任务的接口，taskDefinitionJson 必须是 JSON Array 的方式
update	/dolphinscheduler/projects/{projectCode}/task-definition/{code}	PUT	修改任务的接口，taskDefinitionJsonObj 必须是JSON Object的方式
deleteTaskDefinition	/dolphinscheduler/projects/{projectCode}/task-definition/{code}	DELETE	删除任务的接口，根据任务 code 进行删除
deleteVersion	/dolphinscheduler/projects/{projectCode}/task-definition/{code}/versions/{version}	DELETE	根据任务 code 和 version 删除，只能删除非主表应用版本的数据
switchVersion	/dolphinscheduler/projects/{projectCode}/task-definition/{code}/versions/{version}	GET	根据任务 code 和 version 切换到指定版本
genTaskCodeList	/dolphinscheduler/projects/{projectCode}/task-definition/gen-task-codes	GET	获取 taskCode，根据 genNum 可获取多个
queryTaskDefinitionByCode	/dolphinscheduler/projects/{projectCode}/task-definition/{code}	GET	根据任务 code 查询任务详情信息
queryTaskDefinitionListPaging	/dolphinscheduler/projects/{projectCode}/task-definition	GET	分页查询任务

工作流任务关系接口

接口名称	接口地址	请求方式	功能介绍
save	/dolphinscheduler/projects/{projectCode}/process-task-relation	POST	工作流和任务绑定接口，支持绑定前置任务、绑定后置任务
deleteRelation	/dolphinscheduler/projects/{projectCode}/process-task-relation/{taskCode}	DELETE	工作流和任务解绑，当任务是条件分支、依赖任务、子工作流时同步删除任务
deleteDownstreamRelation	/dolphinscheduler/projects/{projectCode}/process-task-relation/{taskCode}/downstream	DELETE	删除任务的下游依赖，支持批量删除下游
deleteUpstreamRelation	/dolphinscheduler/projects/{projectCode}/process-task-relation/{taskCode}/upstream	DELETE	删除任务的上游依赖，支持批量删除上游
queryDownstreamRelation	/dolphinscheduler/projects/{projectCode}/process-task-relation/{taskCode}/downstream	GET	查询任务的下游依赖
queryUpstreamRelation	/dolphinscheduler/projects/{projectCode}/process-task-relation/{taskCode}/upstream	GET	查询任务的上游依赖

代码调用接口方式

如果单单使用代码调用接口，需要有个 token，这个 token 可以使用 admin 用户在界面生成（创建令牌），也可以通过调用接口获得

Maven 依赖

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.6</version>
</dependency>
复制代码

代码示例

private static String DOLPHIN_BASE_URI = "http://ip:port";
private static String token = "xxx";
private static String sendPost(String uri, List<NameValuePair> params) throws Exception {
    CloseableHttpClient httpclient = HttpClients.createDefault();
    CloseableHttpResponse response = null;
    try {
        UrlEncodedFormEntity formEntity = new UrlEncodedFormEntity(params, Consts.UTF_8);
        HttpPost httpPost = new HttpPost(DOLPHIN_BASE_URI + uri);
        httpPost.setEntity(formEntity);
        httpPost.setHeader("token", token);
        response = httpclient.execute(httpPost);
        return EntityUtils.toString(response.getEntity(), Consts.UTF_8);
    } catch (Exception e) {
        throw new Exception(String.format("[dolphin] The %s call failed", uri));
    } finally {
        try {
            if (response != null) {
                response.close();
            }
            httpclient.close();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}
private static String sendGet(String uri, List<NameValuePair> params) throws Exception {
    CloseableHttpClient httpclient = HttpClients.createDefault();
    CloseableHttpResponse response = null;
    try {
        HttpGet httpGet = new HttpGet(new URIBuilder(DOLPHIN_BASE_URI + uri).setParameters(params).build());
        httpGet.setHeader("token", token);
        response = httpclient.execute(httpGet);
        return EntityUtils.toString(response.getEntity(), Consts.UTF_8);
    } catch (Exception e) {
        throw new Exception(String.format("[dolphin] The %s call failed", uri));
    } finally {
        if (response != null) {
            response.close();
        }
        httpclient.close();
    }
}
复制代码

创建工作流的两种方式

(1) 调用 createProcessDefinition

参数	参数说明	实例值
locations	通过接口调用时可不填写，DAG 界面会给默认值，用户可format后保存重新生成
name	工作流名称	lee-test-01
projectCode	项目 code，必须填写	4362891840832
taskDefinitionJson	task所有信息组成 json Array，在这个接口中 task code 必须含有，task version无需含有	[{"code":4143298469056,"name":"lee-test","description":"","delayTime":0,"taskType":"SHELL","taskParams":{"resourceList":[],"localParams":[],"rawScript":"echo 11333","dependence":{},"conditionResult":{"successNode":[],"failedNode":[]},"waitStartTimeout":{},"switchResult":{}},"flag":"YES","taskPriority":"MEDIUM","workerGroup":"default","failRetryTimes":0,"failRetryInterval":1,"timeoutFlag":"CLOSE","timeoutNotifyStrategy":"WARN","timeout":0,"environmentCode":-1}]
taskRelationJson	dag 上 task 关系描述，postTask表述当前节点	[{"name":"","preTaskCode":0,"preTaskVersion":0,"postTaskCode":4143298469056,"conditionType":0,"conditionParams":{}}]
tenantCode	租户，对应于租户管理的操作系统租户	root
description	工作流描述信息
globalParams	全局参数	[]
timeout	工作流超时时长	0

    public static void main(String[] args) throws Exception {
        long projectCode = 4362891840832L;
        String uri = String.format("/dolphinscheduler/projects/%d/process-definition", projectCode);
        List<NameValuePair> params = new ArrayList<>();
        params.add(new BasicNameValuePair("name", "lee-test-04"));
        params.add(new BasicNameValuePair("projectCode", projectCode + ""));
        String taskDefinitionJson = "[{\"code\":4143298469059,\"name\":\"lee-test-4\",\"description\":\"\",\"delayTime\":0,\"taskType\":\"SHELL\"," +
                "\"taskParams\":{\"resourceList\":[],\"localParams\":[],\"rawScript\":\"echo 11333\",\"dependence\":{},\"conditionResult\"" +
                ":{\"successNode\":[],\"failedNode\":[]},\"waitStartTimeout\":{},\"switchResult\":{}},\"flag\":\"YES\",\"taskPriority\":\"MEDIUM\"," +
                "\"workerGroup\":\"default\",\"failRetryTimes\":0,\"failRetryInterval\":1,\"timeoutFlag\":\"CLOSE\",\"timeoutNotifyStrategy\":\"WARN\"," +
                "\"timeout\":0,\"environmentCode\":-1}]";
        params.add(new BasicNameValuePair("taskDefinitionJson", taskDefinitionJson));
        params.add(new BasicNameValuePair("taskRelationJson", "[{\"name\":\"\",\"preTaskCode\":0,\"preTaskVersion\":0,\"postTaskCode\":4143298469059,\"conditionType\":0,\"conditionParams\":{}}]"));
        params.add(new BasicNameValuePair("tenantCode", "root"));
        params.add(new BasicNameValuePair("description", ""));
        params.add(new BasicNameValuePair("globalParams", "[]"));
        params.add(new BasicNameValuePair("timeout", "0"));
        sendPost(uri, params);
    }
复制代码

(2) 调用工作流 createEmptyProcessDefinition、任务 save、工作流任务关系 save

ProcessDefinition createEmptyProcessDefinition api

参数	参数说明	示例值
name	工作流名称	lee-test-01
projectCode	项目code，必须填写	4362891840832
scheduleJson	创建定时，可为空	{"warningType":"NONE","warningGroupId":1,"failureStrategy":"CONTINUE","workerGroup":"prod","environmentCode":-1,"processInstancePriority":"MEDIUM","startTime":"2022-02-07 00:00:00","endTime":"2027-02-07 00:00:00","crontab":"0 11 11 * * ? *","timezoneId":"Asia/Shanghai"}
tenantCode	租户，对应于租户管理的操作系统租户	root
description	工作流描述信息
globalParams	全局参数	[]
timeout	工作流超时时长	0

TaskDefinition save api

参数	参数说明	示例值
projectCode	项目 code，必须填写	4362891840832
taskDefinitionJson	task 所有信息组成json Array，在这个接口中无需必须含有task code 和 task version	[{"name":"lee-test","description":"","delayTime":0,"taskType":"SHELL","taskParams":{"resourceList":[],"localParams":[],"rawScript":"echo 11333","dependence":{},"conditionResult":{"successNode":[],"failedNode":[]},"waitStartTimeout":{},"switchResult":{}},"flag":"YES","taskPriority":"MEDIUM","workerGroup":"default","failRetryTimes":0,"failRetryInterval":1,"timeoutFlag":"CLOSE","timeoutNotifyStrategy":"WARN","timeout":0,"environmentCode":-1}]

ProcessTaskRelation save api

参数	参数说明	示例值
projectCode	项目code，必须填写	4362891840832
postTaskCode	创建定时，可为空	{"warningType":"NONE","warningGroupId":1,"failureStrategy":"CONTINUE","workerGroup":"prod","environmentCode":-1,"processInstancePriority":"MEDIUM","startTime":"2022-02-07 00:00:00","endTime":"2027-02-07 00:00:00","crontab":"0 11 11 * * ? *","timezoneId":"Asia/Shanghai"}
preTaskCode	租户，对应于租户管理的操作系统租户	root
processDefinitionCode	工作流描述信息

推荐阅读

线程池使用及解析

Java基础-锁核心

一次搜索性能的排查过程和优化效果

kubernetes scheduler 源码解析及自定义资源调度算法实践

招贤纳士

政采云技术团队（Zero），一个富有激情、创造力和执行力的团队，Base 在风景如画的杭州。团队现有300多名研发小伙伴，既有来自阿里、华为、网易的“老”兵，也有来自浙大、中科大、杭电等校的新人。团队在日常业务开发之外，还分别在云原生、区块链、人工智能、低代码平台、中间件、大数据、物料体系、工程平台、性能体验、可视化等领域进行技术探索和实践，推动并落地了一系列的内部技术产品，持续探索技术的新边界。此外，团队还纷纷投身社区建设，目前已经是 google flutter、scikit-learn、Apache Dubbo、Apache Rocketmq、Apache Pulsar、CNCF Dapr、Apache DolphinScheduler、alibaba Seata 等众多优秀开源社区的贡献者。如果你想改变一直被事折腾，希望开始折腾事；如果你想改变一直被告诫需要多些想法，却无从破局；如果你想改变你有能力去做成那个结果，却不需要你；如果你想改变你想做成的事需要一个团队去支撑，但没你带人的位置；如果你想改变本来悟性不错，但总是有那一层窗户纸的模糊……如果你相信相信的力量，相信平凡人能成就非凡事，相信能遇到更好的自己。如果你希望参与到随着业务腾飞的过程，亲手推动一个有着深入的业务理解、完善的技术体系、技术创造价值、影响力外溢的技术团队的成长过程，我觉得我们该聊聊。任何时间，等着你写点什么，发给 [email protected]

微信公众号

文章同步发布，政采云技术团队公众号，欢迎关注