本文介绍调用视频直播 OpenAPI 时的常见易错点。
查询类 API 返回数据为空,如何排查?
DescribeLiveUserStreamMetricData 等查询类接口的 StartTime/EndTime 参数必须使用 UTC 时间(北京时间减 8 小时),格式如 2026-07-01T16:00:00Z。使用北京时间或格式错误会导致返回结果为空。请同时确认查询的域名、时间范围内确实存在业务数据。
换算示例:查询北京时间 2026-07-02 全天数据,应填写 StartTime=2026-07-01T16:00:00Z、EndTime=2026-07-02T15:59:59Z。若直接填写 2026-07-02T00:00:00Z 至 2026-07-02T23:59:59Z,实际查询的是北京时间 07-02 08:00 至 07-03 07:59,与预期时段不符。
其他注意点:域名、AppName、StreamName 需与实际推流完全匹配(区分大小写);监控数据存在 5~10 分钟延迟,刚结束的时段可能暂无数据。
直播预热任务不生效,有什么限制?
调用 SetLiveStreamPreloadTasks 配置直播预热时请注意:单次最多提交 100 个 URL;预热仅支持 RTMP、FLV 协议的播流地址,不支持 HLS(M3U8)地址,提交 M3U8 地址不会生效。
查询消息组在线人数不返回 OnlineUserCounts?
DescribeLiveMessageGroup 仅在群组存在时返回 OnlineUserCounts 字段:群组内无用户时返回 0;所有用户退群后群组不再存在,该字段不返回。建议业务侧对字段缺失情况做好兼容处理。
调用 API 报 AccessPolicyDenied 或跨账号查询失败?
使用 AK/SK 调用接口报 AccessPolicyDenied,通常是账号配置了 IP 访问控制策略,请求来源 IP 不在允许范围内,请调整访问控制策略。另外,不支持跨账号查询域名详情等资源信息,请使用资源所属账号操作或提交工单。
阿里云直播支持哪些推流协议?不支持哪些?
推流支持 RTMP、ARTC、SRT 三种协议,不支持 RTSP、GB28181。使用说明:
-
SRT 推流需先在控制台开启协议开关,并使用地址生成器生成推流地址。
-
WHIP 推流内置 NAT 穿透能力,无需手动配置 STUN/TURN 服务,需放行 UDP 1106 与 443 端口。
-
RTSP、GB28181 等协议的设备接入,需先经业务侧转协议为 RTMP/SRT 后再推流。
拉流转推接口报 400,源地址参数怎么传?
AddLiveStreamTranscode 类拉流转推接口的源地址参数(如 SourceUrls)需按数组格式提交,例如 ["rtmp://example.com/app/stream"]。以下写法均会返回 400 参数错误:直接传字符串;写成 ["SourceUrls.1"] 这类形如索引的占位字符串;数组未做序列化。使用 SDK 时直接传入字符串数组对象,使用 API 探索时按数组类型填写即可。
能否通过接口获取正在拉流的观众真实 IP 地址?
不支持。在线人数类接口(如 DescribeLiveStreamOnlineUserNum)返回的是聚合后的统计数据;且拉流请求经内容分发网络转发,接口侧可见的是边缘节点地址而非观众真实地址。
替代方案:开启日志推送或下载访问日志后,由业务侧自行分析日志中的客户端 IP;若需按用户维度统计,建议在播放地址中携带业务自定义参数,在业务服务端统计。