ES Documentation
手册
API
手册
API
简体中文

规范

请求主题

规则

请求主题的格式遵循 device/{deviceNo}/iot/{topic}/{version}，其中：

TIP
  • {deviceNo} 为设备编号。
  • {topic} 为业务主题：configs、telemetry、retrieve、deliver。
  • {version} 为 API 版本号，目前为 v1。

族与方向

请求主题 方向 业务（sub 取值）
device/{deviceNo}/iot/configs/v1 平台或服务器发布、设备订阅 配置管理：get、set、bcplus、dump，经 reply 回包
device/{deviceNo}/iot/telemetry/v1 设备发布（publish-only） 遥测上报：status、event、data，无回包
device/{deviceNo}/iot/retrieve/v1 设备发布 数据检索：retrieve，经 reply 回包
device/{deviceNo}/iot/deliver/v1 服务器下发、设备订阅 检索结果下发：deliver（常作为 retrieve 的 reply 落点）

示例

例如，device/asr-1/iot/configs/v1 就是一个符合规则的主题示例。

请求结构 (Api request)

规则

  • sub：子主题，仅在双向通信较为复杂的场景下使用，其他场景无需填写。其作用是在主题相同的情况下对不同业务进行区分；本域各主题的 sub 取值见上方族与方向表。
  • id：会话 ID 作为唯一标识符，用于区分不同客户端，需传入 MQTT 客户端 ID。MQTT 客户端 ID 的生成规则如下：
    • 设备管理服务：device,{deviceNo},iot,{sessionId}
    • 设备 WebRTC 服务：device,{deviceNo},webrtc,{sessionId}
    • Web 客户端程序：user,{username},web,{sessionId}
    • App 客户端程序：user,{username},app,{sessionId}
    • (采集/中心)服务器数据服务：server,{serverNo},iot,{sessionId}
    • 中心服务器设备服务：server,{serverNo},device,{sessionId}
    • 采集服务器文件服务：server,{serverNo},file,{sessionId}
  • reply: MQTT 响应消息主题路径，此为可选字段，仅在需要响应数据时才进行相应设置，响应端会通过该主题来返回相应的响应数据。这样的设计便于第三方系统进行对接，第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范。此字段的设置是为了兼容不支持 MQTT 5.0 特性的客户端（对应 MQTT 5.0 中的 Response Topic）。
  • replyNumberMax: 最大回复次数，该字段为可选字段。仅当需要回复响应数据超过 1 次时，才需进行相应设置。服务端已将范围控制在 1 - 10，若为空，默认值为 1。
  • replyInterval: 回复间隔（秒），此为可选字段。仅在需要回复响应数据超过 1 次的情况下，才需进行设置。服务端已将该字段的范围控制在 1 - 10 秒，若该字段为空，则默认值为 1 秒。
  • token: 身份认证令牌，仅用于 HTTP 接口的权限校验；MQTT 管线不读取该字段（设备侧对该字段的校验语义未验证）。
  • params: 传参，此为可选字段，仅在存在传参需求时才进行设置；具体形状随 sub 取值而定，见各主题契约。
TIP
  • {sessionId}：随机生成的标识字符串, 当前程序未退出时，该标识字符串保持不变。
  • {username}：当前登录用户名
  • {deviceNo}：设备编号
  • {serverNo}：服务器编号

示例

MQTT: message
1{
2  "sub": "get",
3  "id": "user,admin,web,session-id-xxx",
4  "token": "token-xxx",
5  "reply": "user/user001/abcdefg/iot/configs/v1",
6  "params": {
7    "structs": ["BATTERY_INFO_S"]
8  }
9}

响应主题

规则

由请求结构中的 reply 字段指定，若该字段为空，则不进行回复。reply 主题由请求方自定，第三方系统可依据自有主题规范订阅。

示例

例如，user/user001/abcdefg/iot/configs/v1 就是参考文档示例中的自定 reply 主题形态。

响应结构 (Api response)

规则

  • sub：业务子命令回显——本域响应信封携带 sub，回显本次请求的业务子命令（如 get 或 retrieve）。与中心服务域「响应不回显 sub」的口径不同，属两域各自的契约事实，解析回包时勿混域。
  • id: 响应信封中的 id 为应答方出站 MQTT 客户端 ID（固定 3 段形态，示例环境为 server,center-server-1,iot），与请求侧传入的 id 不同。
  • status: 响应状态码，其默认值为 200，该状态码能够直观地反映出请求响应的大致情况。
    • 200：成功执行请求，没有发生任何错误。
    • 400：对象验证失败：请求参数缺失、长度或格式不符等校验未通过，具体原因见 error 字段。
    • 401：身份验证失败：凭据错误、令牌无效或过期、缺少认证信息。
    • 403：拒绝访问：已认证但无权访问目标资源（权限不足）。
    • 422：业务逻辑验证失败：请求格式正确但业务条件不满足（如目标数据不存在），具体原因见 error 字段。
    • 500：服务器内部错误：界面只显示 System Error，详细错误信息记录在服务端日志。
    • 1000：消息转换失败：请求体无法解析为目标对象或响应体序列化失败（数据格式不匹配）。
    • 1001：控制器参数校验失败：表单字段缺失、超长或格式不符，具体原因见 error 字段。
  • error: 错误描述信息，此为可选字段，仅在出现异常情况时才会返回相关内容，以便使用者清晰知晓出现问题的具体缘由。
  • data: 响应数据，此为可选字段，仅在实际有数据需要返回时，才会呈现相应的内容。
  • replyNumber: 回复数量，与请求结构中的 replyNumberMax 相对应，用于表明本次请求的回复次数。

示例

MQTT: message
1{
2  "sub": "retrieve",
3  "id": "server,center-server-1,iot",
4  "status": 200,
5  "data": {
6    "ice": [
7      { "urls": "stun:example.invalid:3478" },
8      { "urls": "turn:example.invalid:3478", "username": "xxx", "credential": "xxx" }
9    ]
10  }
11}

遥测上报节律与检索配对

telemetry 采集与上报节律

  • 电量：变化即采集，上报 1 条；
  • GPS：有效定位按 15 秒累积上报；
  • 磁盘容量：变化即采集，上报 1 条；
  • 统一上报间隔 5 分钟（按业务需求定）。

sub 为 status 时状态变化即时报；sub 为 event 时上报事件（time 为数字）；sub 为 data 时按 time 字符串键分组批量上报历史数据（两类时间类型不一致，照录参考文档形状）。

retrieve 与 deliver 配对

设备向 device/{deviceNo}/iot/retrieve/v1 发布检索请求（params.items 指定检索项），并将 reply 指向 device/{deviceNo}/iot/deliver/v1；服务器将检索结果经 deliver 主题下发，信封 data 以检索项为键（sub 为 deliver）。

目录