实时遥测

接口说明

获取指定设备最新一次上报的遥测与状态数据。返回的数据反映设备最近一次与平台通信时的快照，字段内容因设备类型而有所差异。

本页的 REST 接口返回最近一次快照；若需持续接收实时遥测，请通过设备控制服务的 WebSocket 通道订阅 telemetry 推送（见下方「实时遥测推送」）。

请求信息

项目	内容
方法	GET
路径	`/api/devices/{id}/telemetry/latest`
服务	核心业务 API（域名见快速开始）
鉴权	是，请求头携带 `Authorization: Bearer your_token_here`

请求参数

参数名	类型	必填	说明
id	int	是	路径参数，设备 ID

本接口无额外查询参数。

请求示例

curl -X GET "/api/devices/101/telemetry/latest" \
  -H "Authorization: Bearer your_token_here" \
  -H "Accept: application/json"

响应参数

字段	类型	说明
code	int	状态码，0 表示成功
message	string	响应描述
data.device_id	int	设备 ID
data.device_no	string	设备编号
data.online_status	int	在线状态：1 = 在线，0 = 离线
data.is_online	bool	是否在线
data.last_online_at	string\|null	最近上线时间，可为空
data.reported_at	string\|null	最近遥测数据上报时间，可为空
data.device_type_code	string	设备类型代码
data.status	object	设备状态值（结构因设备类型而异）
data.battery	number\|null	电量百分比（0–100），可为空
data.pose	object\|null	姿态信息（如偏航角、俯仰角等），可为空
data.location	object\|null	位置坐标信息，可为空
data.source	string\|null	数据来源标识，可为空

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "device_id": 101,
    "device_no": "DEV-2024-001",
    "online_status": 1,
    "is_online": true,
    "last_online_at": "2026-07-05 10:23:45",
    "reported_at": "2026-07-05 10:23:40",
    "device_type_code": "inspection_robot",
    "status": {
      "motion": "idle",
      "task_id": null
    },
    "battery": 87.5,
    "pose": {
      "yaw": 45.0,
      "pitch": 0.0,
      "roll": 0.2
    },
    "location": {
      "longitude": 121.473701,
      "latitude": 31.230416,
      "altitude": 5.2
    },
    "source": "mqtt"
  }
}

失败响应

{
  "code": 404,
  "message": "设备不存在",
  "data": null
}

{
  "code": 30002,
  "message": "无设备查看权限",
  "data": null
}

实时遥测推送（WebSocket）

建立设备控制服务 WebSocket 连接后，设备控制服务会主动推送 telemetry 消息，用于实时监控设备状态：

{
  "type": "telemetry",
  "device_no": "DEV-2024-001",
  "status": "standby",
  "battery": 88,
  "pose": { "x": 0.0, "y": 0.0, "yaw": 0.0 },
  "ts": 1720146600000
}

字段	类型	说明
type	string	消息类型，固定为 `telemetry`
device_no	string	设备编号
status	string	运行状态：`standby` 待机 / `moving` 运动中 / `error` 异常
battery	number	电量百分比（0–100）
pose	object	姿态与位置：`x`、`y`、`yaw`
ts	int	时间戳（毫秒）