iot_cloud/docs/iot_api.md

```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

参数： 无

返回示例：

{"result":
    [
      "uuid-1",
      "uuid-2",
      "uuid-3"
    ]
}

---

2. 通过 UUID 获取主机信息

接口：

GET /get_host_by_uuid?uuid=<uuid>

参数：

参数名	类型	必填	说明
uuid	string	✅	主机 UUID

返回示例：

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

返回示例：

{
  "result": {
    "id": 1,
    "uuid": "uuid-1",
    "name": "HostA"
  }
}

---

4. 修改主机状态

接口：

POST /change_host_status

请求体：

{
  "uuid": "uuid-1",
  "new_status": 1
}

返回示例：

{
  "result": 1
}

---

5. 获取主机下的设备列表

接口：

GET /get_host_devices?host_id=<id>

参数：

参数名	类型	必填	说明
host_id	integer	✅	主机 ID

返回示例：

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

返回示例：

{
  "result": {
    "device_uuid": "dev-1",
    "type": "sensor",
    "status": 1
  }
}

---

7. 修改设备状态

接口：

POST /change_device_status

请求体：

{
  "device_uuid": "dev-1",
  "new_status": 1
}

返回示例：

{
  "result": 1
}

---

🌐 Endpoint（数据终端）相关接口

8. 获取所有 Endpoint

接口：

GET /get_all_endpoints

参数： 无

返回示例：

{
  "result": [
    {
      "id": 1,
      "name": "mqtt_endpoint",
      "type": "mqtt",
      "status": 1
    }
  ]
}

---

9. 获取指定 Endpoint 信息

接口：

GET /get_endpoint?id=<id>

参数：

参数名	类型	必填	说明
id	integer	✅	Endpoint ID

返回示例：

{
  "result": {
    "id": 1,
    "name": "mqtt_endpoint",
    "title": "MQTT接口",
    "type": "mqtt",
    "config_json": "{\"host\":\"mqtt.example.com\",\"port\":1883}"
  }
}

---

🤖 AI 事件接口

10. 触发 AI 事件

接口：

POST {api_url}

请求体：

{
  "id": 123,
  "token": "<md5(API_TOKEN + id + API_TOKEN)>"
}

返回：

• 成功：HTTP 200
• 失败：返回错误日志（lager 记录）

说明： token 通过以下 Erlang 表达式生成：

iot_util:md5(<<API_TOKEN, integer_to_binary(Id), API_TOKEN>>)

---

🧱 Endpoint 配置结构说明

根据 type 不同，config_json 结构如下：

MQTT

{
  "host": "broker.example.com",
  "port": 1883,
  "client_id": "client-1",
  "username": "user",
  "password": "pass",
  "topic": "iot/topic",
  "qos": 1
}

HTTP

{
  "url": "https://api.example.com",
  "pool_size": 5
}

Kafka（带认证）

{
  "bootstrap_servers": ["kafka1:9092", "kafka2:9092"],
  "topic": "iot_topic",
  "sasl_config": {
    "username": "user",
    "password": "pass",
    "mechanism": "sha_512"
  }
}

Kafka（无认证）

{
  "bootstrap_servers": ["kafka1:9092"],
  "topic": "iot_topic"
}

---

⚠️ 错误响应格式

统一错误返回结构：

{
  "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 文档**（带目录与搜索功能）？