查询设备实时状态

查询单台设备的最新状态。服务端会主动向设备发起刷新；若设备当前离线，则返回该设备最后一次在线时的状态。

该接口适合用户显式点击"刷新"时调用。批量列表、首页概览、后台轮询请优先使用 查询设备列表。

限流

维度	规则	触发后行为
同一设备实时刷新	10 秒内最多 1 次	返回 429 RATE_LIMITED，并带 Retry-After

端点

GET /wlte/v1/devices/{deviceId}

权限要求

Scope	必须	说明
device:read	是	查询单个设备实时状态

请求

完整地址：

GET {baseUrl}/wlte/v1/devices/{deviceId}

请求头：

Authorization: Bearer {accessToken}
Accept: application/json

路径参数：

参数	类型	必填	规则
deviceId	string	是	不能为空

成功响应

HTTP 状态码：

200 OK

响应体：

{
  "code": "SUCCESS",
  "message": "OK.",
  "requestId": "req_001",
  "data": {
    "deviceId": "abc123456789",
    "name": "YourDeviceName",
    "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"
  }
}

返回规则

• 设备在线时，返回本次刷新后的最新状态
• 设备离线时，返回该设备最后一次在线时的状态；status 为 OFFLINE，stateUpdatedAt 反映最后更新时间
• 同一个传感器接口可能返回多个类型的读数，例如同一 index 同时返回温度和湿度。客户端应使用 index + type 识别一条传感器读数

响应 data 结构

字段	类型	必填	说明
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

补充说明：

• 当 deviceType 返回 UNSUPPORTED 时，表示该设备当前还没有可用的 OpenAPI 设备类型定义，暂不能按标准能力模型接入

错误响应

可能返回：

• 400 INVALID_REQUEST
• 401 AUTH_REQUIRED
• 401 AUTH_INVALID
• 401 AUTH_EXPIRED
• 403 AUTH_SCOPE_DENIED
• 404 DEVICE_NOT_FOUND
• 429 RATE_LIMITED
• 503 GATEWAY_UNAVAILABLE
• 504 DEVICE_TIMEOUT

429 RATE_LIMITED 响应体

触发限流时，响应体会携带 data 字段，同时返回 Retry-After 响应头：

{
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "requestId": "req_001",
  "data": {
    "retryAfterSeconds": 10
  }
}

retryAfterSeconds 与 Retry-After 响应头的值相同，单位为秒。