zhanghuilai/UAV-CO2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
af56c94efe2c822d7ec21a6e9a785dab5ed1e7fa
UAV-CO2/API_ENDPOINTS.md
zhanghuilai d5edbc0723 增加web_api
2026-02-05 15:13:54 +08:00

18 KiB
Raw Blame History

GasFlux Web API 端点参考

概述

GasFlux Web API 是一个基于 Flask 的 RESTful API，用于上传数据文件、执行气体通量分析处理，并下载处理结果。

基础信息:

  • 基础 URL: http://localhost:5000
  • 认证: 无需认证
  • 数据格式: JSON
  • 文件大小限制: 100MB
  • 支持的文件类型: .xlsx, .xls, .yaml, .yml

🔍 监控和健康检查

1. 获取健康状态

端点: GET /health

描述: 获取 API 的健康状态、系统信息和性能指标。

响应示例 (200):

{
  "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):

{
  "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):

{
  "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):

{
  "code": 200,
  "message": "统计信息重置成功",
  "data": {
    "timestamp": 1705257600.123
  }
}

状态码:

  • 200: 成功

4. 获取配置信息

端点: GET /config

描述: 获取当前应用配置信息和支持的环境变量。

响应示例 (200):

{
  "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):

{
  "code": 202,
  "message": "任务已接受并加入处理队列",
  "data": {
    "status": "accepted",
    "job_id": "abc123-def456-ghi789",
    "task_status_url": "/task/abc123-def456-ghi789"
  }
}

错误响应示例 (400):

{
  "code": 400,
  "message": "无效的数据文件类型。只允许 .xlsx 和 .xls 格式。",
  "data": {}
}

错误响应示例 (413):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "code": 200,
  "message": "任务查询成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "processing",
    "message": "GasFlux 分析完成，正在生成报告...",
    "updated_at": 1705257600.123
  }
}

响应示例 - 处理完成 (200):

{
  "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):

{
  "code": 404,
  "message": "任务未找到",
  "data": {}
}

状态码:

  • 200: 成功
  • 404: 任务不存在

11. 更新任务状态

端点: PUT /task/{task_id}

描述: 更新任务的状态、信息或优先级。

路径参数:

  • task_id: 任务 ID (UUID 格式)

请求参数 (JSON):

  • status (可选): 新的任务状态
  • message (可选): 状态消息或错误描述
  • priority (可选): 任务优先级 (normal/high/low)

响应示例 (200):

{
  "code": 200,
  "message": "任务更新成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "updated",
    "task_info": {
      "status": "completed",
      "message": "手动标记为完成",
      "updated_at": 1705257600.123,
      "priority": "normal"
    }
  }
}

错误响应示例 (404):

{
  "code": 404,
  "message": "任务未找到",
  "data": {}
}

错误响应示例 (400):

{
  "code": 400,
  "message": "无效状态。必须是以下之一: pending, processing, completed, failed",
  "data": {}
}

状态码:

  • 200: 成功
  • 400: 无效请求
  • 404: 任务不存在

12. 删除任务

端点: DELETE /task/{task_id}

描述: 删除任务及其所有相关的文件和数据。

路径参数:

  • task_id: 任务 ID (UUID 格式)

响应示例 (200):

{
  "code": 200,
  "message": "任务及相关文件删除成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "deleted",
    "details": {
      "folders_deleted": 1,
      "total_size_deleted": 307200,
      "task_status": "completed"
    }
  }
}

错误响应示例 (404):

{
  "code": 404,
  "message": "任务未找到",
  "data": {}
}

错误响应示例 (409):

{
  "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):

{
  "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):

{
  "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