396 lines
5.4 KiB
Markdown
396 lines
5.4 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 |
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"id": 1,
|
||
"uuid": "uuid-1",
|
||
"name": "HostA",
|
||
"status": 1,
|
||
"created_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 通过主机 ID 获取主机信息
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_host_by_id?host_id=<id>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------- | ------- | -- | ----- |
|
||
| host_id | integer | ✅ | 主机 ID |
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"id": 1,
|
||
"uuid": "uuid-1",
|
||
"name": "HostA"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 修改主机状态
|
||
|
||
**接口：**
|
||
|
||
```
|
||
POST /change_host_status
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"uuid": "uuid-1",
|
||
"new_status": 1
|
||
}
|
||
```
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取主机下的设备列表
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_host_devices?host_id=<id>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| ------- | ------- | -- | ----- |
|
||
| host_id | integer | ✅ | 主机 ID |
|
||
|
||
**返回示例：**
|
||
|
||
```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 |
|
||
|
||
**返回示例：**
|
||
|
||
```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": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🌐 Endpoint（数据终端）相关接口
|
||
|
||
### 8. 获取所有 Endpoint
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_all_endpoints
|
||
```
|
||
|
||
**参数：** 无
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": [
|
||
{
|
||
"id": 1,
|
||
"name": "mqtt_endpoint",
|
||
"type": "mqtt",
|
||
"status": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9. 获取指定 Endpoint 信息
|
||
|
||
**接口：**
|
||
|
||
```
|
||
GET /get_endpoint?id=<id>
|
||
```
|
||
|
||
**参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | ------- | -- | ----------- |
|
||
| id | integer | ✅ | Endpoint ID |
|
||
|
||
**返回示例：**
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"id": 1,
|
||
"name": "mqtt_endpoint",
|
||
"title": "MQTT接口",
|
||
"type": "mqtt",
|
||
"config_json": "{\"host\":\"mqtt.example.com\",\"port\":1883}"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🤖 AI 事件接口
|
||
|
||
### 10. 触发 AI 事件
|
||
|
||
**接口：**
|
||
|
||
```
|
||
POST {api_url}
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"id": 123,
|
||
"token": "<md5(API_TOKEN + id + API_TOKEN)>"
|
||
}
|
||
```
|
||
|
||
**返回：**
|
||
|
||
* 成功：HTTP 200
|
||
* 失败：返回错误日志（`lager` 记录）
|
||
|
||
**说明：**
|
||
`token` 通过以下 Erlang 表达式生成：
|
||
|
||
```erlang
|
||
iot_util:md5(<<API_TOKEN, integer_to_binary(Id), API_TOKEN>>)
|
||
```
|
||
|
||
---
|
||
|
||
## 🧱 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"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📄 附录：内部函数说明（开发者参考）
|
||
|
||
| 函数名 | 作用 | 说明 |
|
||
| ------------------- | ----------------------------- | ------------------------------------- |
|
||
| `do_get/2` | 执行 HTTP GET 请求 | 返回 `{ok, Result}` 或 `{error, Reason}` |
|
||
| `do_post/2` | 执行 HTTP POST 请求 | 自动编码 JSON，解析返回值 |
|
||
| `endpoint_record/1` | 将 JSON 转换为内部 `#endpoint{}` 结构 | 内部使用 |
|
||
| `parse_config/2` | 解析不同类型 endpoint 配置 | 支持 mqtt/http/kafka |
|
||
|
||
---
|
||
|
||
📅 **最后更新：2025-11-07**
|
||
|
||
```
|
||
|
||
---
|
||
|
||
是否希望我帮你把这份 `.md` 文件转成一个 **可浏览的 HTML 文档**（带目录与搜索功能）？
|
||
```
|