API执行
视频示例
调度提供了外部系统调用API的能力，可通过API实现指定某个机器人、某个应用、所需的参数，在需要的时候触发运行，运行的结果可通过回调接口返回。
通过调度API，实现了外部系统与调度中心的连接互动。
API配置
可新增多个API配置，支持多个系统调用。
重置密钥和删除后，原接口将调用不通。
API执行记录
通过API执行的任务，在「API执行」中可以查看
鉴权接口
获取token
accessKeyId 和 accessKeySecret 需要从 影刀控制台 获取，获取后请妥善保管，管理员可以选择给每个需要对接影刀的系统各自创建一对密钥。
请求方式：GET
请求地址：https://api.winrobot360.com/oapi/token/v2/token/create
Content-Type：application/x-www-form-urlencoded
请求参数:
| 参数名 | 参数类型 | 参数描述 | 示例 |
|---|---|---|---|
| accessKeyId | String | 影刀控制台获取的accessKeyId | MerC5cKPSa7BTG1A@platform |
| accessKeySecret | String | 影刀控制台获取的accessKeySecret | mqTxhk4aK1v7PpDtfQU6dCMgnrR50HFc |
调用示例
请求响应
正常:
{
"data": {
"accessToken": "520da9c9-694d-4b40-9332-0c179243c88e",
"expiresIn": 7199
},
"code": 200,
"success": true,
"requestId": "601cf6274032e2cc335c97d2"
}
accessKeyId不正确时响应:
{
"code": 400,
"success": false,
"requestId": "d63a123c5d79060c2a704da6",
"msg": "accessKeyId错误，请用企业管理员登录后台并进行核对!!!"
}
响应参数说明 accessToken 用作后续的访问，expiresIn 说明token的有效时长(秒)。调用方应该在 accessToken 失效前，再次调用 获取token 接口更新 accessToken，建议调用方根据有效期缓存，避免重复获取token，另外当通过accessToken访问调度API接口时返回401，重新获取token即可!!!
响应参数说明
| 参数 | 类型 | 是否必填 | 最大长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
| code | int | 是 | 3 | 状态码 | 0 |
| msg | String | 是 | - | 响应msg | accessKeyId错误，请用企业管理员登录后台并进行核对!!! |
| success | boolean | 是 | - | true/false,表示是否调用成功 | true |
| requestId | String | 否 | - | 请求id | 调用失败时 |
| accessToken | String | 否 | - | 用作后续的接口访问 | 1d6a43d5-c545-4284-9675-9db53027619e |
| expiresIn | int | 否 | - | 有效期，一般2小时 | 7199 |
状态码说明
| code（返回码） | msg（返回码描述） |
|---|---|
| 0 | 接口调用成功 |
| 400 | 具体描述如下： |
1.未配置accessKeyId, 请用企业管理员登录后台并进行配置!!!
2.未配置accessKeySecret, 请用企业管理员登录后台并进行配置!!!
3.accessKeyId错误，请用企业管理员登录后台并进行核对!!!
4.accessKeySecret错误，请用企业管理员登录后台并进行核对!!!
任务运行状态枚举值说明
| 状态码 | 状态码描述 |
|---|---|
| waiting | 等待调度 |
| running | 任务运行中 |
| finish | 任务运行结束 |
| stopping | 任务正在停止 |
| stopped | 已结束 |
| error | 异常 |
应用运行状态枚举值说明
| 状态码 | 状态码描述 |
|---|---|
| created | 已创建 |
| waiting | 等待调度 |
| running | 运行中 |
| finish | 完成 |
| stopping | 停止中 |
| stopped | 已停止 |
| error | 异常 |
| skipped | 已跳过 |
| CANCEL | 已取消 |
使用token
accessToken 在每次调用具体的接口的时候，需要作为参数放在 header 中，参数放置如下：
authorization: Bearer ${accessToken}
authorization: Bearer 1d6a43d5-c545-4284-9675-9db53027619e
注意：authorization 为 header 的 key，value 为 "Bearer 1d6a43d5-c545-4284-9675-9db53027619e"，Bearer 和 accessToken 中间有一个空格 注意:当accessToken失效时，code码为401，此时需要重新调用 https://api.winrobot360.com/oapi/token/v2/token/create 刷新接口
应用运行接口
启动Job
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/job/start
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
// 以应用和机器人去执行
{
"accountName": "admin@fckj", //机器人注册时候使用的账号名
"robotUuid": "73d9a119-7ec7-4226-b679-506afefae667", //应用的uuid，可以在客户端的应用详情中获取
"robotClientGroupUuid": "xx", // 机器人分组uuid
"params":[
{
"name":"获取页数", //应用参数名称
"value":"10" // 应用参数值
}
]
}
请求响应：
{
"data": {
"jobUuid": "fc38f4f1-8444-475e-83f8-3292eeb1606b"
},
"code": 200,
"success": true
}
Job结果回调
回调接口需要在 影刀控制台 注册，在Job运行结束后，会主动通过回调接口传递Job运行结果数据。推荐使用回调方式获取数据结果，保证数据及时获取到。
回调接口要求是POST请求方式，回调的请求数据类型为 application/json ，数据内容：
请求响应：
// 运行结束，有返回值
{
"data": {
"jobUuid": "42c2e0ce-499b-47aa-8642-3a1125b4759a",
"status": "waiting",
"statusName": "等待调度",
"robotUuid": "00a7a1de-af0b-47ad-a3a8-a8fc2b009761",
"robotClientUuid":"bfd28e42-e530-41eb-bf46-796a86ff7ec3",
"robotName": "打印日志应用",
"remark": "应用启动",
"robotParams": {
"inputs": [
{
"name": "姓",
"value": "王",
"type": "str"
},
{
"name": "名",
"value": "5",
"type": "str"
},
{
"name": "上传文件",
"value": "https://winrobot-pub-a-dev.oss-cn-hangzhou.aliyuncs.com/document/temp/request.txt",
"type": "file"
}
]
}
},
"code": 200,
"success": true
}
// 运行结束，无返回值
{
"jobUuid":"45c882ed-e44f-4818-afc0-05172e7ffbe0",
"status":"finish" // 运行状态
}
// 运行异常
{
"jobUuid":"45c882ed-e44f-4818-afc0-05172e7ffbe0",
"status":"error", // 运行状态
"msg":"具体的异常信息"
}
//任务运行结束 回调
{
"dataType": "task", //数据类型 job表示应用运行回调(通过api调用应用robotUuid的方式), task表示任务运行回调(通过api调用任务scheduleUuid的方式)
"startTime": 1,//可为空 第一个应用开始运行时间
"endTime": 1642837962000, //最后一个应用结束运行时间
"jobList": [
{
"dataType": "job",
"jobUuid": "6de893bb-8224-4f60-9bff-b8597b8ed8fc",
"msg": "",
"robotClientUuid": "cfcc5904-2e82-4295-911c-0ce65c9099f2",
"status": "finish"
},
{
"dataType": "job",
"jobUuid": "5b798f23-c8a7-4595-b764-cb491555f936",
"msg": "",
"robotClientUuid": "cfcc5904-2e82-4295-911c-0ce65c9099f2",
"status": "finish"
}
],
"msg": "运行结束", //任务运行备注
"status": "finish", // 任务运行状态
"taskUuid": "ea947f83-82fb-4afb-8412-4021255fd7cd"
}
停止Job
停止运行中的Job
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/job/stop
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
{
"jobUuid": "45c882ed-e44f-4818-afc0-05172e7ffbe0", //运行任务的jobUuid
}
请求响应：
{
"code": 200,
"success": true
}
查询Job结果
Job的运行结果保留24小时，超过时间后会自动清理掉。
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/job/query
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
{
"jobUuid": "45c882ed-e44f-4818-afc0-05172e7ffbe0", //运行任务的jobUuid
}
请求响应：
// 运行结束，有返回值
{
"data": {
"jobUuid": "42c2e0ce-499b-47aa-8642-3a1125b4759a",
"status": "waiting",
"statusName": "等待调度",
"robotUuid": "00a7a1de-af0b-47ad-a3a8-a8fc2b009761",
"robotClientUuid":"bfd28e42-e530-41eb-bf46-796a86ff7ec3",
"robotName": "打印日志应用",
"remark": "应用启动",
"robotParams": {
"inputs": [
{
"name": "姓",
"value": "王",
"type": "str"
},
{
"name": "名",
"value": "5",
"type": "str"
},
{
"name": "上传文件",
"value": "https://winrobot-pub-a-dev.oss-cn-hangzhou.aliyuncs.com/document/temp/request.txt",
"type": "file"
}
],
"outputs":[
{
"name": "姓",
"value": "王",
"type": "str"
}
]
}
},
"code": 200,
"success": true
}
// 运行结束，无返回值
{
"data": {
"status":"finish" // 运行状态
},
"code": 200,
"success": true,
"requestId": "4ee3b003-6331-4329-96f3-e513f4671f88"
}
// 运行中
{
"data": {
"status":"running" // 运行状态
},
"code": 200,
"success": true,
"requestId": "4ee3b003-6331-4329-96f3-e513f4671f88"
}
// 运行异常
{
"data": {
"status":"error", // 运行状态
"msg":"具体的异常信息"
},
"code": 200,
"success": true,
"requestId": "4ee3b003-6331-4329-96f3-e513f4671f88"
}
任务运行接口
启动任务
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/task/start
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
// api调用任务
{
"scheduleUuid":"d4a9bda3-78f8-4a63-8f7d-20f4ce637c9b"
}
请求响应：
{
"data": {
"taskUuid": "4d8aae66-cec5-4043-85cc-70f4e0430d4e" // 该taskUuid可进行后续任务运行状态查询和停止任务运行等操作
},
"code": 200,
"success": true
}
查询任务结果
任务的运行结果保留24小时，超过时间后会自动清理掉。
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/task/query
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
{
"taskUuid":"4d8aae66-cec5-4043-85cc-70f4e0430d4e" //任务运行的uuid
}
请求响应：
{
"data": {
"taskUuid": "4d8aae66-cec5-4043-85cc-70f4e0430d4e", //任务
"taskName": "测试-api任务", //任务名称
"status": "running", //任务运行状态
"statusName": "运行中", //任务状态描述
"jobDataList": [ //任务所关联的应用运行信息，多个应用有多条
{
"jobUuid": "b934597c-f06d-4c52-9624-e62e7f7b9489", //jobUuid 可以通过job查询结构查询任务状态
"status": "finish", //应用运行状态
"statusName": "完成", //应用运行状态描述
"robotUuid": "3f3c9861-9300-4400-9c1f-f4e7f8bb4d08", // 应用uuid
"robotName": "wait-10", //应用名称
"startTime": "2022-01-22 15:10:28", //应用开始时间 可为空
"endTime": "2022-01-22 15:10:46", // 应用结束时间 可为空
"remark": "", //应用运行异常描述
"robotParams": {}, //应用运行输出参数
"robotClientUuid": "cfcc5904-2e82-4295-911c-0ce65c9099f2" //机器人uuid 可通过查询机器人信息接口查询
},
{
"jobUuid": "97421b0b-2f64-4adf-94b9-0bdfc73face6",
"status": "created",
"statusName": "已创建",
"robotUuid": "e8be5a0a-ec3a-4f3a-b4a2-b9319fe6fd0a",
"robotName": "等待-10s",
"robotParams": {},
"robotClientUuid": "cfcc5904-2e82-4295-911c-0ce65c9099f2"
}
]
},
"code": 200,
"success": true
}
停止任务
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/task/stop
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
{
"taskUuid":"4d8aae66-cec5-4043-85cc-70f4e0430d4e" //任务运行的uuid
}
请求响应：
{
"code": 200,
"success": true
}
查询机器人信息
查询机器人信息
请求方式：POST
请求地址：https://api.winrobot360.com/oapi/dispatch/v2/client/query
Content-Type：application/json
请求头：
authorization: Bearer ${access_token}
请求参数：
// robotClientUuid和accountName只需要传一个
{
"robotClientUuid":"0d6a835a-2e08-414a-af73-1e43f9d9c8ff",
"accountName":"ceshi1@csqy1"
}
请求响应：
// 机器人状态
{
"data": {
"robotClientUuid": "0d6a835a-2e08-414a-af73-1e43f9d9c8ff", //机器人uuid
"robotClientName": "ceshi1@csqy1", //机器人名称
"status": "idle", //状态 connected:已连接 idle:空闲 running:运行中 allocated:已分配 abnormal:异常 offline:离线
"description": "ceshi1", //"机器人备注"
"clientIp": "172.16.28.156", //"机器人客户端ip"
"remark": "运行成功" //运行备注
},
"code": 200,
"success": true
}
//错误响应
{
"code": 400,
"success": false,
"serverInstName": "by.dispatch.local",
"msg": "[robotClientUuid不能为空]"
}
回调验签
在Job运行结束后，会主动通过回调接口传递Job运行结果数据，回调接口需要在 影刀控制台 注册
参与签名的bodyMd5和timestamp由回调地址回传
bodyMd5和timestamp加密之后生成的签名与回调接口的sign做比较，一致表明验签通过
签名代码示例
package com.xybot.oapi.service;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.Charset;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.Date;
/**
* 生成签名
*
* @author boyi@fckj
* @since 2021-09-07 11:39
*/
public class SignDemo {
private static final char[] DIGITS_LOWER = new char[]{'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};;
private static final String UTF8_NAME = "UTF-8";
private static final Charset UTF8_CHARSET = Charset.forName(UTF8_NAME);
public static void main(String[] args) {
long timestamp = 1630982412; //由回调接口回传
String accessKeyId = "BTKk8A2nsrjg5xwV@platform"; //影刀控制台配置的accessKeyId
String accessKeySecret = "tXUvxjNreuqJF4bd39pM8hm0621TYCgW"; //影刀控制台配置的accessKeySecret
String bodyMd5 = "6a7c5c8a3572297346481146606eb054"; //由回调接口回传
DateTimeFormatter pattern = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
Date date = new Date(timestamp);
LocalDateTime localDateTime = LocalDateTime.ofInstant(date.toInstant(), ZoneId.systemDefault());
System.out.println(bodyMd5);
StringBuilder sb = new StringBuilder();
sb.append("accessKeyId=");
sb.append(accessKeyId);
sb.append("&bodyMd5=");
sb.append(bodyMd5);
sb.append("×tamp=");
sb.append(pattern.format(localDateTime));
String originalStr = sb.toString();
byte[] keyBytes = accessKeySecret.getBytes();
SecretKeySpec secretKey = new SecretKeySpec(keyBytes, "HmacSHA1");
try {
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(secretKey);
byte[] rawHmac = mac.doFinal(originalStr.getBytes(UTF8_CHARSET));
String sign = encodeHex(rawHmac);
System.out.println("sign: " + sign);
} catch (Exception e) {
e.printStackTrace();
}
}
/**
* 转换16进制
*
* @param data
* @return
*/
private static String encodeHex(byte[] data) {
int l = data.length;
char[] out = new char[l << 1];
int i = 0;
for(int var5 = 0; i < l; ++i) {
out[var5++] = DIGITS_LOWER[(240 & data[i]) >>> 4];
out[var5++] = DIGITS_LOWER[15 & data[i]];
}
return new String(out);
}
}
说明: accessKeyId:影刀控制台生成的accessKeyId，登录后选择API执行->API配置
bodyMd5：请求体加密的字符串，可由回调接口回传回去
timestamp:精确到秒的时间戳即可，由回调接口回传回去
调用平台管理
API机器人的调用，需要先在影刀控制台注册调用平台，每个平台代表一个调用来源。平台注册后，可以获取接口调用的密钥对。