10.task-management.md•9.82 kB
# API文档
以下是对原始API文档的整理和优化，遵循结构清晰、信息准确的原则，并标注发现的问题。
---
## 任务管理
### 1. 查询任务列表
**功能说明**：根据过滤条件查询任务实例列表。
**接口约束**：需具备 `TASK_VIEWER` 权限。
**请求路径**：`GET /api/v2/tasks/instances`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| name | String | 否 | "Prepare host" | 任务名称模糊匹配 |
| status | StringArray | 否 | ["RUNNING", "FAILED"] | 任务状态（可选值：RUNNING/FAILED/SUCCESSFUL） |
| type | String | 否 | "MANUAL" | 任务类型（可选值：MANUAL/SYS_ONECE/SCHEDULED/SYS_SCHEDULED） |
| clusterName | String | 否 | "meta" | 集群名称模糊匹配 |
| clusterId | Long | 否 | 100 | 集群ID |
| tenantName | String | 否 | "SYS" | 租户名称（需配合集群ID） |
| tenantId | Long | 否 | 100 | 租户ID |
| hostId | Long | 否 | 100 | 主机ID |
| page | Integer | 否 | 1 | 分页页码（从1开始） |
| size | Integer | 否 | 10 | 分页大小（默认10，最大2000） |
| sort | String | 否 | "id,asc" | 排序规则 |
**返回结果**：
| 参数 | 类型 | 说明 |
|------|------|------|
| data | Object | 包含任务列表及分页信息 |
| successful | Boolean | 请求是否成功 |
| timestamp | Datetime | 服务端完成时间戳 |
| duration | Integer | 处理时间（毫秒） |
| status | Integer | HTTP状态码 |
| traceId | String | 请求追踪ID |
| server | String | 服务地址 |
**data字段结构**：
```json
{
"contents": [BasicTaskInstance],
"page": {
"totalElements": Integer,
"totalPages": Integer,
"number": Integer,
"size": Integer
}
}
```
**BasicTaskInstance结构**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 任务实例ID |
| name | String | 任务名称 |
| cluster | Object | 集群信息（见下表） |
| tenant | Object | 租户信息（见下表） |
| creator | Object | 创建者信息（见下表） |
| status | String | 状态（RUNNING/FAILED/SUCCESSFUL） |
| startTime | String | 开始时间 |
| finishTime | String | 结束时间 |
| subtasks | Array | 子任务列表（BasicSubtaskInstance对象） |
**cluster参数**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | OCP集群ID |
| name | String | 集群名称 |
| obClusterId | Long | OceanBase集群ID |
| type | String | 类型（PRIMARY/STANDBY） |
**tenant参数**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 租户ID |
| name | String | 租户名称 |
| obClusterId | Long | OceanBase租户ID |
| mode | String | 模式（ORACLE/MYSQL） |
**creator参数**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 用户ID |
| name | String | 用户名 |
**BasicSubtaskInstance结构**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 子任务ID |
| name | String | 子任务名称 |
| description | String | 描述 |
| status | String | 状态（PENDING/READY/RUNNING/CANCELING/FAILED/SUCCESSFUL） |
| operation | String | 操作类型（EXECUTE/RETRY/ROLLBACK/SKIP/CANCEL） |
---
### 2. 查询任务详情
**功能说明**：获取指定任务实例的详细信息。
**接口约束**：需具备 `TASK_VIEWER` 权限。
**请求路径**：`GET /api/v2/tasks/instances/{taskInstanceId}`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
**返回结果**：
| 参数 | 类型 | 说明 |
|------|------|------|
| data | Object | WrappedTaskInstance对象 |
| successful | Boolean | 请求是否成功 |
| timestamp | Datetime | 服务端完成时间戳 |
| duration | Integer | 处理时间（毫秒） |
| status | Integer | HTTP状态码 |
| traceId | String | 请求追踪ID |
| server | String | 服务地址 |
**WrappedTaskInstance结构**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 任务ID |
| name | String | 任务名称 |
| taskDefinitionId | Long | 任务定义ID |
| cluster | Object | 集群信息（见下表） |
| tenant | Object | 租户信息（见下表） |
| creator | Object | 创建者信息（见下表） |
| status | String | 状态（RUNNING/FAILED/SUCCESSFUL） |
| type | String | 类型（MANUAL/SYS_ONECE/SCHEDULED/SYS_SCHEDULED） |
| operation | String | 操作类型（EXECUTE/RETRY/ROLLBACK/SKIP/CANCEL） |
| executor | String | 执行主机 |
| prohibitRollback | Boolean | 是否禁止回滚 |
| subtasks | Array | 子任务列表（SubtaskInstance对象） |
| createTime | String | 创建时间 |
| startTime | String | 开始时间 |
| finishTime | String | 结束时间 |
**SubtaskInstance结构**：
| 参数 | 类型 | 说明 |
|------|------|------|
| id | Long | 子任务ID |
| name | String | 子任务名称 |
| seriesId | Long | 序列ID |
| description | String | 描述 |
| timeout | Integer | 超时时间（秒） |
| status | String | 状态（PENDING/READY/RUNNING/CANCELING/FAILED/SUCCESSFUL） |
| operation | String | 操作类型（EXECUTE/RETRY/ROLLBACK/SKIP/CANCEL） |
| executor | String | 执行节点 |
| runTime | Integer | 执行次数 |
| nodeType | String | 节点类型（如JAVA_TASK） |
| paralleIdx | Integer | 并行索引（-1表示非并行） |
| upstreams | Array<Long> | 上游子任务ID列表 |
| downstream | Array<Long> | 下游子任务ID列表 |
| prohibitRollback | Boolean | 是否禁止回滚 |
| createTime | String | 创建时间 |
| startTime | String | 开始时间 |
| finishTime | String | 结束时间 |
---
### 3. 回滚任务
**功能说明**：从所有失败子任务开始回滚。
**接口约束**：需具备 `TASK_MANAGER` 权限。
**请求路径**：`POST /api/v2/tasks/instances/{taskInstanceId}/rollback`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
**返回结果**：与 **查询任务详情** 的返回结果一致。
---
### 4. 重试任务
**功能说明**：重试任务的所有失败子任务。
**接口约束**：需具备 `TASK_MANAGER` 权限。
**请求路径**：`POST /api/v2/tasks/instances/{taskInstanceId}/retry`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
**返回结果**：与 **回滚任务** 的返回结果一致。
---
## 子任务操作
### 5. 取消子任务
**功能说明**：取消执行中的子任务，标记为失败。
**接口约束**：需具备 `TASK_MANAGER` 权限。
**请求路径**：`POST /api/v2/tasks/instances/{taskInstanceId}/subtasks/{subtaskInstanceId}/cancel`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
| subtaskInstanceId | Long | 是 | 10001 | 子任务实例ID |
**返回结果**：
| 参数 | 类型 | 说明 |
|------|------|------|
| successful | Boolean | 请求是否成功 |
| timestamp | Datetime | 服务端完成时间戳 |
| duration | Integer | 处理时间（毫秒） |
| status | Integer | HTTP状态码 |
| traceId | String | 请求追踪ID |
| server | String | 服务地址 |
---
### 6. 重试子任务
**功能说明**：重新执行失败的子任务。
**接口约束**：需具备 `TASK_MANAGER` 权限。
**请求路径**：`POST /api/v2/tasks/instances/{taskInstanceId}/subtasks/{subtaskInstanceId}/retry`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
| subtaskInstanceId | Long | 是 | 10001 | 子任务实例ID |
**返回结果**：
| 参数 | 类型 | 说明 |
|------|------|------|
| data | Object | SubtaskInstance对象 |
| successful | Boolean | 请求是否成功 |
| timestamp | Datetime | 服务端完成时间戳 |
| duration | Integer | 处理时间（毫秒） |
| status | Integer | HTTP状态码 |
| traceId | String | 请求追踪ID |
| server | String | 服务地址 |
**SubtaskInstance结构**：与 **查询任务详情** 中的结构一致。
---
### 7. 跳过子任务
**功能说明**：跳过失败的子任务，标记为成功。
**接口约束**：需具备 `TASK_MANAGER` 权限。
**请求路径**：`POST /api/v2/tasks/instances/{taskInstanceId}/subtasks/{subtaskInstanceId}/skip`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
| subtaskInstanceId | Long | 是 | 10001 | 子任务实例ID |
**返回结果**：与 **取消子任务** 的返回结果一致。
---
### 8. 查询子任务日志
**功能说明**：获取子任务执行日志。
**接口约束**：需具备 `TASK_VIEWER` 权限。
**请求路径**：`GET /api/v2/tasks/instances/{taskInstanceId}/subtasks/{subtaskInstanceId}/log`
**请求参数**：
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|------|------|------|--------|------|
| taskInstanceId | Long | 是 | 1000 | 任务实例ID |
| subtaskInstanceId | Long | 是 | 10001 | 子任务实例ID |
**返回结果**：
| 参数 | 类型 | 说明 |
|------|------|------|
| data | Object | 包含日志内容 |
| successful | Boolean | 请求是否成功 |
| timestamp | Datetime | 服务端完成时间戳 |
| duration | Integer | 处理时间（毫秒） |
| status | Integer | HTTP状态码 |
| traceId | String | 请求追踪ID |
| server | String | 服务地址 |
**data字段结构**：
```json
{
"log": "日志内容（多行用\\n分隔）"
}
```