419 lines
6.2 KiB
Markdown
419 lines
6.2 KiB
Markdown
---
|
||
|
||
```markdown
|
||
# 📘 IoT API 接口文档
|
||
|
||
> 模块：`iot_api`
|
||
> 作者：**anlicheng**
|
||
> 创建时间：2023-12-24
|
||
> 数据格式：`application/json`
|
||
> 认证方式：内置 `API_TOKEN = "wv6fGyBhl*7@AsD9"`
|
||
|
||
---
|
||
|
||
## 🔐 通用请求头
|
||
|
||
| Header | 值 | 说明 |
|
||
|--------|----|------|
|
||
| Content-Type | application/json | 请求体格式 |
|
||
| Accept | application/json | 响应体格式 |
|
||
|
||
---
|
||
|
||
## 🧩 主机（Host）相关接口
|
||
|
||
### 1. 获取所有主机列表
|
||
|
||
**接口：**
|
||
```
|
||
|
||
GET /get_all_hosts
|
||
|
||
````
|
||
|
||
**参数：**
|
||
无
|
||
|
||
**返回示例：**
|
||
```json
|
||
{"result":
|
||
[
|
||
"uuid-1",
|
||
"uuid-2",
|
||
"uuid-3"
|
||
]
|
||
}
|
||
````
|
||
---
|
||
|
||
### 2. 通过 UUID 获取主机信息
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_host_by_uuid?uuid=<uuid>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ---- | ------ | -- | ------- |
|
||
| uuid | string | ✅ | 主机 UUID |
|
||
|
||
**返回示例：(包含host的全部字段)**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"id": 1,
|
||
"uuid": "uuid-1",
|
||
"name": "HostA",
|
||
"status": 1,
|
||
"authorize_status": 1,
|
||
"created_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 通过主机 ID 获取主机信息
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_host_by_id?host_id=<id>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------- | ------- | -- | ----- |
|
||
| host_id | integer | ✅ | 主机 ID |
|
||
|
||
**返回示例：(包含host的全部字段)**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"id": 1,
|
||
"uuid": "uuid-1",
|
||
"name": "HostA",
|
||
"authorize_status": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 修改主机状态
|
||
|
||
**接口：**
|
||
|
||
```
|
||
POST /change_host_status
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"uuid": "uuid-1",
|
||
"new_status": 1
|
||
}
|
||
```
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": "ok"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取主机下的设备列表
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_host_devices?host_id=<id>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------- | ------- | -- | ----- |
|
||
| host_id | integer | ✅ | 主机 ID |
|
||
|
||
**返回示例：(包含device的全部字段)**
|
||
|
||
```json
|
||
{
|
||
"result": [
|
||
{ "device_uuid": "dev-1", "status": 1 },
|
||
{ "device_uuid": "dev-2", "status": 0 }
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 设备（Device）相关接口
|
||
|
||
### 6. 获取设备详情
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_device_by_uuid?device_uuid=<uuid>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ----------- | ------ | -- | ------- |
|
||
| device_uuid | string | ✅ | 设备 UUID |
|
||
|
||
**返回示例：(包含device的全部字段)**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"device_uuid": "dev-1",
|
||
"type": "sensor",
|
||
"status": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 修改设备状态
|
||
|
||
**接口：**
|
||
|
||
```
|
||
POST /change_device_status
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"device_uuid": "dev-1",
|
||
"new_status": 1
|
||
}
|
||
```
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": "ok"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🌐 Endpoint（数据终端）相关接口
|
||
|
||
### 8. 获取所有 Endpoint
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_all_endpoints
|
||
```
|
||
|
||
**参数：** 无
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": [
|
||
{
|
||
"id": 1,
|
||
"name": "mqtt_endpoint_1",
|
||
"title": "MQTT 接入节点",
|
||
"type": "mqtt",
|
||
"status": 1,
|
||
"creator": 1,
|
||
"created_at": "2024-01-01T00:00:00Z",
|
||
"updated_at": "2024-05-01T12:00:00Z",
|
||
"config": {
|
||
"host": "mqtt.broker.local",
|
||
"port": 1883,
|
||
"client_id": "iot-client-1",
|
||
"username": "iot_user",
|
||
"password": "123456",
|
||
"topic": "iot/device/data",
|
||
"qos": 1
|
||
}
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "http_endpoint_1",
|
||
"title": "HTTP 推送接口",
|
||
"type": "http",
|
||
"status": 1,
|
||
"creator": 2,
|
||
"created_at": "2024-02-15T10:00:00Z",
|
||
"updated_at": "2024-04-01T09:30:00Z",
|
||
"config": {
|
||
"url": "https://webhook.example.com/data",
|
||
"pool_size": 10
|
||
}
|
||
},
|
||
{
|
||
"id": 3,
|
||
"name": "kafka_endpoint_auth",
|
||
"title": "Kafka 接入（认证）",
|
||
"type": "kafka",
|
||
"status": 1,
|
||
"creator": 3,
|
||
"created_at": "2024-03-10T08:00:00Z",
|
||
"updated_at": "2024-06-20T09:00:00Z",
|
||
"config": {
|
||
"bootstrap_servers": [
|
||
"kafka1:9092",
|
||
"kafka2:9092"
|
||
],
|
||
"topic": "iot_topic",
|
||
"sasl_config": {
|
||
"username": "user_a",
|
||
"password": "p@ssw0rd",
|
||
"mechanism": "sha_256"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"id": 4,
|
||
"name": "kafka_endpoint_noauth",
|
||
"title": "Kafka 接入（无认证）",
|
||
"type": "kafka",
|
||
"status": 1,
|
||
"creator": 3,
|
||
"created_at": "2024-03-15T09:30:00Z",
|
||
"updated_at": "2024-06-25T10:15:00Z",
|
||
"config": {
|
||
"bootstrap_servers": [
|
||
"kafka1:9092"
|
||
],
|
||
"topic": "iot_noauth_topic"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
|
||
```
|
||
|
||
---
|
||
|
||
### 9. 获取指定 Endpoint 信息
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_endpoint?id=<id>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | ------- | -- | ----------- |
|
||
| id | integer | ✅ | Endpoint ID |
|
||
|
||
**返回示例：()**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"id": 1,
|
||
"name": "mqtt_endpoint",
|
||
"title": "MQTT接口",
|
||
"type": "mqtt",
|
||
"config_json": {
|
||
"id": 2,
|
||
"name": "http_endpoint_1",
|
||
"title": "HTTP 推送接口",
|
||
"type": "http",
|
||
"status": 1,
|
||
"creator": 2,
|
||
"created_at": "2024-02-15T10:00:00Z",
|
||
"updated_at": "2024-04-01T09:30:00Z",
|
||
"config": {
|
||
"url": "https://webhook.example.com/data",
|
||
"pool_size": 10
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🧱 Endpoint 配置结构说明
|
||
|
||
根据 `type` 不同，`config_json` 结构如下：
|
||
|
||
### MQTT
|
||
|
||
```json
|
||
{
|
||
"host": "broker.example.com",
|
||
"port": 1883,
|
||
"client_id": "client-1",
|
||
"username": "user",
|
||
"password": "pass",
|
||
"topic": "iot/topic",
|
||
"qos": 1
|
||
}
|
||
```
|
||
|
||
### HTTP
|
||
|
||
```json
|
||
{
|
||
"url": "https://api.example.com",
|
||
"pool_size": 5
|
||
}
|
||
```
|
||
|
||
### Kafka（带认证）
|
||
|
||
```json
|
||
{
|
||
"bootstrap_servers": ["kafka1:9092", "kafka2:9092"],
|
||
"topic": "iot_topic",
|
||
"sasl_config": {
|
||
"username": "user",
|
||
"password": "pass",
|
||
"mechanism": "sha_512"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Kafka（无认证）
|
||
|
||
```json
|
||
{
|
||
"bootstrap_servers": ["kafka1:9092"],
|
||
"topic": "iot_topic"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 错误响应格式
|
||
|
||
统一错误返回结构：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": 400,
|
||
"message": "Invalid parameter"
|
||
}
|
||
}
|
||
``` |