规范#

请求主题#

规则#

请求主题的格式遵循 server/{serverNo}/{serviceName}/{version}/{topicSuffix}，其中：

示例#

例如，server/center-server/iot/v1/list-online-status 就是一个符合规则的请求主题示例。

请求结构 (Api request)#

规则#

• sub：子主题，仅在双向通信较为复杂的场景下使用，其他场景无需填写。其作用是在主题相同的情况下对不同业务进行区分。
• id：会话 ID 作为唯一标识符，用于区分不同客户端，需传入 MQTT 客户端 ID。MQTT 客户端 ID 的生成规则如下：
  • Web 客户端程序：user,{username},web,{sessionId}
  • App 客户端程序：user,{username},app,{sessionId}
  • 设备管理服务：device,{deviceNo},iot,{sessionId}
  • 设备 WebRTC 服务：device,{deviceNo},webrtc,{sessionId}
  • 采集服务器文件服务：server,{serverNo},file,{sessionId}
  • 中心或采集服务器数据服务：server,{serverNo},iot,{sessionId}
  • 中心服务器设备服务：server,{serverNo},device,{sessionId}
• reply: MQTT 响应消息主题路径，此为可选字段，仅在需要响应数据时才进行相应设置，响应端会通过该主题来返回相应的响应数据。这样的设计便于第三方系统进行对接，第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范。此字段的设置是为了兼容不支持 MQTT 5.0 特性的客户端（对应 MQTT 5.0 中的 Response Topic）。
• replyNumberMax: 最大回复次数，该字段为可选字段。仅当需要回复响应数据超过 1 次时，才需进行相应设置。服务端已将范围控制在 1 - 10，若为空，默认值为 1。
• replyInterval: 回复间隔（秒），此为可选字段。仅在需要回复响应数据超过 1 次的情况下，才需进行设置。服务端已将该字段的范围控制在 1 - 10 秒，若该字段为空，则默认值为 1 秒。
• token: 身份认证令牌，专门用于接口权限的校验工作，以此确保接口使用的合法性与安全性。
• params: 传参，此为可选字段，仅在存在传参需求时才进行相应设置。

示例#

1{
2  "id": "user,admin,web,session-id-xxx",
3  "token": "token-xxx",
4  "reply": "user/admin/web/session-id-xxx/rx/resp/server/center-server/iot/v1/list-online-status",
5  "params": {
6    "mqttClientIdPrefixes": [
7      "user,admin,web",
8      "user,admin,app",
9      "device,asr-1,webrtc",
10      "device,asr-1,iot",
11      "server,center,iot",
12      "server,center,file"
13    ]
14  }
15}

响应主题#

规则#

由请求结构中的 reply 字段指定，若该字段为空，则不进行回复。

示例#

例如，user/admin/web/session-id-xxx/rx/resp/server/center-server/iot/v1/list-online-status , 第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范

响应结构 (Api response)#

规则#

• sub：子主题，仅在双向通信较为复杂的场景下使用，其他场景无需填写。其作用是在主题相同的情况下对不同业务进行区分。
• id：会话 ID 作为唯一标识符，用于区分不同客户端，需传入 MQTT 客户端 ID。MQTT 客户端 ID 的生成规则如下：
  • Web 客户端程序：user,{username},web,{sessionId}
  • App 客户端程序：user,{username},app,{sessionId}
  • 设备管理服务：device,{deviceNo},iot,{sessionId}
  • 设备 WebRTC 服务：device,{deviceNo},webrtc,{sessionId}
  • 中心或采集服务器数据服务：server,{serverNo},iot,{sessionId}
  • 中心服务器设备服务：server,{serverNo},device,{sessionId}
  • 采集服务器文件服务：server,{serverNo},file,{sessionId}
• reply: MQTT 响应消息主题路径，此为可选字段，仅在需要响应数据时才进行相应设置，响应端会通过该主题来返回相应的响应数据。这样的设计便于第三方系统进行对接，第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范。此字段的设置是为了兼容不支持 MQTT 5.0 特性的客户端（对应 MQTT 5.0 中的 Response Topic）。
• status: 响应状态码，其默认值为 200，该状态码能够直观地反映出请求响应的大致情况。
  • : 成功执行请求，没有发生任何错误。
  • : 对象验证失败：请求参数缺失、长度或格式不符等校验未通过，具体原因见 error 字段。
  • : 身份验证失败：凭据错误、令牌无效或过期、缺少认证信息。
  • : 拒绝访问：已认证但无权访问目标资源（权限不足）。
  • : 业务逻辑验证失败：请求格式正确但业务条件不满足（如目标数据不存在），具体原因见 error 字段。
  • : 服务器内部错误：界面只显示 System Error，详细错误信息记录在服务端日志。
  • : 消息转换失败：请求体无法解析为目标对象或响应体序列化失败（数据格式不匹配）。
  • : 控制器参数校验失败：表单字段缺失、超长或格式不符，具体原因见 error 字段。
• error: 错误描述信息，此为可选字段，仅在出现异常情况时才会返回相关内容，以便使用者清晰知晓出现问题的具体缘由。
• data: 响应数据，此为可选字段，仅在实际有数据需要返回时，才会呈现相应的内容。
• replyNumber: 回复数量，与请求结构中的 replyNumberMax 相对应，用于表明本次请求的回复次数。

示例#

1{
2  "id": "server,center,iot,session-id-xxx",
3  "status": 200,
4  "data": [
5    {
6      "mqttClientIdPrefix": "user,admin,web",
7      "onlineStatus": true
8    }
9  ]
10}