Files
CPY_AlgorithmGateway/API_DOCUMENTATION.md
T

329 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 | 初始版本,支持数据上传、计算和设备管理 |