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

返回示例：(包含host的全部字段)

{
  "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的全部字段)

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

---

4. 修改主机状态

接口：

POST /change_host_status

请求体：

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

返回示例：

{
  "result": "ok"
}

---

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

接口：

GET /get_host_devices?host_id=<id>

参数：

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

返回示例：(包含device的全部字段)

{
  "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的全部字段)

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

---

7. 修改设备状态

接口：

POST /change_device_status

请求体：

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

返回示例：

{
  "result": "ok"
}

---

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

8. 获取所有 Endpoint

接口：

GET /get_all_endpoints

参数： 无

返回示例：

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

返回示例：()

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

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