Files
CPY_AlgorithmGateway/API_DOCUMENTATION.md

7.3 KiB
Raw Permalink Blame History

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(不限制)

请求示例

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

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

{
  "error": "No file provided"
}

或

{
  "error": "Failed to process file"
}

或

{
  "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:获取服务器基本状态

curl -X GET http://localhost:5000/api/status

示例2:获取特定设备状态

curl -X GET "http://localhost:5000/api/status?dev_id=device1"

响应格式

成功响应 - 基本状态(200 OK):

{
  "running": "true",
  "mqtt_connected": true,
  "version": "1.0.0"
}

或

{
  "running": "false",
  "mqtt_connected": false,
  "version": "1.0.0"
}

成功响应 - 设备状态(200 OK):

{
  "running": true,
  "mqtt_connected": true,
  "compute_status": true,
  "version": "1.0.0"
}

或

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

请求示例

curl -X POST http://localhost:5000/api/register \
  -H "Content-Type: application/json" \
  -d '{"dev_id": "device1"}'

响应格式

成功响应(200 OK):

{
  "message": "Device registered successfully"
}

错误响应(400 Bad Request):

{
  "error": "dev_id is required"
}

或

{
  "error": "Failed to initialize ComputeService: ..."
}

错误码说明

HTTP状态码 说明
200 请求成功
400 请求参数错误
500 服务器内部错误

使用场景示例

场景1:首次上传数据并计算

# 上传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:连续上传数据

# 后续上传,init=0
curl -X POST http://localhost:5000/api/data \
  -F "file=@measurement_data_002.csv" \
  -F "dev_id=device1" \
  -F "init=0"

场景3:检查服务器状态

# 查询服务器状态
curl -X GET http://localhost:5000/api/status

场景4:注册新设备

# 注册新设备
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文件中,主要配置项:

{
  "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 初始版本,支持数据上传、计算和设备管理