查询设备列表

分页查询当前账号可访问的所有设备，返回每台设备的基本信息和当前状态。

适合设备概览、看板展示、批量列表和后台同步场景。如需获取单台设备的最新状态，请调用 查询设备详情。

端点

GET /wlte/v1/devices

权限要求

Scope	必须	说明
device:read	是	查询当前账号可访问的设备列表

请求

完整地址：

GET {baseUrl}/wlte/v1/devices

请求头：

Authorization: Bearer {accessToken}
Accept: application/json

查询参数：

参数	类型	必填	规则
page	integer	否	默认 1，最小值 1
pageSize	integer	否	默认 20，范围 1 到 100

分页字段说明见 分页规则。

成功响应

HTTP 状态码：

200 OK

响应体：

{
  "code": "SUCCESS",
  "message": "OK.",
  "requestId": "req_001",
  "data": {
    "devices": [
      {
        "deviceId": "abc123456789",
        "name": "YourDeviceName-A",
        "deviceType": "SM4_T_TH",
        "status": "ONLINE",
        "peripherals": {
          "relays": [
            {
              "index": 1,
              "on": false
            },
            {
              "index": 2,
              "on": false
            },
            {
              "index": 3,
              "on": true
            },
            {
              "index": 4,
              "on": false
            }
          ],
          "digitalInputs": [
            {
              "index": 1,
              "active": false
            },
            {
              "index": 2,
              "active": false
            },
            {
              "index": 3,
              "active": false
            },
            {
              "index": 4,
              "active": false
            }
          ],
          "sensors": [
            {
              "index": 1,
              "type": "TEMP",
              "value": 30.4,
              "unit": "C",
              "status": "ONLINE"
            },
            {
              "index": 2,
              "type": "TEMP",
              "value": 32.6,
              "unit": "C",
              "status": "ONLINE"
            },
            {
              "index": 2,
              "type": "HUMI",
              "value": 54,
              "unit": "%",
              "status": "ONLINE"
            }
          ]
        },
        "stateUpdatedAt": "2026-04-29T10:28:45.258Z"
      },
      {
        "deviceId": "xyz987654321",
        "name": "YourDeviceName-B",
        "deviceType": "UNSUPPORTED",
        "status": "OFFLINE",
        "stateUpdatedAt": "2026-04-29T09:12:03.011Z"
      }
    ],
    "stats": {
      "total": 2,
      "online": 1,
      "offline": 1
    },
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 2,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

列表项规则

• 默认按 deviceId 升序排列，当前版本不支持排序参数
• deviceType 是稳定的设备能力类型码
• stats 统计的是当前授权设备范围，不是当前页数量
• 当 deviceType 返回 UNSUPPORTED 时，表示该设备当前还没有可用的 OpenAPI 设备类型定义，暂不能按标准能力模型接入
• 同一个传感器接口可能返回多个类型的读数，例如同一 index 同时返回温度和湿度。客户端应使用 index + type 识别一条传感器读数

响应 data 结构

字段	类型	必填	说明
devices	array<Device>	是	当前页设备列表，空页返回 []
stats	object	是	当前授权设备范围内的状态统计
stats.total	integer	是	当前设备总数
stats.online	integer	是	当前在线设备数
stats.offline	integer	是	当前离线设备数
pagination	object	是	分页信息，字段说明见 分页规则
pagination.page	integer	是	当前页码，从 1 开始
pagination.pageSize	integer	是	当前页大小
pagination.total	integer	是	当前查询条件下的结果总条目数
pagination.totalPages	integer	是	总页数，ceil(total / pageSize)，最小为 1
pagination.hasNext	boolean	是	是否存在下一页
pagination.hasPrev	boolean	是	是否存在上一页

Device 结构

字段	类型	必填	说明
deviceId	string	是	设备唯一标识
name	string	是	设备展示名称
deviceType	string	是	设备能力类型码，用于标识设备的能力特征
status	string	是	设备在线状态，枚举：ONLINE、OFFLINE
peripherals	object	否	设备当前外设状态
peripherals.relays	array<RelayState>	否	继电器状态列表。参见 继电器输出
peripherals.digitalInputs	array<DigitalInputState>	否	数字输入状态列表。参见 数字输入
peripherals.sensors	array<SensorState>	否	传感器读数列表。参见 传感器读数
peripherals.analogInputs	array<AnalogInputState>	否	模拟量读数列表。参见 模拟量读数
stateUpdatedAt	string	是	设备状态更新时间，RFC3339 UTC

错误响应

可能返回：

• 400 INVALID_REQUEST
• 401 AUTH_REQUIRED
• 401 AUTH_INVALID
• 401 AUTH_EXPIRED
• 403 AUTH_SCOPE_DENIED
• 429 RATE_LIMITED
• 500 INTERNAL_ERROR