订阅消息通道

本页目标

通过消费组轮询拉取设备事件（适合可容忍延迟、希望自主控流的场景）。与推送对比见 接收设备事件。

消息通道供开发者主动拉取平台实时消息，需自行轮询消费，与平台主动推送互为补充。

消息在通道中最多保留 2 天。消息中图片的有效期为 7 天，需长期保存请自行转存。msgBody 与消息推送载荷一致，可按 msgType 复用解析逻辑，类型见 事件消息类型定义，消息体见 事件消息格式定义。

HTTP 参数、示例与错误码见 pullMessages、commitOffset。

步骤

申请

提交 技术工单 或通过 问题解决渠道 申请开通账号的消息通道订阅功能权限，约 5 分钟后生效。权限开通后，新产生的消息会进入消息通道。

事件消息对接 写的是：先申请开通消息通道权限，或通过联系我们做项目咨询；审批通过后再按教程对接。

消费组

教程的约束：

• 消费组固定 3 个：group1 / group2 / group3，数据相同、偏移量独立。
• 同一 appId + group 同时仅允许一个拉取或提交请求。
• 单次最大 500 条。
• 每个 appId + group 建议单实例、单线程消费。

每个消费组最多 3 个消费者实例，须自行管理生命周期（与 事件消息对接 对比表一致）。

偏移量

教程中的消费流程：

1. 获取 accessToken，见 首次接口调用 与 token。
2. 循环调用 pullMessages，处理返回的 messages。
3. autoCommit=true：本次 pullMessages 成功后，服务端立即提交本轮位点，无需再调 commitOffset。位点在 pull 返回后即已推进，与业务是否处理完成无关。须异步处理，并接受 at-most-once。处理失败可能丢消息。教程写此模式用于联调、快速验证。
4. autoCommit=false：位点进入 pending，业务处理成功后调用 commitOffset。教程写生产环境推荐此模式。无 pending 位点时调用 commitOffset 返回 MC1003。
5. 若 hasMore=true，间隔不少于 1 秒继续拉取。

用 msgId 做幂等去重。字段说明见 pullMessages 响应表。

响应里与消费有关的字段，说明为：messages（含 msgId、msgType、msgBody）、count（本次条数）、hasMore（是否可能仍有更多消息）、offsetReset（是否因超过 2 天保留期触发位点重置，部分历史消息可能丢失）。

pullMessages 请求中 autoCommit 为 JSON 布尔（勿写成字符串 "false"）：

{
  "params": {
    "token": "<accessToken>",
    "group": "group1",
    "limit": 500,
    "autoCommit": false
  }
}

积压恢复

说明到的恢复相关事实：

• 消息在通道中保留 2 天。选型建议写：自身服务短暂故障时，重启后也能从通道中拉到积压的消息。见 事件消息对接。
• hasMore=false 且 count=0 表示已追上最新。
• offsetReset=true：消息超过 2 天保留期被清理，位点已重置。

通道不支持按消息 ID 回拨位点；超过 2 天保留期会 offsetReset。错误码 OP1026、MC1001–MC1003 见 pullMessages 与 排障。

各端实现

相关参考

• 消息通道订阅（拉取模式）
• 事件消息对接
• 事件消息类型定义
• 事件消息格式定义
• 配置平台消息推送
• 获取与解密告警图片
• 排障：收不到推送、重复、延迟

完整 HTTP 请求体格式、响应表与 SDK Demo 步骤见 pullMessages、commitOffset。