782 lines
18 KiB
Markdown
782 lines
18 KiB
Markdown
# GasFlux Web API 端点参考
|
||
|
||
## 概述
|
||
|
||
GasFlux Web API 是一个基于 Flask 的 RESTful API，用于上传数据文件、执行气体通量分析处理，并下载处理结果。
|
||
|
||
**基础信息:**
|
||
- **基础 URL**: `http://localhost:5000`
|
||
- **认证**: 无需认证
|
||
- **数据格式**: JSON
|
||
- **文件大小限制**: 100MB
|
||
- **支持的文件类型**: `.xlsx`, `.xls`, `.yaml`, `.yml`
|
||
|
||
---
|
||
|
||
## 🔍 监控和健康检查
|
||
|
||
### 1. 获取健康状态
|
||
**端点**: `GET /health`
|
||
|
||
**描述**: 获取 API 的健康状态、系统信息和性能指标。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "健康检查完成",
|
||
"data": {
|
||
"status": "healthy",
|
||
"version": "1.0.0",
|
||
"timestamp": 1705257600.123,
|
||
"uptime": "2h 30m 15s",
|
||
"storage": {
|
||
"uploads_writable": true,
|
||
"outputs_writable": true
|
||
},
|
||
"tasks": {
|
||
"active_count": 2,
|
||
"total_tracked": 15,
|
||
"total_processed": 13,
|
||
"success_rate_percent": 92.31
|
||
},
|
||
"performance": {
|
||
"requests_per_second": 0.08,
|
||
"avg_response_time_ms": 234.56,
|
||
"error_rate_percent": 1.5
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例** (503):
|
||
```json
|
||
{
|
||
"code": 503,
|
||
"message": "服务不可用",
|
||
"data": {
|
||
"status": "degraded",
|
||
"version": "1.0.0",
|
||
"timestamp": 1705257600.123,
|
||
"uptime": "1h 30m 45s",
|
||
"storage": {
|
||
"uploads_writable": true,
|
||
"outputs_writable": true
|
||
},
|
||
"tasks": {
|
||
"active_count": 0,
|
||
"total_tracked": 5,
|
||
"total_processed": 3,
|
||
"success_rate_percent": 60.0
|
||
},
|
||
"performance": {
|
||
"requests_per_second": 0.12,
|
||
"avg_response_time_ms": 145.67,
|
||
"error_rate_percent": 50.0
|
||
},
|
||
"issues": [
|
||
"错误率过高 (50.0%)",
|
||
"活跃任务数量过多 (25)"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: API 健康
|
||
- `503`: API 不健康
|
||
|
||
---
|
||
|
||
### 2. 获取系统统计信息
|
||
**端点**: `GET /stats`
|
||
|
||
**描述**: 获取详细的 API 统计信息、性能指标和系统监控数据。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "统计信息获取成功",
|
||
"data": {
|
||
"summary": {
|
||
"uptime_seconds": 3600.5,
|
||
"uptime_formatted": "1h 0m 0s",
|
||
"requests_total": 150,
|
||
"requests_per_second": 0.04,
|
||
"error_rate_percent": 2.0,
|
||
"active_tasks": 1
|
||
},
|
||
"requests": {
|
||
"by_method": {
|
||
"GET": 120,
|
||
"POST": 30
|
||
},
|
||
"by_status": {
|
||
"200": 145,
|
||
"400": 3,
|
||
"500": 2
|
||
},
|
||
"top_endpoints": {
|
||
"/task/abc123": 45,
|
||
"/health": 30,
|
||
"/": 25
|
||
}
|
||
},
|
||
"tasks": {
|
||
"total_created": 25,
|
||
"total_completed": 20,
|
||
"total_failed": 2,
|
||
"success_rate_percent": 90.91,
|
||
"by_status": {
|
||
"pending": 1,
|
||
"processing": 1,
|
||
"completed": 20,
|
||
"failed": 2
|
||
}
|
||
},
|
||
"performance": {
|
||
"avg_response_time_ms": 245.67,
|
||
"max_response_time_ms": 1250.34,
|
||
"min_response_time_ms": 12.45
|
||
},
|
||
"system": {
|
||
"memory_usage_percent": 45.2,
|
||
"memory_used_gb": 7.3,
|
||
"memory_total_gb": 16.0,
|
||
"disk_usage_percent": 23.1,
|
||
"disk_used_gb": 46.8,
|
||
"disk_total_gb": 203.2
|
||
},
|
||
"recent_tasks": [
|
||
{
|
||
"task_id": "abc123-def456",
|
||
"status": "completed",
|
||
"age_seconds": 45.2,
|
||
"message": "处理完成成功"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
### 3. 重置统计信息
|
||
**端点**: `POST /stats/reset`
|
||
|
||
**描述**: 重置所有 API 统计数据（管理员功能）。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "统计信息重置成功",
|
||
"data": {
|
||
"timestamp": 1705257600.123
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
### 4. 获取配置信息
|
||
**端点**: `GET /config`
|
||
|
||
**描述**: 获取当前应用配置信息和支持的环境变量。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "配置信息获取成功",
|
||
"data": {
|
||
"configuration": {
|
||
"host": "0.0.0.0",
|
||
"port": 5000,
|
||
"debug": false,
|
||
"base_dir": "/app",
|
||
"upload_folder": "/app/web_api_data/uploads",
|
||
"output_folder": "/app/web_api_data/outputs",
|
||
"max_content_length": 104857600,
|
||
"log_level": "INFO",
|
||
"log_file": "logs/gasflux_api.log",
|
||
"cors_origins": ["*"],
|
||
"task_cleanup_interval": 3600,
|
||
"max_task_age": 86400,
|
||
"threads": 8,
|
||
"connection_limit": 100,
|
||
"channel_timeout": 300
|
||
},
|
||
"environment_variables": {
|
||
"supported": [
|
||
"GASFLUX_HOST", "GASFLUX_PORT", "GASFLUX_DEBUG",
|
||
"GASFLUX_UPLOAD_FOLDER", "GASFLUX_OUTPUT_FOLDER",
|
||
"GASFLUX_MAX_CONTENT_LENGTH", "GASFLUX_LOG_LEVEL",
|
||
"GASFLUX_LOG_FILE", "GASFLUX_CORS_ORIGINS",
|
||
"GASFLUX_TASK_CLEANUP_INTERVAL", "GASFLUX_MAX_TASK_AGE",
|
||
"GASFLUX_THREADS", "GASFLUX_CONNECTION_LIMIT",
|
||
"GASFLUX_CHANNEL_TIMEOUT"
|
||
],
|
||
"current_values": {
|
||
"GASFLUX_HOST": "0.0.0.0",
|
||
"GASFLUX_PORT": "5000",
|
||
"GASFLUX_DEBUG": "false"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
## 📤 文件上传和管理
|
||
|
||
### 5. 文件上传和处理
|
||
**端点**: `POST /upload`
|
||
|
||
**描述**: 上传数据文件并启动异步处理任务。
|
||
|
||
**请求参数** (multipart/form-data):
|
||
- `file` (必需): 数据文件 (.xlsx 或 .xls 格式)
|
||
- `config` (可选): 配置文件 (.yaml 或 .yml 格式)
|
||
|
||
**响应示例** (202):
|
||
```json
|
||
{
|
||
"code": 202,
|
||
"message": "任务已接受并加入处理队列",
|
||
"data": {
|
||
"status": "accepted",
|
||
"job_id": "abc123-def456-ghi789",
|
||
"task_status_url": "/task/abc123-def456-ghi789"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (400):
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "无效的数据文件类型。只允许 .xlsx 和 .xls 格式。",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (413):
|
||
```json
|
||
{
|
||
"code": 413,
|
||
"message": "文件过大。最大尺寸为 100MB。",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `202`: 任务已接受
|
||
- `400`: 请求参数错误
|
||
- `413`: 文件过大
|
||
|
||
---
|
||
|
||
## 📊 任务管理和监控
|
||
|
||
### 6. 分页查询任务列表
|
||
**端点**: `GET /tasks`
|
||
|
||
**描述**: 分页查询所有任务，支持按状态过滤、排序和分页。返回体为前端友好的瘦身结构：仅包含任务状态信息；当任务已完成时会包含 `downloads` 直达下载链接。
|
||
|
||
**查询参数**:
|
||
- `page` (可选): 页码 (默认: 1)
|
||
- `page_size` (可选): 每页任务数量 (默认: 20, 最大: 100)
|
||
- `sort_by` (可选): 排序字段 ('created_at', 'updated_at', 'status') (默认: 'updated_at')
|
||
- `sort_order` (可选): 排序顺序 ('asc', 'desc') (默认: 'desc')
|
||
- `status` (可选): 按任务状态过滤，支持多个状态用逗号分隔
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务列表查询成功",
|
||
"data": {
|
||
"tasks": [
|
||
{
|
||
"task_id": "abc123-def456-ghi789",
|
||
"status": "completed",
|
||
"message": "Processing completed successfully",
|
||
"updated_at": 1705257700.456,
|
||
"downloads": {
|
||
"data_xlsx": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
|
||
"report_ch4": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
|
||
"report_co2": "/download/abc123-def456-ghi789/08_34_01_5m.processed_co2_report.html",
|
||
"config": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
|
||
"metadata": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json"
|
||
}
|
||
},
|
||
{
|
||
"task_id": "xyz789-abc123-def456",
|
||
"status": "processing",
|
||
"message": "正在进行数据分析...",
|
||
"updated_at": 1705257650.321
|
||
}
|
||
],
|
||
"total": 25,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"total_pages": 2,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
- `400`: 参数无效
|
||
|
||
---
|
||
|
||
### 7. 获取任务池统计信息
|
||
**端点**: `GET /tasks/stats`
|
||
|
||
**描述**: 获取任务池的统计信息，包括各状态任务数量、活跃任务数等。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务池统计信息查询成功",
|
||
"data": {
|
||
"total_tasks": 25,
|
||
"status_counts": {
|
||
"pending": 3,
|
||
"processing": 2,
|
||
"completed": 18,
|
||
"failed": 2
|
||
},
|
||
"active_tasks": 2,
|
||
"queued_tasks": 3,
|
||
"completed_tasks": 18,
|
||
"failed_tasks": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
### 8. 获取活跃任务列表
|
||
**端点**: `GET /tasks/active`
|
||
|
||
**描述**: 获取当前正在处理的任务列表（瘦身结构）。当列表中包含已完成任务时会附带 `downloads` 直达下载链接。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "活跃任务查询成功",
|
||
"data": {
|
||
"active_tasks": [
|
||
{
|
||
"task_id": "abc123-def456-ghi789",
|
||
"status": "processing",
|
||
"message": "正在生成报告...",
|
||
"updated_at": 1705257650.321
|
||
},
|
||
{
|
||
"task_id": "completed-task-123",
|
||
"status": "completed",
|
||
"message": "Processing completed successfully",
|
||
"updated_at": 1705257550.456,
|
||
"downloads": {
|
||
"data_xlsx": "/download/completed-task-123/processed_data.xlsx",
|
||
"report_html": "/download/completed-task-123/data_report.html"
|
||
}
|
||
}
|
||
],
|
||
"count": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
### 9. 获取队列任务列表
|
||
**端点**: `GET /tasks/queue`
|
||
|
||
**描述**: 获取等待处理的任务队列（瘦身结构）。当列表中包含已完成任务时会附带 `downloads` 直达下载链接。
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "队列任务查询成功",
|
||
"data": {
|
||
"queued_tasks": [
|
||
{
|
||
"task_id": "xyz789-abc123-def456",
|
||
"status": "pending",
|
||
"message": "等待处理",
|
||
"updated_at": 1705257400.123
|
||
},
|
||
{
|
||
"task_id": "completed-queued-task",
|
||
"status": "completed",
|
||
"message": "Processing completed successfully",
|
||
"updated_at": 1705257450.321,
|
||
"downloads": {
|
||
"data_xlsx": "/download/completed-queued-task/processed_data.xlsx",
|
||
"report_html": "/download/completed-queued-task/analysis_report.html"
|
||
}
|
||
}
|
||
],
|
||
"count": 2,
|
||
"queue_position_info": "任务按创建时间排序，较早的任务优先处理"
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
### 10. 查询任务状态
|
||
**端点**: `GET /task/{task_id}`
|
||
|
||
**描述**: 查询异步处理任务的当前状态和进度信息。
|
||
|
||
**路径参数**:
|
||
- `task_id`: 任务 ID (UUID 格式)
|
||
|
||
**响应示例** - 处理中 (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务查询成功",
|
||
"data": {
|
||
"task_id": "abc123-def456-ghi789",
|
||
"status": "processing",
|
||
"message": "GasFlux 分析完成，正在生成报告...",
|
||
"updated_at": 1705257600.123
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例** - 处理完成 (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务查询成功",
|
||
"data": {
|
||
"task_id": "abc123-def456-ghi789",
|
||
"status": "completed",
|
||
"message": "处理完成成功",
|
||
"updated_at": 1705257600.123,
|
||
"results": [
|
||
{
|
||
"name": "08_34_01_5m.processed_ch4_report.html",
|
||
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
|
||
"size": 245760,
|
||
"type": "report"
|
||
},
|
||
{
|
||
"name": "08_34_01_5m.processed_data.xlsx",
|
||
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
|
||
"size": 153600,
|
||
"type": "data"
|
||
},
|
||
{
|
||
"name": "08_34_01_5m.processed_config.yaml",
|
||
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
|
||
"size": 2048,
|
||
"type": "config"
|
||
},
|
||
{
|
||
"name": "08_34_01_5m.processed_output_vars.json",
|
||
"rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json",
|
||
"size": 4096,
|
||
"type": "metadata"
|
||
}
|
||
],
|
||
"downloads": {
|
||
"data_xlsx": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
|
||
"report_ch4": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
|
||
"report_co2": "/download/abc123-def456-ghi789/08_34_01_5m.processed_co2_report.html",
|
||
"config": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
|
||
"metadata": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例** - 任务不存在 (404):
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "任务未找到",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
- `404`: 任务不存在
|
||
|
||
---
|
||
|
||
### 11. 更新任务状态
|
||
**端点**: `PUT /task/{task_id}`
|
||
|
||
**描述**: 更新任务的状态、信息或优先级。
|
||
|
||
**路径参数**:
|
||
- `task_id`: 任务 ID (UUID 格式)
|
||
|
||
**请求参数** (JSON):
|
||
- `status` (可选): 新的任务状态
|
||
- `message` (可选): 状态消息或错误描述
|
||
- `priority` (可选): 任务优先级 (normal/high/low)
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务更新成功",
|
||
"data": {
|
||
"task_id": "abc123-def456-ghi789",
|
||
"status": "updated",
|
||
"task_info": {
|
||
"status": "completed",
|
||
"message": "手动标记为完成",
|
||
"updated_at": 1705257600.123,
|
||
"priority": "normal"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (404):
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "任务未找到",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (400):
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "无效状态。必须是以下之一: pending, processing, completed, failed",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
- `400`: 无效请求
|
||
- `404`: 任务不存在
|
||
|
||
---
|
||
|
||
### 12. 删除任务
|
||
**端点**: `DELETE /task/{task_id}`
|
||
|
||
**描述**: 删除任务及其所有相关的文件和数据。
|
||
|
||
**路径参数**:
|
||
- `task_id`: 任务 ID (UUID 格式)
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "任务及相关文件删除成功",
|
||
"data": {
|
||
"task_id": "abc123-def456-ghi789",
|
||
"status": "deleted",
|
||
"details": {
|
||
"folders_deleted": 1,
|
||
"total_size_deleted": 307200,
|
||
"task_status": "completed"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (404):
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "任务未找到",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (409):
|
||
```json
|
||
{
|
||
"code": 409,
|
||
"message": "无法删除当前正在处理或等待处理的任务",
|
||
"data": {
|
||
"task_status": "processing"
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
- `404`: 任务不存在
|
||
- `409`: 任务正在处理
|
||
|
||
---
|
||
|
||
## 📋 报告管理和查询
|
||
|
||
### 13. 分页查询已生成报告
|
||
**端点**: `GET /reports`
|
||
|
||
**描述**: 分页查询所有已生成的处理报告，支持排序和过滤。
|
||
|
||
**查询参数**:
|
||
- `page` (可选): 页码 (默认: 1)
|
||
- `per_page` (可选): 每页报告数量 (默认: 20, 最大: 100)
|
||
- `sort_by` (可选): 排序字段 (默认: created_at)
|
||
- `sort_order` (可选): 排序顺序 (默认: desc)
|
||
- `status` (可选): 按任务状态过滤
|
||
|
||
**响应示例** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "报告列表获取成功",
|
||
"data": {
|
||
"reports": [
|
||
{
|
||
"task_id": "abc123-def456-ghi789",
|
||
"report_name": "08_34_01_5m",
|
||
"status": "completed",
|
||
"created_at": 1705257600.123,
|
||
"file_count": 4,
|
||
"total_size": 307200,
|
||
"processing_time_seconds": 125.67,
|
||
"main_report": {
|
||
"name": "08_34_01_5m.processed_ch4_report.html",
|
||
"size": 245760,
|
||
"type": "report",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_ch4_report.html"
|
||
},
|
||
"all_files": [
|
||
{
|
||
"name": "08_34_01_5m.processed_ch4_report.html",
|
||
"size": 245760,
|
||
"type": "report",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_ch4_report.html"
|
||
},
|
||
{
|
||
"name": "08_34_01_5m.processed_data.csv",
|
||
"size": 153600,
|
||
"type": "data",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_data.csv"
|
||
},
|
||
{
|
||
"name": "08_34_01_5m.processed_config.yaml",
|
||
"size": 2048,
|
||
"type": "config",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_config.yaml"
|
||
},
|
||
{
|
||
"name": "08_34_01_5m.processed_output_vars.json",
|
||
"size": 4096,
|
||
"type": "metadata",
|
||
"download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_output_vars.json"
|
||
}
|
||
],
|
||
"run_directory": "abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"per_page": 20,
|
||
"total_reports": 45,
|
||
"total_pages": 3,
|
||
"has_next": true,
|
||
"has_prev": false
|
||
},
|
||
"filters": {
|
||
"sort_by": "created_at",
|
||
"sort_order": "desc",
|
||
"status": null
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应示例** (400):
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "Invalid parameter: per_page must be between 1 and 100",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
- `400`: 参数无效
|
||
|
||
---
|
||
|
||
## 📁 文件下载
|
||
|
||
### 14. 下载处理结果
|
||
**端点**: `GET /download/{filename}`
|
||
|
||
**描述**: 下载处理后的结果文件，支持传入完整文件路径。
|
||
|
||
**路径参数**:
|
||
- `filename`: 文件的完整路径或相对路径 (包含任务ID)
|
||
|
||
**状态码**:
|
||
- `200`: 成功下载文件
|
||
- `403`: 访问被拒绝
|
||
- `404`: 文件不存在
|
||
- `400`: 路径不是文件
|
||
|
||
---
|
||
|
||
## 🌐 Web 界面
|
||
|
||
### 15. Web 管理界面
|
||
**端点**: `GET /`
|
||
|
||
**描述**: 访问用户友好的 Web 界面，支持文件上传、任务监控和结果下载。
|
||
|
||
**状态码**:
|
||
- `200`: 成功
|
||
|
||
---
|
||
|
||
*最后更新: 2026年1月29日*
|
||
|
||
*GasFlux Web API 版本: 1.0.0* |