六、调度中心 / 执行器 RESTful API
XXL-JOB 目标是一种跨平台、跨语言的任务调度规范和协议。
针对 Java 应用,可以直接通过官方提供的调度中心与执行器,方便快速的接入和使用调度中心,可以参考上文 “快速入门” 章节。
针对非 Java 应用,可借助 XXL-JOB 的标准 RESTful API 方便的实现多语言支持。
- 调度中心 RESTful API:
- 说明:调度中心提供给执行器使用的 API;不局限于官方执行器使用,第三方可使用该 API 来实现执行器;
- API 列表:执行器注册、任务结果回调等;
- 执行器 RESTful API :
- 说明:执行器提供给调度中心使用的 API;官方执行器默认已实现,第三方执行器需要实现并对接提供给调度中心;
- API 列表:任务触发、任务终止、任务日志查询……等;
此处 RESTful API 主要用于非 Java 语言定制个性化执行器使用,实现跨语言。除此之外,如果有需要通过 API 操作调度中心,可以个性化扩展 “调度中心 RESTful API” 并使用。
6.1 调度中心 RESTful API
API 服务位置:com.xxl.job.core.biz.AdminBiz ( com.xxl.job.admin.controller.JobApiController )
API 服务请求参考代码:com.xxl.job.adminbiz.AdminBizTest
a、任务回调
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
|
1. ` 说明:执行器执行完任务后,回调任务结果时使用 `
3. `------`
5. ` 地址格式:{ 调度中心根地址 }/api/callback`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `[{` 12. `"logId":1, // 本次调度日志 ID` 13. `"logDateTim":0, // 本次调度日志时间 ` 14. `"handleCode":200, // 200 表示任务执行正常,500 表示失败 ` 15. `"handleMsg": null` 16. `}` 17. `}]`
19. ` 响应数据格式:` 20. `{` 21. `"code": 200, // 200 表示正常、其他失败 ` 22. `"msg": null // 错误提示消息 ` 23. `}`
|
b、执行器注册
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
|
1. ` 说明:执行器注册时使用,调度中心会实时感知注册成功的执行器并发起任务调度 `
3. `------`
5. ` 地址格式:{ 调度中心根地址 }/api/registry`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `{` 12. `"registryGroup":"EXECUTOR", // 固定值 ` 13. `"registryKey":"xxl-job-executor-example", // 执行器 AppName` 14. `"registryValue":"http://127.0.0.1:9999/" // 执行器地址,内置服务跟地址 ` 15. `}`
17. ` 响应数据格式:` 18. `{` 19. `"code": 200, // 200 表示正常、其他失败 ` 20. `"msg": null // 错误提示消息 ` 21. `}`
|
c、执行器注册摘除
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
|
1. ` 说明:执行器注册摘除时使用,注册摘除后的执行器不参与任务调度与执行 `
3. `------`
5. ` 地址格式:{ 调度中心根地址 }/api/registryRemove`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `{` 12. `"registryGroup":"EXECUTOR", // 固定值 ` 13. `"registryKey":"xxl-job-executor-example", // 执行器 AppName` 14. `"registryValue":"http://127.0.0.1:9999/" // 执行器地址,内置服务跟地址 ` 15. `}`
17. ` 响应数据格式:` 18. `{` 19. `"code": 200, // 200 表示正常、其他失败 ` 20. `"msg": null // 错误提示消息 ` 21. `}`
|
6.2 执行器 RESTful API
API 服务位置:com.xxl.job.core.biz.ExecutorBiz
API 服务请求参考代码:com.xxl.job.executorbiz.ExecutorBizTest
a、心跳检测
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
|
1. ` 说明:调度中心检测执行器是否在线时使用 `
3. `------`
5. ` 地址格式:{ 执行器内嵌服务根地址 }/beat`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:`
12. ` 响应数据格式:` 13. `{` 14. `"code": 200, // 200 表示正常、其他失败 ` 15. `"msg": null // 错误提示消息 ` 16. `}`
|
b、忙碌检测
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
|
1. ` 说明:调度中心检测指定执行器上指定任务是否忙碌(运行中)时使用 `
3. `------`
5. ` 地址格式:{ 执行器内嵌服务根地址 }/idleBeat`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `{` 12. `"jobId":1 // 任务 ID` 13. `}`
15. ` 响应数据格式:` 16. `{` 17. `"code": 200, // 200 表示正常、其他失败 ` 18. `"msg": null // 错误提示消息 ` 19. `}`
|
c、触发任务
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
|
1. ` 说明:触发任务执行 `
3. `------`
5. ` 地址格式:{ 执行器内嵌服务根地址 }/run`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `{` 12. `"jobId":1, // 任务 ID` 13. `"executorHandler":"demoJobHandler", // 任务标识 ` 14. `"executorParams":"demoJobHandler", // 任务参数 ` 15. `"executorBlockStrategy":"COVER_EARLY", // 任务阻塞策略,可选值参考 com.xxl.job.core.enums.ExecutorBlockStrategyEnum` 16. `"executorTimeout":0, // 任务超时时间,单位秒,大于零时生效 ` 17. `"logId":1, // 本次调度日志 ID` 18. `"logDateTime":1586629003729, // 本次调度日志时间 ` 19. `"glueType":"BEAN", // 任务模式,可选值参考 com.xxl.job.core.glue.GlueTypeEnum` 20. `"glueSource":"xxx", // GLUE 脚本代码 ` 21. `"glueUpdatetime":1586629003727, // GLUE 脚本更新时间,用于判定脚本是否变更以及是否需要刷新 ` 22. `"broadcastIndex":0, // 分片参数:当前分片 ` 23. `"broadcastTotal":0 // 分片参数:总分片 ` 24. `}`
26. ` 响应数据格式:` 27. `{` 28. `"code": 200, // 200 表示正常、其他失败 ` 29. `"msg": null // 错误提示消息 ` 30. `}`
|
f、终止任务
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
|
1. ` 说明:终止任务 `
3. `------`
5. ` 地址格式:{ 执行器内嵌服务根地址 }/kill`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `{` 12. `"jobId":1 // 任务 ID` 13. `}`
16. ` 响应数据格式:` 17. `{` 18. `"code": 200, // 200 表示正常、其他失败 ` 19. `"msg": null // 错误提示消息 ` 20. `}`
|
d、查看执行日志
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
|
1. ` 说明:终止任务,滚动方式加载 `
3. `------`
5. ` 地址格式:{ 执行器内嵌服务根地址 }/log`
7. `Header:` 8. `XXL-JOB-ACCESS-TOKEN : { 请求令牌 }`
10. ` 请求数据格式如下,放置在 RequestBody 中,JSON 格式:` 11. `{` 12. `"logDateTim":0, // 本次调度日志时间 ` 13. `"logId":0, // 本次调度日志 ID` 14. `"fromLineNum":0 // 日志开始行号,滚动加载日志 ` 15. `}`
17. ` 响应数据格式:` 18. `{` 19. `"code":200, // 200 表示正常、其他失败 ` 20. `"msg": null // 错误提示消息 ` 21. `"content":{` 22. `"fromLineNum":0, // 本次请求,日志开始行数 ` 23. `"toLineNum":100, // 本次请求,日志结束行号 ` 24. `"logContent":"xxx", // 本次请求日志内容 ` 25. `"isEnd":true // 日志是否全部加载完 ` 26. `}` 27. `}`
|