first commit
This commit is contained in:
@@ -0,0 +1,328 @@
|
||||
# Python Gateway HTTP API 接口文档
|
||||
|
||||
## 概述
|
||||
|
||||
Python Gateway HTTP Server 提供RESTful API接口,用于文件上传、计算处理、设备管理和状态查询。
|
||||
|
||||
**服务器地址**: `http://<host>:<port>`
|
||||
**默认端口**: `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 | 初始版本,支持数据上传、计算和设备管理 |
|
||||
Reference in New Issue
Block a user