# Python Gateway HTTP API 接口文档 ## 概述 Python Gateway HTTP Server 提供RESTful API接口,用于文件上传、计算处理、设备管理和状态查询。 **服务器地址**: `http://:` **默认端口**: `5000` **当前版本**: `1.0.0` (在version.py中管理) **Content-Type**: `application/json` 或 `multipart/form-data` --- ## API 接口列表 ### 1. 上传数据并计算 **接口地址**: `/api/data` **请求方法**: `POST` **Content-Type**: `multipart/form-data` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | file | File | 是 | 要上传的文件(CSV格式) | | dev_id | String | 否 | 设备ID,默认为'default' | | init | Integer | 否 | 初始化标志(0或1),默认为0 | | device_name | String | 否 | 设备名称,用于设置文件根目录 | | file_type | String | 否 | 文件类型,默认为'raw' | | compress | String | 否 | 压缩类型('none'或'gz'),默认为'none' | | scale | Float | 否 | 数据缩放因子,默认为1.0 | | offset | Float | 否 | 数据偏移量,默认为0.0 | | row_count | Integer | 否 | 行数限制,默认为0(不限制) | #### 请求示例 ```bash curl -X POST http://localhost:5000/api/data \ -F "file=@data.csv" \ -F "dev_id=device1" \ -F "init=0" \ -F "device_name=TGX-08-0005" ``` #### 响应格式 成功响应(200 OK): ```json { "WtOSC": [1.234, 2.345, 3.456, 4.567, 5.678, 6.789, 7.890, 8.901], "WtINS": [2.345, 3.456, 4.567, 5.678, 6.789, 7.890, 8.901, 9.012], "WtISC": [3.456, 4.567, 5.678, 6.789, 7.890, 8.901, 9.012, 10.123], "WtALL": [4.567, 5.678, 6.789, 7.890, 8.901, 9.012, 10.123, 11.234], "AngOSC": [95.5, 185.3, 275.1], "AngINS": [105.2, 195.0, 284.8], "AngISC": [115.1, 204.9, 294.7], "AngALL": [125.0, 214.8, 304.6], "DmCORE": [100.5, 101.2, 102.3], "DmALL": [120.5, 121.2, 122.3], "EccentricityINS": 2.5, "EccentricityOSC": 3.2, "EccentricityISC": 1.8, "Volatility": [0.05, 0.08, 0.12], "EdgesA": [10.5, 20.3, 30.1, 40.9, 50.7, 60.5, 70.3, 80.1], "EdgesB": [15.5, 25.3, 35.1, 45.9, 55.7, 65.5, 75.3, 85.1] } ``` 错误响应(400 Bad Request): ```json { "error": "No file provided" } ``` 或 ```json { "error": "Failed to process file" } ``` 或 ```json { "error": "ComputeService not initialized for dev_id device1" } ``` #### 响应字段说明 | 字段名 | 类型 | 说明 | |--------|------|------| | WtOSC | Array[Float] | 外屏层壁厚(8个测量点) | | WtINS | Array[Float] | 绝缘层壁厚(8个测量点) | | WtISC | Array[Float] | 内屏层壁厚(8个测量点) | | WtALL | Array[Float] | 总壁厚(8个测量点) | | AngOSC | Array[Float] | 外屏层角度(3个角度值) | | AngINS | Array[Float] | 绝缘层角度(3个角度值) | | AngISC | Array[Float] | 内屏层角度(3个角度值) | | AngALL | Array[Float] | 总壁厚角度(3个角度值) | | DmCORE | Array[Float] | 核心直径(3个测量值) | | DmALL | Array[Float] | 总直径(3个测量值) | | EccentricityINS | Float | 绝缘层偏心率(百分比) | | EccentricityOSC | Float | 外屏层偏心率(百分比) | | EccentricityISC | Float | 内屏层偏心率(百分比) | | Volatility | Array[Float] | 波动性[设备1标准差, 设备2标准差, 总体标准差] | | EdgesA | Array[Float] | A边边缘位置(8个点) | | EdgesB | Array[Float] | B边边缘位置(8个点) | --- ### 2. 获取服务器状态 **接口地址**: `/api/status` **请求方法**: `GET` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | dev_id | String | 否 | 设备ID,如果不提供则返回服务器基本状态 | #### 请求示例 示例1:获取服务器基本状态 ```bash curl -X GET http://localhost:5000/api/status ``` 示例2:获取特定设备状态 ```bash curl -X GET "http://localhost:5000/api/status?dev_id=device1" ``` #### 响应格式 成功响应 - 基本状态(200 OK): ```json { "running": "true", "mqtt_connected": true, "version": "1.0.0" } ``` 或 ```json { "running": "false", "mqtt_connected": false, "version": "1.0.0" } ``` 成功响应 - 设备状态(200 OK): ```json { "running": true, "mqtt_connected": true, "compute_status": true, "version": "1.0.0" } ``` 或 ```json { "running": true, "mqtt_connected": true, "compute_status": false, "version": "1.0.0" } ``` #### 响应字段说明 | 字段名 | 类型 | 说明 | |--------|------|------| | running | String/Boolean | 服务器运行状态(不带dev_id时为字符串"true"/"false",带dev_id时为布尔值) | | mqtt_connected | Boolean | MQTT连接状态 | | compute_status | Boolean | 计算服务可用状态(仅当提供dev_id时返回) | | version | String | 软件版本号 | --- ### 3. 注册设备 **接口地址**: `/api/register` **请求方法**: `POST` **Content-Type**: `application/json` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | dev_id | String | 是 | 设备ID | #### 请求示例 ```bash curl -X POST http://localhost:5000/api/register \ -H "Content-Type: application/json" \ -d '{"dev_id": "device1"}' ``` #### 响应格式 成功响应(200 OK): ```json { "message": "Device registered successfully" } ``` 错误响应(400 Bad Request): ```json { "error": "dev_id is required" } ``` 或 ```json { "error": "Failed to initialize ComputeService: ..." } ``` --- ## 错误码说明 | HTTP状态码 | 说明 | |-----------|------| | 200 | 请求成功 | | 400 | 请求参数错误 | | 500 | 服务器内部错误 | --- ## 使用场景示例 ### 场景1:首次上传数据并计算 ```bash # 上传CSV文件并计算 curl -X POST http://localhost:5000/api/data \ -F "file=@measurement_data.csv" \ -F "dev_id=device1" \ -F "init=1" \ -F "device_name=TGX-08-0005" ``` ### 场景2:连续上传数据 ```bash # 后续上传,init=0 curl -X POST http://localhost:5000/api/data \ -F "file=@measurement_data_002.csv" \ -F "dev_id=device1" \ -F "init=0" ``` ### 场景3:检查服务器状态 ```bash # 查询服务器状态 curl -X GET http://localhost:5000/api/status ``` ### 场景4:注册新设备 ```bash # 注册新设备 curl -X POST http://localhost:5000/api/register \ -H "Content-Type: application/json" \ -d '{"dev_id": "device2"}' ``` --- ## 注意事项 1. **文件格式**: 上传的文件应为CSV格式,包含CH1和CH2两列数据 2. **设备ID**: 每个设备需要先通过`/api/register`接口注册,才能进行计算 3. **初始化**: 首次上传数据时建议设置`init=1`,后续上传设置`init=0` 4. **文件大小**: 建议单次上传文件不超过10MB 5. **并发处理**: 服务器支持多线程并发处理请求 6. **MQTT发布**: 计算结果会自动发布到MQTT主题(如果MQTT已启用) --- ## 配置说明 服务器配置存储在`config.json`文件中,主要配置项: ```json { "http": { "host": "0.0.0.0", "port": 5000 }, "mqtt": { "enable": true, "broker": "123.57.81.127", "port": 1883, "username": "test", "password": "test" }, "file_root": "D:\\CPY_DTAT", "template_path": "D:\\Python\\CPY_Server\\InStructTemplate.mat" } ``` --- ## 版本历史 | 版本 | 日期 | 说明 | |------|------|------| | 1.0.0 | 2026-01-05 | 初始版本,支持数据上传、计算和设备管理 |