业务系统通常需要什么
业务系统接入摄像头网关时，通常不希望直接处理每个摄像头的差异。更常见的需求是读取设备和通道列表、获取浏览器播放地址、查看在线状态、查询录像索引、接收通道变化或告警事件，并把这些能力嵌入自己的业务页面。
StreamGate 的 Public API 仅向有效专业版和企业版授权开放。标准版和未导入授权的免费状态均不提供 API Token、Public API 路由或运行时 OpenAPI 描述。专业版可按设备、通道、运行状态、播放地址、录像、告警、GB28181 和集成分别签发最小权限 scope。
StreamGate 当前公开专业版的管理接口覆盖设备增删改与 ONVIF 发现、通道配置和按需/常驻切换、云台控制、录像任务与策略、GB28181 平台/目录发布/上联，以及 WebHook、MQTT 和投递日志。设备、通道、录像、国标和集成分别使用独立的读取或写入 scope，业务系统不需要为单项操作持有全部权限。系统设置、账号、授权、升级和服务控制不属于 Public API；智能分析接口需另行具备相应能力授权。
播放地址接口通过 quality 参数区分 high 与 fluent。业务页面可让多窗口默认请求 fluent，放大后再请求 high；未配置流畅源时，响应会明确返回可用性或回退信息。浏览器直接访问接口时，允许的来源在 StreamGate 系统设置中维护；生产环境仍应使用最小权限 Token，并由业务服务端保管管理凭据。
从只读查询开始
在控制台的接口设置中创建 Token，只勾选业务所需的只读范围。由业务服务器保存 Token 并发起请求，不把管理 Token 写入公开网页、播放地址或日志。分别验证有效请求、缺少 scope、Token 停用和授权失效的结果；基础只读不包含设备凭据、录像文件路径、下载或写控制权限。
需要把编解码、采集或播放嵌入自己的程序时，选择 StreamCore SDK；调用独立部署的 StreamGate API 不需要另购 SDK。两种产品的应用身份授权与网关部署授权不能互相替代。
WebHook 和 MQTT 适合什么
OpenAPI 更适合主动查询和管理操作，WebHook 适合把事件推送到业务系统，MQTT 适合已有消息总线或设备平台。具体使用哪种方式，取决于客户系统的架构、网络边界、权限模型和运维习惯。
正式项目中，建议以少量真实设备验证播放地址、通道状态和事件通知，再扩展到更多设备和业务流程。
事件接收与重试
专业集成接收方应按稳定事件标识处理重复消息，并保存事件时间、通道标识和处理结果。HTTP 接收方应在完成可靠保存后再确认成功；网络失败和重试不能重复触发同一业务动作。
分析候选通知、模型复核建议与人工确认的告警是不同状态。按业务需要订阅和筛选，不把候选到达或模型返回建议当作正式告警。联调时分别验证正常投递、接收方失败、重复消息和服务重启后的恢复，再扩大业务范围。