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

规范

请求主题

规则

请求主题的格式遵循 device/{deviceNo}/webrtc/{topic}/{version}；其中信令主题为特例——不含 {topic} 段，直接为 device/{deviceNo}/webrtc/v1：

TIP
  • {deviceNo} 为设备编号。
  • {topic} 为业务主题：telemetry、retrieve、deliver。信令主题（device/{deviceNo}/webrtc/v1）无此段，业务由请求结构中的 sub 区分。
  • {version} 为 API 版本号，目前为 v1。

族与方向

请求主题 方向 业务（sub 取值）
device/{deviceNo}/webrtc/v1 信令主题：平台发布、设备订阅 信令：ping、pong、call、sdp、candidate、media、bye，经 reply 回包
device/{deviceNo}/webrtc/telemetry/v1 设备发布（publish-only） 遥测上报：status，无回包
device/{deviceNo}/webrtc/retrieve/v1 设备发布 数据检索：retrieve，经 reply 回包
device/{deviceNo}/webrtc/deliver/v1 服务器下发、设备订阅 检索结果下发：deliver（常作为 retrieve 的 reply 落点）

示例

例如，device/asr-1/webrtc/v1 就是一个符合规则的信令主题示例；device/asr-1/webrtc/telemetry/v1 是一个含业务主题段的示例。

请求结构 (Api request)

规则

  • sub：子主题，仅在双向通信较为复杂的场景下使用，其他场景无需填写。其作用是在主题相同的情况下对不同业务进行区分；本域各主题的 sub 取值见上方族与方向表，信令主题的逐子命令形状见下方「信令子命令索引」。
  • id：会话 ID 作为唯一标识符，用于区分不同客户端，需传入 MQTT 客户端 ID。MQTT 客户端 ID 的生成规则如下：
    • 设备 WebRTC 服务：device,{deviceNo},webrtc,{sessionId}
    • 设备管理服务：device,{deviceNo},iot,{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": "ping",
3  "id": "user,admin,web,session-id-xxx",
4  "token": "token-xxx",
5  "reply": "user/user001/abcdefg/webrtc/v1"
6}

响应主题

规则

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

TIP

reply 字段仅用于需要多次双向通信的场景，例如 WebRTC 通信——本族信令主题（device/{deviceNo}/webrtc/v1）即属此类：房态探询、SDP 交换与 ICE 候选交换在同一主题上多轮往复，接入方应按回包 sub 逐轮处理，直到通话以 bye 结束。

示例

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

响应结构 (Api response)

规则

  • sub：业务子命令回显——本域响应信封携带 sub，回显本次请求的业务子命令。信令应答中 ping 的回包取 pong（配对子命令，非同值回显）。与中心服务域「响应不回显 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": "pong",
3  "id": "device,asr-1,webrtc",
4  "status": 200,
5  "data": {
6    "status": "idle",
7    "id": "",
8    "room": 0,
9    "feed": 0,
10    "session_id": 0,
11    "handle_id": 0
12  }
13}

信令子命令索引与多轮通信

信令子命令（sub）索引

信令主题 device/{deviceNo}/webrtc/v1 的 7 个信令子命令——逐子命令的传参与回包形状见本服务契约 v1-signaling.yaml（经本服务「清单」页的 Swagger 视图查阅）：

sub 方向与用途 载荷要点
ping 平台发布：房态探询 设备以 pong 回包，data 携房态
pong 设备应答 ping 的回包子命令 房态字段：status、id、room、feed、session_id、handle_id
call 平台发布：发起通话 房态为 idle 时可发送；无契约化传参
sdp 双向：SDP 交换 设备 offer 回包走 data；客户端应答走 params
candidate 双向：ICE 候选交换 载荷 {candidate, sdpMid, sdpMLineIndex, usernameFragment}，两向同形状
media 平台发布：媒体控制 params 携音频、视频与播放控制；音频编码、视频编码与麦克风取值当前暂不可控
bye 平台发布：结束通话 无契约化传参

房态语义（pong）

ping 的回包 pong 携带设备当前房态，接入方按房态决定通话动作：

  • status 为 idle：设备空闲，可发送 call 发起通话；
  • status 为 p2p：设备已被点对点占用，id 为占用方标识；
  • status 为 sfu：设备处于 SFU 模式，room 为 0 表示建房中（暂不可入房），大于 0 表示房间已建立（可入房）。

retrieve 与 deliver 配对（ICE 配置）

设备向 device/{deviceNo}/webrtc/retrieve/v1 发布检索请求（正本示例 items 仅含 ice），并将 reply 指向 device/{deviceNo}/webrtc/deliver/v1；服务器将 ICE 服务器配置经 deliver 主题下发，信封 data 以检索项为键（sub 为 deliver）。

目录