ratch-job docs

Appearance

Ratch Job Open API 文档 ​

概述 ​

本文档描述了 Ratch Job 系统的 HTTP Open API 接口，所有接口都以 /ratch/v1/job/ 开头。

基础地址：http://127.0.0.1:8725

1. 创建任务 ​

接口地址： POST /ratch/v1/job/create

接口描述： 创建一个新的定时任务

请求参数 ​

参数名类型必填说明
appNamestring是应用名称
namespacestring是命名空间
keystring否任务唯一标识键（不填时自动生成UUID）
handleNamestring是任务处理器名称（当runMode为BEAN时必填）
scheduleTypestring否调度类型：CRON、INTERVAL、DELAY、NONE
cronValuestring否CRON表达式（当scheduleType为CRON时必填）
delaySecondnumber否延迟秒数（当scheduleType为DELAY时必填）
intervalSecondnumber否间隔秒数（当scheduleType为INTERVAL时必填）
runModestring否运行模式：BEAN、GLUE_GROOVY、GLUE_SHELL、GLUE_PYTHON、GLUE_PHP、GLUE_NODEJS、GLUE_POWERSHELL
descriptionstring否任务描述
triggerParamstring否触发参数
routerStrategystring否路由策略：FIRST、LAST、ROUND_ROBIN、RANDOM、CONSISTENT_HASH、SHARDING_BROADCAST
pastDueStrategystring否过期策略：DEFAULT、IGNORE、EXECUTE
blockingStrategystring否阻塞策略：SERIAL_EXECUTION、DISCARD_LATER、COVER_EARLY、OTHER
timeoutSecondnumber否超时秒数
tryTimesnumber否重试次数
retryIntervalnumber否重试间隔
enableboolean否是否启用，默认true

响应参数 ​

参数名类型说明
contentobject任务信息对象
content.idnumber任务ID
content.enableboolean是否启用
content.appNamestring应用名称
content.namespacestring命名空间
content.keystring任务唯一标识键
content.descriptionstring任务描述
content.scheduleTypestring调度类型
content.cronValuestringCRON表达式
content.delaySecondnumber延迟秒数
content.intervalSecondnumber间隔秒数
content.runModestring运行模式
content.handleNamestring任务处理器名称
content.triggerParamstring触发参数
content.routerStrategystring路由策略
content.pastDueStrategystring过期策略
content.blockingStrategystring阻塞策略
content.timeoutSecondnumber超时秒数
content.tryTimesnumber重试次数
content.versionIdnumber版本ID
content.lastModifiedMillisnumber最后修改时间戳
content.createTimenumber创建时间戳
content.retryIntervalnumber重试间隔
codenumber响应码，200表示成功
msgstring错误信息

示例 ​

通过open-api创建任务

sh
curl -X POST "http://127.0.0.1:8725/ratch/v1/job/create" -H 'Content-Type: application/json' -d '{"appName":"xxl-job-executor-sample","namespace":"xxl","handleName":"demoJobHandler","scheduleType":"CRON","cronValue":"0/15 * * * * *","blockingStrategy":"SERIAL_EXECUTION"}'

响应信息为:

json
{"content":{},"code":200,"msg":null}

注意事项 ​

  • 通过 enable 参数可以设置任务是否启用：
    • enable: true - 启用任务，任务会按照调度配置正常执行
    • enable: false - 禁用任务，任务不会执行但配置会保留
  • 更新任务时，只需要传入需要修改的字段，其他字段会保持原值不变
  • 任务ID (id) 是必填参数，用于指定要更新的任务

2. 更新任务 ​

接口地址： POST /ratch/v1/job/update

接口描述： 更新已存在的任务信息

请求参数 ​

参数名类型必填说明
idnumber是任务ID
appNamestring否应用名称
namespacestring否命名空间
keystring否任务唯一标识键
handleNamestring否任务处理器名称
scheduleTypestring否调度类型
cronValuestring否CRON表达式
delaySecondnumber否延迟秒数
intervalSecondnumber否间隔秒数
runModestring否运行模式
descriptionstring否任务描述
triggerParamstring否触发参数
routerStrategystring否路由策略
pastDueStrategystring否过期策略
blockingStrategystring否阻塞策略
timeoutSecondnumber否超时秒数
tryTimesnumber否重试次数
retryIntervalnumber否重试间隔
enableboolean否是否启用

响应参数 ​

参数名类型说明
contentobject响应内容，更新成功时为空对象
codenumber响应码，200表示成功
msgstring错误信息

示例 ​

sh
curl -X POST "http://127.0.0.1:8725/ratch/v1/job/update" -H 'Content-Type: application/json' -d '{"id":2,"appName":"xxl-job-executor-sample","namespace":"xxl","handleName":"demoJobHandler","scheduleType":"CRON","cronValue":"0/30 * * * * *","blockingStrategy":"SERIAL_EXECUTION","enable":true}'

响应信息为:

json
{"content":{},"code":200,"msg":null}

3. 删除任务 ​

接口地址： POST /ratch/v1/job/remove

接口描述： 删除指定的任务

请求参数 ​

参数名类型必填说明
idnumber是任务ID

响应参数 ​

参数名类型说明
contentobject响应内容，删除成功时为空对象
codenumber响应码，200表示成功
msgstring错误信息

示例 ​

sh
curl -X POST "http://127.0.0.1:8725/ratch/v1/job/remove" -H 'Content-Type: application/json' -d '{"id":2}'

响应信息为:

json
{"content":{},"code":200,"msg":null}

4. 获取任务详情 ​

接口地址： GET /ratch/v1/job/info

接口描述： 获取指定任务的详细信息

请求参数 ​

参数名类型必填说明
idnumber是任务ID

响应参数 ​

参数名类型说明
dataobject任务信息对象
data.idnumber任务ID
data.enableboolean是否启用
data.appNamestring应用名称
data.namespacestring命名空间
data.keystring任务唯一标识键
data.descriptionstring任务描述
data.scheduleTypestring调度类型
data.cronValuestringCRON表达式
data.delaySecondnumber延迟秒数
data.intervalSecondnumber间隔秒数
data.runModestring运行模式
data.handleNamestring任务处理器名称
data.triggerParamstring触发参数
data.routerStrategystring路由策略
data.pastDueStrategystring过期策略
data.blockingStrategystring阻塞策略
data.timeoutSecondnumber超时秒数
data.tryTimesnumber重试次数
data.versionIdnumber版本ID
data.lastModifiedMillisnumber最后修改时间戳
data.createTimenumber创建时间戳
data.retryIntervalnumber重试间隔
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/job/info?id=2"

响应信息为:

json
{"data":{"id":2,"enable":true,"appName":"xxl-job-executor-sample","namespace":"xxl","description":"","scheduleType":"CRON","cronValue":"0/15 * * * * *","delaySecond":0,"intervalSecond":0,"runMode":"BEAN","handleName":"demoJobHandler","triggerParam":"","routerStrategy":"ROUND_ROBIN","pastDueStrategy":"DEFAULT","blockingStrategy":"SERIAL_EXECUTION","timeoutSecond":0,"tryTimes":0,"versionId":0,"lastModifiedMillis":1743353817624,"createTime":1743353817624,"retryInterval":0},"success":true,"code":null,"message":null}

5. 查询任务列表 ​

接口地址： GET /ratch/v1/job/list

接口描述： 分页查询任务列表

请求参数 ​

参数名类型必填说明
namespacestring否命名空间
appNamestring否应用名称
likeDescriptionstring否任务描述模糊查询
likeHandleNamestring否处理器名称模糊查询
pageNonumber否页码，默认1
pageSizenumber否每页大小，默认所有

响应参数 ​

参数名类型说明
dataobject分页结果对象
data.totalCountnumber总记录数
data.listarray任务列表
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/job/list?namespace=xxl&pageNo=1&pageSize=10"

响应信息为:

json
{"data":{"totalCount":1,"list":[{"id":2,"enable":true,"appName":"xxl-job-executor-sample","namespace":"xxl","description":"","scheduleType":"CRON","cronValue":"0/15 * * * * *","delaySecond":0,"intervalSecond":0,"runMode":"BEAN","handleName":"demoJobHandler","triggerParam":"","routerStrategy":"ROUND_ROBIN","pastDueStrategy":"DEFAULT","blockingStrategy":"SERIAL_EXECUTION","timeoutSecond":0,"tryTimes":0,"versionId":0,"lastModifiedMillis":1743353817624,"createTime":1743353817624,"retryInterval":0}]},"success":true,"code":null,"message":null}

枚举值说明 ​

调度类型 (scheduleType) ​

  • CRON: CRON表达式调度
  • INTERVAL: 固定间隔调度
  • DELAY: 延迟调度
  • NONE: 无调度

运行模式 (runMode) ​

  • BEAN: Spring Bean模式
  • GLUE_GROOVY: Groovy脚本模式
  • GLUE_SHELL: Shell脚本模式
  • GLUE_PYTHON: Python脚本模式
  • GLUE_PHP: PHP脚本模式
  • GLUE_NODEJS: Node.js脚本模式
  • GLUE_POWERSHELL: PowerShell脚本模式

路由策略 (routerStrategy) ​

  • FIRST: 第一个
  • LAST: 最后一个
  • ROUND_ROBIN: 轮询
  • RANDOM: 随机
  • CONSISTENT_HASH: 一致性哈希
  • SHARDING_BROADCAST: 分片广播

过期策略 (pastDueStrategy) ​

  • DEFAULT: 默认策略
  • IGNORE: 忽略过期任务
  • EXECUTE: 执行过期任务

阻塞策略 (blockingStrategy) ​

  • SERIAL_EXECUTION: 串行执行
  • DISCARD_LATER: 丢弃后续任务
  • COVER_EARLY: 覆盖之前任务
  • OTHER: 其他策略

6. 查询任务执行记录列表 ​

接口地址： GET /ratch/v1/job/task/list

接口描述： 分页查询指定任务的执行记录

请求参数 ​

参数名类型必填说明
jobIdnumber是任务ID
pageNonumber否页码，默认1
pageSizenumber否每页大小，默认10

响应参数 ​

参数名类型说明
dataobject分页结果对象
data.totalCountnumber总记录数
data.listarray任务执行记录列表
data.list[].taskIdnumber任务ID
data.list[].jobIdnumber任务ID
data.list[].triggerTimenumber触发时间（Unix时间戳，秒）
data.list[].instanceAddrstring执行实例地址
data.list[].triggerMessagestring触发消息
data.list[].statusstring任务状态：Init、Running、Success、Fail
data.list[].finishTimenumber完成时间（Unix时间戳，秒）
data.list[].callbackMessagestring回调消息
data.list[].executionTimenumber执行耗时（秒）
data.list[].triggerFromstring触发来源
data.list[].tryTimesnumber重试次数
data.list[].tryLogsarray重试记录列表
data.list[].tryLogs[].executionTimenumber执行时间（秒）
data.list[].tryLogs[].addrstring执行地址
data.list[].retryIntervalnumber重试间隔（秒）
data.list[].retryCountnumber已重试次数
data.list[].timeoutSecondnumber超时时间（秒）
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/job/task/list?jobId=2&pageNo=1&pageSize=10"

响应信息为:

json
{"data":{"totalCount":1,"list":[{"taskId":1001,"jobId":2,"triggerTime":1743353820,"instanceAddr":"192.168.1.100:9999","triggerMessage":"","status":"Success","finishTime":1743353825,"callbackMessage":"","executionTime":5,"triggerFrom":"SYSTEM","tryTimes":3,"tryLogs":[],"retryInterval":10,"retryCount":0,"timeoutSecond":60}]},"success":true,"code":null,"message":null}

7. 查询最新任务历史记录 ​

接口地址： GET /ratch/v1/job/task/latest-history

接口描述： 分页查询指定任务的最新历史执行记录

请求参数 ​

参数名类型必填说明
jobIdnumber是任务ID
pageNonumber否页码，默认1
pageSizenumber否每页大小，默认10

响应参数 ​

参数名类型说明
dataobject分页结果对象
data.totalCountnumber总记录数
data.listarray任务执行记录列表
data.list[].taskIdnumber任务ID
data.list[].jobIdnumber任务ID
data.list[].triggerTimenumber触发时间（Unix时间戳，秒）
data.list[].instanceAddrstring执行实例地址
data.list[].triggerMessagestring触发消息
data.list[].statusstring任务状态：Init、Running、Success、Fail
data.list[].finishTimenumber完成时间（Unix时间戳，秒）
data.list[].callbackMessagestring回调消息
data.list[].executionTimenumber执行耗时（秒）
data.list[].triggerFromstring触发来源
data.list[].tryTimesnumber重试次数
data.list[].tryLogsarray重试记录列表
data.list[].tryLogs[].executionTimenumber执行时间（秒）
data.list[].tryLogs[].addrstring执行地址
data.list[].retryIntervalnumber重试间隔（秒）
data.list[].retryCountnumber已重试次数
data.list[].timeoutSecondnumber超时时间（秒）
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/job/task/latest-history?jobId=2&pageNo=1&pageSize=10"

响应信息为:

json
{"data":{"totalCount":1,"list":[{"taskId":1001,"jobId":2,"triggerTime":1743353820,"instanceAddr":"192.168.1.100:9999","triggerMessage":"","status":"Success","finishTime":1743353825,"callbackMessage":"","executionTime":5,"triggerFrom":"SYSTEM","tryTimes":3,"tryLogs":[],"retryInterval":10,"retryCount":0,"timeoutSecond":60}]},"success":true,"code":null,"message":null}

任务状态说明 (status) ​

  • Init: 初始化状态
  • Running: 运行中
  • Success: 执行成功
  • Fail: 执行失败

8. 根据Key查询任务ID ​

接口地址： GET /ratch/v1/job/queryIdByKey

接口描述： 根据namespace、app_name和key查询任务ID

请求参数 ​

参数名类型必填说明
namespacestring是命名空间
appNamestring是应用名称
keystring是任务唯一标识键

响应参数 ​

参数名类型说明
datanumber任务ID
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/job/queryIdByKey?namespace=xxl&appName=xxl-job-executor-sample&key=your-job-key"

响应信息为:

json
{"data":2,"success":true,"code":null,"message":null}

9. 根据Key查询任务详情 ​

接口地址： GET /ratch/v1/job/queryJobByKey

接口描述： 根据namespace、app_name和key查询任务详细信息

请求参数 ​

参数名类型必填说明
namespacestring是命名空间
appNamestring是应用名称
keystring是任务唯一标识键

响应参数 ​

参数名类型说明
dataobject任务信息对象
data.idnumber任务ID
data.enableboolean是否启用
data.appNamestring应用名称
data.namespacestring命名空间
data.keystring任务唯一标识键
data.descriptionstring任务描述
data.scheduleTypestring调度类型
data.cronValuestringCRON表达式
data.delaySecondnumber延迟秒数
data.intervalSecondnumber间隔秒数
data.runModestring运行模式
data.handleNamestring任务处理器名称
data.triggerParamstring触发参数
data.routerStrategystring路由策略
data.pastDueStrategystring过期策略
data.blockingStrategystring阻塞策略
data.timeoutSecondnumber超时秒数
data.tryTimesnumber重试次数
data.versionIdnumber版本ID
data.lastModifiedMillisnumber最后修改时间戳
data.createTimenumber创建时间戳
data.retryIntervalnumber重试间隔
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/job/queryJobByKey?namespace=xxl&appName=xxl-job-executor-sample&key=your-job-key"

响应信息为:

json
{"data":{"id":2,"enable":true,"appName":"xxl-job-executor-sample","namespace":"xxl","key":"your-job-key","description":"","scheduleType":"CRON","cronValue":"0/15 * * * * *","delaySecond":0,"intervalSecond":0,"runMode":"BEAN","handleName":"demoJobHandler","triggerParam":"","routerStrategy":"ROUND_ROBIN","pastDueStrategy":"DEFAULT","blockingStrategy":"SERIAL_EXECUTION","timeoutSecond":0,"tryTimes":0,"versionId":0,"lastModifiedMillis":1743353817624,"createTime":1743353817624,"retryInterval":0},"success":true,"code":null,"message":null}

10. 查询命名空间列表 ​

接口地址： GET /ratch/v1/namespace/list

接口描述： 查询所有可用的命名空间列表

请求参数 ​

无

响应参数 ​

参数名类型说明
dataarray命名空间列表
data[].namespacestring命名空间名称
data[].namespaceDescstring命名空间描述
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/namespace/list"

响应信息为:

json
{"data":[{"namespace":"xxl","namespaceDesc":"xxl"},{"namespace":"default","namespaceDesc":"default"}],"success":true,"code":null,"message":null}

11. 查询应用列表 ​

接口地址： GET /ratch/v1/app/list

接口描述： 查询所有可用的应用名称列表

请求参数 ​

无

响应参数 ​

参数名类型说明
dataarray应用名称列表
successboolean是否成功
codestring错误码
messagestring错误信息

示例 ​

sh
curl -X GET "http://127.0.0.1:8725/ratch/v1/app/list"

响应信息为:

json
{"data":["xxl-job-executor-sample","demo-app"],"success":true,"code":null,"message":null}

错误码说明 ​

  • 200: 成功
  • 500: 系统内部错误

当接口调用失败时，会返回相应的错误信息和错误码。