7.4 KiB
7.4 KiB
定时任务 API 接口文档
基础信息
- 基础路径:
/scheduled_task - 认证方式: 所有接口都需要在请求头中携带
token（通过mw.CheckToken中间件验证） - 请求方法: 所有接口均为
POST
公共数据结构
ScheduledTaskMessage（消息内容）
{
"type": 1, // 消息类型：1-文本，2-图片，3-视频
"content": "string", // 消息内容（文本内容、图片URL、视频URL等）
"thumbnail": "string", // 缩略图URL（用于图片和视频，可选）
"duration": 0, // 时长（秒，用于视频，可选）
"fileSize": 0 // 文件大小（字节，用于图片和视频，可选）
}
ScheduledTaskInfo（定时任务信息）
{
"id": "string", // 任务ID
"userID": "string", // 用户ID
"name": "string", // 任务名称
"cronExpression": "string", // Crontab表达式：分 时 日 月 周（例如："0 9 * * *"）
"messages": [ // 消息列表（支持多条消息一起发送）
{
"type": 1,
"content": "string",
"thumbnail": "string",
"duration": 0,
"fileSize": 0
}
],
"recvIDs": ["string"], // 接收者ID列表（单聊，可以多个）
"groupIDs": ["string"], // 群组ID列表（群聊，可以多个）
"status": 1, // 状态：0-已禁用，1-已启用
"createTime": 1234567890123, // 创建时间（毫秒时间戳）
"updateTime": 1234567890123 // 更新时间（毫秒时间戳）
}
RequestPagination（分页信息）
{
"pageNumber": 1, // 页码（从1开始）
"showNumber": 10 // 每页显示数量
}
Crontab 表达式说明
格式：分 时 日 月 周
- 分: 0-59
- 时: 0-23
- 日: 1-31
- 月: 1-12
- 周: 0-7（0和7都表示周日）
示例
"0 9 * * *"- 每天9点执行"*/5 * * * *"- 每5分钟执行"0 0 * * 1"- 每周一0点执行"0 12 * * 1-5"- 周一到周五每天12点执行"0 0 1 * *"- 每月1号0点执行
1. 创建定时任务
接口地址: POST /scheduled_task/create
请求参数:
{
"name": "string", // 必填：任务名称
"cronExpression": "string", // 必填：Crontab表达式
"messages": [ // 必填：消息列表（至少一条）
{
"type": 1, // 必填：消息类型：1-文本，2-图片，3-视频
"content": "string", // 必填：消息内容
"thumbnail": "string", // 可选：缩略图URL
"duration": 0, // 可选：时长（秒）
"fileSize": 0 // 可选：文件大小（字节）
}
],
"recvIDs": ["string"], // 可选：接收者ID列表（单聊，可以多个）
"groupIDs": ["string"], // 可选：群组ID列表（群聊，可以多个）
"status": 1 // 可选：状态：0-已禁用，1-已启用（默认为1）
}
注意: recvIDs 和 groupIDs 至少需要提供一个，不能同时为空。
响应参数:
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"taskID": "string" // 创建的任务ID
}
}
请求示例:
{
"name": "每日问候",
"cronExpression": "0 9 * * *",
"messages": [
{
"type": 1,
"content": "早上好！"
},
{
"type": 2,
"content": "https://example.com/image.jpg",
"thumbnail": "https://example.com/thumb.jpg",
"fileSize": 102400
}
],
"recvIDs": ["user1", "user2"],
"groupIDs": ["group1"],
"status": 1
}
2. 获取定时任务详情
接口地址: POST /scheduled_task/get
请求参数:
{
"taskID": "string" // 必填：任务ID
}
响应参数:
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"task": { // 定时任务信息
"id": "string",
"userID": "string",
"name": "string",
"cronExpression": "string",
"messages": [
{
"type": 1,
"content": "string",
"thumbnail": "string",
"duration": 0,
"fileSize": 0
}
],
"recvIDs": ["string"],
"groupIDs": ["string"],
"status": 1,
"createTime": 1234567890123,
"updateTime": 1234567890123
}
}
}
3. 获取定时任务列表
接口地址: POST /scheduled_task/list
请求参数:
{
"pagination": { // 必填：分页信息
"pageNumber": 1, // 页码（从1开始）
"showNumber": 10 // 每页显示数量
}
}
响应参数:
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"total": 100, // 总数
"tasks": [ // 任务列表
{
"id": "string",
"userID": "string",
"name": "string",
"cronExpression": "string",
"messages": [
{
"type": 1,
"content": "string",
"thumbnail": "string",
"duration": 0,
"fileSize": 0
}
],
"recvIDs": ["string"],
"groupIDs": ["string"],
"status": 1,
"createTime": 1234567890123,
"updateTime": 1234567890123
}
]
}
}
4. 更新定时任务
接口地址: POST /scheduled_task/update
请求参数:
{
"taskID": "string", // 必填：任务ID
"name": "string", // 可选：任务名称
"cronExpression": "string", // 可选：Crontab表达式
"messages": [ // 可选：消息列表
{
"type": 1,
"content": "string",
"thumbnail": "string",
"duration": 0,
"fileSize": 0
}
],
"recvIDs": ["string"], // 可选：接收者ID列表
"groupIDs": ["string"], // 可选：群组ID列表
"status": 1 // 可选：状态：0-已禁用，1-已启用
}
注意:
- 所有字段都是可选的，只更新提供的字段
- 如果更新
recvIDs和groupIDs，确保至少有一个不为空
响应参数:
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {}
}
请求示例:
{
"taskID": "task123",
"name": "更新后的任务名称",
"status": 0
}
5. 删除定时任务
接口地址: POST /scheduled_task/delete
请求参数:
{
"taskIDs": ["string"] // 必填：任务ID列表（支持批量删除）
}
响应参数:
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {}
}
请求示例:
{
"taskIDs": ["task1", "task2", "task3"]
}
错误码说明
0: 成功- 其他错误码请参考系统错误码定义
注意事项
- 所有接口都需要在请求头中携带有效的
token - 用户只能操作自己创建的定时任务
recvIDs和groupIDs可以同时提供，表示同时发送到多个单聊和群聊messages数组支持多条消息，会按顺序发送- Crontab 表达式需要符合标准格式，客户端负责解析和执行
- 服务端只负责存储配置，不执行定时任务