520 lines
10 KiB
Markdown
520 lines
10 KiB
Markdown
# 天风任务系统 API 接口文档
|
||
|
||
## 目录
|
||
|
||
- [组件管理 API](#组件管理-api)
|
||
- [获取所有组件类型及详细信息](#获取所有组件类型及详细信息)
|
||
- [获取指定类型的组件详细信息](#获取指定类型的组件详细信息)
|
||
- [自动发现并注册组件](#自动发现并注册组件)
|
||
- [任务管理 API](#任务管理-api)
|
||
- [获取任务列表](#获取任务列表)
|
||
- [获取任务类型列表](#获取任务类型列表)
|
||
- [创建任务](#创建任务)
|
||
- [删除任务](#删除任务)
|
||
- [批量删除任务](#批量删除任务)
|
||
- [更新任务基本信息](#更新任务基本信息)
|
||
- [获取任务编辑信息](#获取任务编辑信息)（还没完成）
|
||
- [获取可用的子任务列表](#获取可用的子任务列表)
|
||
- [任务参数管理 API](#任务参数管理-api)
|
||
- [获取任务输入参数表单字段定义](#获取任务输入参数表单字段定义)
|
||
- [获取任务输入参数配置](#获取任务输入参数配置)
|
||
- [更新任务输入参数配置](#更新任务输入参数配置)
|
||
|
||
## 组件管理 API
|
||
|
||
### 获取所有组件类型及详细信息
|
||
|
||
获取系统中所有组件类型及其详细信息。
|
||
|
||
**接口地址**：`/component/components`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取组件类型成功",
|
||
"data": {
|
||
"component_types": ["string"],
|
||
"component_type_info": [
|
||
{
|
||
"type": "string",
|
||
"name": "string"
|
||
}
|
||
],
|
||
"component_categories": {
|
||
"category": ["string"]
|
||
},
|
||
"component_details": ["object"],
|
||
"component_details_by_type": {
|
||
"type": ["object"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `component_types`: 所有组件类型的列表
|
||
- `component_type_info`: 包含中文名称的组件类型信息
|
||
- `component_categories`: 按类别分组的组件类型
|
||
- `component_details`: 所有组件的详细配置
|
||
- `component_details_by_type`: 按组件类型分组的详细配置
|
||
|
||
### 获取指定类型的组件详细信息
|
||
|
||
获取指定类型的组件详细信息。
|
||
|
||
**接口地址**：`/component/components/{component_type}`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| component_type | string | 是 | 组件类型 |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取组件详细信息成功",
|
||
"data": {
|
||
"components": ["object"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `components`: 指定类型的组件详细配置列表
|
||
|
||
### 自动发现并注册组件
|
||
|
||
自动发现并注册组件。
|
||
|
||
**接口地址**：`/component/components/discover`
|
||
|
||
**请求方式**：`POST`
|
||
|
||
**请求参数**：
|
||
|
||
```json
|
||
{
|
||
"package_name": "string"
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "自动发现组件成功，共发现 x 个组件",
|
||
"data": {
|
||
"component_types": ["string"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `component_types`: 发现的组件类型列表
|
||
|
||
## 任务管理 API
|
||
|
||
### 获取任务列表
|
||
|
||
获取任务列表，支持多种筛选条件、排序和分页。
|
||
|
||
**接口地址**：`/tasks`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| status | string | 否 | 任务状态 |
|
||
| task_type | string | 否 | 任务类型 |
|
||
| name | string | 否 | 任务名称（模糊查询）|
|
||
| is_scheduled | boolean | 否 | 是否为定时任务 |
|
||
| created_start | integer | 否 | 创建时间起始（毫秒时间戳）|
|
||
| created_end | integer | 否 | 创建时间结束（毫秒时间戳）|
|
||
| sort_by | string | 否 | 排序字段，默认为 CREATED_AT |
|
||
| sort_order | string | 否 | 排序方式，默认为 DESC |
|
||
| page | integer | 否 | 页码，默认为 1 |
|
||
| page_size | integer | 否 | 每页数量，默认为 10 |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取任务列表成功",
|
||
"data": {
|
||
"tasks": ["object"],
|
||
"pagination": {
|
||
"page": 1,
|
||
"page_size": 10,
|
||
"total": 100,
|
||
"total_pages": 10
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `tasks`: 任务列表
|
||
- `pagination`: 分页信息
|
||
|
||
### 获取任务类型列表
|
||
|
||
获取系统中所有任务类型列表。
|
||
|
||
**接口地址**：`/task/types`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取任务类型列表成功",
|
||
"data": [
|
||
{
|
||
"key": "string",
|
||
"name": "string",
|
||
"description": "string",
|
||
"value": "string"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `key`: 任务类型的键
|
||
- `name`: 任务类型的名称
|
||
- `description`: 任务类型的描述
|
||
- `value`: 任务类型的枚举值
|
||
|
||
### 创建任务
|
||
|
||
创建一个新任务。
|
||
|
||
**接口地址**：`/task/create`
|
||
|
||
**请求方式**：`POST`
|
||
|
||
**请求参数**：
|
||
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"task_type": "string"
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "创建任务成功",
|
||
"data": {
|
||
"task_id": "string",
|
||
"name": "string",
|
||
"task_type": "string",
|
||
"task_type_name": "string",
|
||
"created_at": "timestamp",
|
||
"updated_at": "timestamp"
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `task_id`: 任务ID
|
||
- `name`: 任务名称
|
||
- `task_type`: 任务类型
|
||
- `task_type_name`: 任务类型中文名称
|
||
|
||
### 删除任务
|
||
|
||
删除指定ID的任务。
|
||
|
||
**接口地址**：`/task/{task_id}`
|
||
|
||
**请求方式**：`DELETE`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| task_id | string | 是 | 任务ID |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除任务成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 批量删除任务
|
||
|
||
批量删除多个任务。
|
||
|
||
**接口地址**：`/task/batch`
|
||
|
||
**请求方式**：`DELETE`
|
||
|
||
**请求参数**：
|
||
|
||
```json
|
||
{
|
||
"task_ids": ["string"]
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "批量删除任务成功，共删除 x 个任务",
|
||
"data": {
|
||
"deleted_count": 0,
|
||
"total_count": 0,
|
||
"not_found_ids": ["string"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `deleted_count`: 成功删除的任务数量
|
||
- `total_count`: 总共请求删除的任务数量
|
||
- `not_found_ids`: 未找到的任务ID列表
|
||
|
||
### 更新任务基本信息
|
||
|
||
更新任务的基本信息。
|
||
|
||
**接口地址**：`/task/{task_id}`
|
||
|
||
**请求方式**：`PUT`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| task_id | string | 是 | 任务ID |
|
||
|
||
```json
|
||
{
|
||
"name": "string",
|
||
"description": "string",
|
||
"task_type": "string",
|
||
"blocks": ["object"],
|
||
"variables": ["object"],
|
||
"schedule": "object"
|
||
}
|
||
```
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新任务成功",
|
||
"data": {
|
||
"task": "object"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取任务编辑信息
|
||
|
||
获取任务的编辑信息，包括任务实例、组件、参数等。
|
||
|
||
**接口地址**：`/task/{task_id}/edit`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| task_id | string | 是 | 任务ID |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取任务编辑信息成功",
|
||
"data": {
|
||
"task": "object",
|
||
"instance": "object",
|
||
"component_types": "object",
|
||
"common_params": "object",
|
||
"task_input_params": ["object"],
|
||
"block_output_params": "object",
|
||
"context_params": "object"
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `task`: 任务基本信息
|
||
- `instance`: 任务实例信息
|
||
- `component_types`: 组件类型信息
|
||
- `common_params`: 常用参数数据
|
||
- `task_input_params`: 任务输入参数
|
||
- `block_output_params`: 块输出参数
|
||
- `context_params`: 上下文参数
|
||
|
||
### 获取可用的子任务列表
|
||
|
||
获取可用的子任务列表，用于任务嵌套。
|
||
|
||
**接口地址**：`/tasks/available-subtasks`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| current_task_id | string | 否 | 当前任务ID，用于排除自身 |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取可用子任务列表成功",
|
||
"data": {
|
||
"subtasks": [
|
||
{
|
||
"task_id": "string",
|
||
"name": "string"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 任务参数管理 API
|
||
|
||
### 获取任务输入参数表单字段定义
|
||
|
||
获取任务输入参数表单字段定义，用于前端表单生成。
|
||
|
||
**接口地址**：`/task/input-params/fields`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：无
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取任务输入参数表单字段定义成功",
|
||
"data": {
|
||
"form_fields": ["object"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `form_fields`: 表单字段定义列表
|
||
|
||
### 获取任务输入参数配置
|
||
|
||
获取任务输入参数配置，包括系统默认参数和用户自定义参数。
|
||
|
||
**接口地址**：`/task/{task_id}/input-params`
|
||
|
||
**请求方式**：`GET`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| task_id | string | 是 | 任务ID |
|
||
| instance_id | string | 否 | 任务实例ID，不传则使用最新实例 |
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取任务输入参数成功",
|
||
"data": {
|
||
"task_id": "string",
|
||
"instance_id": "string",
|
||
"params": ["object"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `params`: 任务输入参数列表
|
||
|
||
### 更新任务输入参数配置
|
||
|
||
更新任务输入参数配置，批量保存用户自定义的任务输入参数配置。
|
||
|
||
**接口地址**：`/task/{task_id}/input-params`
|
||
|
||
**请求方式**：`POST`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必须 | 说明 |
|
||
|-------|------|------|------|
|
||
| task_id | string | 是 | 任务ID |
|
||
| instance_id | string | 否 | 任务实例ID，不传则使用最新实例或创建新实例 |
|
||
|
||
请求体：
|
||
```json
|
||
[
|
||
{
|
||
"param_name": "string",
|
||
"label": "string",
|
||
"param_type": "string",
|
||
"required": true,
|
||
"default_value": "any",
|
||
"description": "string"
|
||
}
|
||
]
|
||
```
|
||
|
||
**响应数据**：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新任务输入参数成功",
|
||
"data": {
|
||
"task_id": "string",
|
||
"instance_id": "string",
|
||
"updated_params_count": 0,
|
||
"has_changes": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**：
|
||
- `updated_params_count`: 更新的参数数量
|
||
- `has_changes`: 是否有参数变动 |