341 lines
7.4 KiB
Markdown
341 lines
7.4 KiB
Markdown
# 定时任务 API 接口文档
|
||
|
||
## 基础信息
|
||
|
||
- **基础路径**: `/scheduled_task`
|
||
- **认证方式**: 所有接口都需要在请求头中携带 `token`（通过 `mw.CheckToken` 中间件验证）
|
||
- **请求方法**: 所有接口均为 `POST`
|
||
|
||
## 公共数据结构
|
||
|
||
### ScheduledTaskMessage（消息内容）
|
||
|
||
```json
|
||
{
|
||
"type": 1, // 消息类型：1-文本，2-图片，3-视频
|
||
"content": "string", // 消息内容（文本内容、图片URL、视频URL等）
|
||
"thumbnail": "string", // 缩略图URL（用于图片和视频，可选）
|
||
"duration": 0, // 时长（秒，用于视频，可选）
|
||
"fileSize": 0 // 文件大小（字节，用于图片和视频，可选）
|
||
}
|
||
```
|
||
|
||
### ScheduledTaskInfo（定时任务信息）
|
||
|
||
```json
|
||
{
|
||
"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（分页信息）
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"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` 至少需要提供一个，不能同时为空。
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"taskID": "string" // 创建的任务ID
|
||
}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"taskID": "string" // 必填：任务ID
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"pagination": { // 必填：分页信息
|
||
"pageNumber": 1, // 页码（从1开始）
|
||
"showNumber": 10 // 每页显示数量
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"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`，确保至少有一个不为空
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"taskID": "task123",
|
||
"name": "更新后的任务名称",
|
||
"status": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 删除定时任务
|
||
|
||
**接口地址**: `POST /scheduled_task/delete`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"taskIDs": ["string"] // 必填：任务ID列表（支持批量删除）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"taskIDs": ["task1", "task2", "task3"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
- `0`: 成功
|
||
- 其他错误码请参考系统错误码定义
|
||
|
||
## 注意事项
|
||
|
||
1. 所有接口都需要在请求头中携带有效的 `token`
|
||
2. 用户只能操作自己创建的定时任务
|
||
3. `recvIDs` 和 `groupIDs` 可以同时提供，表示同时发送到多个单聊和群聊
|
||
4. `messages` 数组支持多条消息，会按顺序发送
|
||
5. Crontab 表达式需要符合标准格式，客户端负责解析和执行
|
||
6. 服务端只负责存储配置，不执行定时任务
|
||
|