设备管理 API 实践案例

本页面展示了移动控制台和管理后台对物联网设备实施增删改查（CRUD）操作的真实 HTTP 报文及参数示例。

---

1. 查询设备列表 (List Devices)

用于分页获取当前用户账户下的设备，支持按在线状态过滤。

• HTTP 请求:

  GET /v1/devices?page=1&per_page=2&status=online&sort=-created_at HTTP/1.1
  Host: api.example.com
  Authorization: Bearer <access_token>
  Accept: application/json

• HTTP 响应:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  X-RateLimit-Limit: 120
  X-RateLimit-Remaining: 118
  X-RateLimit-Reset: 1716000060
  
  {
    "data": [
      {
        "deviceId": "dev_f49b10a2",
        "macAddress": "00:1a:2b:3c:4d:5e",
        "deviceName": "客厅空气检测仪",
        "deviceModel": "air-monitor-v2",
        "status": "online",
        "latestTelemetry": {
          "timestamp": 1716000000000,
          "metrics": {
            "temperature": 24.5,
            "humidity": 45.0,
            "co2": 450
          }
        },
        "createdAt": 1715820000000
      },
      {
        "deviceId": "dev_3e8c9b2a",
        "macAddress": "11:2b:3c:4d:5e:6f",
        "deviceName": "卧室温湿度传感器",
        "deviceModel": "temp-sensor-v1",
        "status": "online",
        "latestTelemetry": {
          "timestamp": 1716000005000,
          "metrics": {
            "temperature": 22.1,
            "humidity": 50.5
          }
        },
        "createdAt": 1715820100000
      }
    ],
    "meta": {
      "currentPage": 1,
      "perPage": 2,
      "totalPages": 8,
      "totalItems": 15
    }
  }

---

2. 注册/绑定新设备 (Register Device)

在系统里登记新出厂的硬件，或者由用户通过扫描 MAC 二维码将其与个人账户进行绑定。

• HTTP 请求:

  POST /v1/devices HTTP/1.1
  Host: api.example.com
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {
    "macAddress": "22:3c:4d:5e:6f:7a",
    "deviceName": "厨房烟雾报警器",
    "deviceModel": "smoke-detector-v1",
    "roomId": "room_kitchen_01"
  }

• HTTP 响应:

  HTTP/1.1 201 Created
  Content-Type: application/json; charset=utf-8
  
  {
    "deviceId": "dev_8c9b2e7a",
    "macAddress": "22:3c:4d:5e:6f:7a",
    "deviceName": "厨房烟雾报警器",
    "deviceModel": "smoke-detector-v1",
    "status": "offline",
    "createdAt": 1716000032000
  }

---

3. 获取单台设备详情 (Get Device Details)

查看某台特定设备的元数据及最新遥测参数。

• HTTP 请求:

  GET /v1/devices/dev_f49b10a2 HTTP/1.1
  Host: api.example.com
  Authorization: Bearer <access_token>
  Accept: application/json

• HTTP 响应:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  
  {
    "deviceId": "dev_f49b10a2",
    "macAddress": "00:1a:2b:3c:4d:5e",
    "deviceName": "客厅空气检测仪",
    "deviceModel": "air-monitor-v2",
    "status": "online",
    "latestTelemetry": {
      "timestamp": 1716000000000,
      "metrics": {
        "temperature": 24.5,
        "humidity": 45.0,
        "co2": 450,
        "voltage": 3.6
      }
    },
    "createdAt": 1715820000000
  }

---

4. 更新设备配置属性 (Update Device Config)

下发控制指令以修改硬件运行参数，如更改数据上传的频率。

• HTTP 请求:

  PUT /v1/devices/dev_f49b10a2/config HTTP/1.1
  Host: api.example.com
  Authorization: Bearer <access_token>
  Content-Type: application/json
  
  {
    "sampleInterval": 30,
    "reportInterval": 300,
    "ecoMode": true
  }

• HTTP 响应:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  
  {
    "deviceId": "dev_f49b10a2",
    "config": {
      "sampleInterval": 30,
      "reportInterval": 300,
      "ecoMode": true
    },
    "updatedAt": 1716000045000
  }

---

5. 解绑/注销设备 (Decommission Device)

从账户中注销并永久清理指定硬件。

• HTTP 请求:

  DELETE /v1/devices/dev_f49b10a2 HTTP/1.1
  Host: api.example.com
  Authorization: Bearer <access_token>

• HTTP 响应:

  HTTP/1.1 204 No Content

---

6. 参数校验异常错误响应示例 (Validation Error)

当注册设备时，如果 MAC 地址格式不正确，网关和业务后台将校验失败并返回基于 RFC 7807 标准的错误。

• HTTP 响应:

  HTTP/1.1 422 Unprocessable Entity
  Content-Type: application/problem+json; charset=utf-8
  
  {
    "type": "https://api.example.com/errors/validation-failed",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "The provided payload has validation errors. See 'errors' field for details.",
    "instance": "/v1/devices",
    "errors": {
      "macAddress": [
        "The macAddress field format is invalid. It must be in XX:XX:XX:XX:XX:XX format."
      ]
    }
  }