集成最佳实践
声网建议你在参考 API 文档集成输入在线媒体流服务后,依据本文进行检查,以保障输入在线媒体流服务的可靠性。
确保开通服务
开始使用输入在线媒体流 RESTful API 前,你需要满足以下条件:
检查服务配额
最大并发数
PCW 限制与你使用输入在线媒体流服务处理的视频流分辨率和所在地区有关,详见下表:
- 中国大陆
- 除中国大陆之外的亚太地区
- 北美
- 欧洲
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 20 | 10 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 20 | 5 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 10 | 5 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 10 | 5 |
拉流分辨率和路数限制
声网支持往频道内拉流的视频属性上限为:分辨率 1920 × 1080,帧率 30 fps。
声网支持往频道内拉流的最大流路数详见下表:
- 中国大陆
- 除中国大陆之外的亚太地区
- 北美
- 欧洲
标清 SD (≤ 640 × 360) | 高清 HD(≤ 1280 × 720) | 全高清 FHD(≤ 1920 × 1080) |
---|---|---|
20 | 20 | 10 |
标清 SD (≤ 640 × 360) | 高清 HD(≤ 1280 × 720) | 全高清 FHD(≤ 1920 × 1080) |
---|---|---|
20 | 20 | 5 |
标清 SD (≤ 640 × 360) | 高清 HD(≤ 1280 × 720) | 全高清 FHD(≤ 1920 × 1080) |
---|---|---|
20 | 10 | 5 |
标清 SD (≤ 640 × 360) | 高清 HD(≤ 1280 × 720) | 全高清 FHD(≤ 1920 × 1080) |
---|---|---|
20 | 10 | 5 |
如果你需要同时拉多种档位的流,则确保同时满足如下要求:
- 总路数不能超过所支持档位的最大路数,即 Max(标清支持路数, 高清支持路数, 全高清支持路数)。例如,如果你需要在中国大陆使用输入在线媒体流服务既拉标清,又拉高清,则拉流总路数不能超过 20;如果既拉高清,又拉全高清,则总路数不能超过 20。
- 各档位拉流路数不能超过该档位支持的最大路数。
API 限流
声网服务器限制用户 API 调用速率,超出限制速率时会返回状态码 429(Too Many Requests)
。
下表展示各 API 限流说明:
API | 限流说明 |
---|---|
Create | 根据创建的播放器是否有名字,限流情况不同:
|
Update | 根据更新的播放器是否有名字,限流情况不同:
|
Delete | 一个项目中,销毁云端播放器的速率上限为 100 次/秒。 |
List | 根据查询时是否设置过滤条件,限流情况不同:
|
提升配额
如果你想提升配额,可以联系技术支持。
保障服务高可用
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供故障迁移、多路任务保障、切换域名的方案。
故障迁移
针对网络故障,以及非声网云、非声网软件、设施和不可抗力因素等因素导致的输入在线媒体流中断,声网服务为了保证更好的用户体验,提供自动故障迁移服务,该服务会在尽量短的时间内完成迁移(预计 4 分钟内),迁移期间输入在线媒体流任务中断,可能导致部分数据丢失。
对于频道内较多观众端的场景或对高可用有极高要求的关键性业务,你需要基于当前业务的重要性和声网提供的自动迁移时效性来考虑是否采用更高的质量保障。例如,准备多路任务保障以应对迁移期间的快速切换,或者可以采用退避重试策略主动迁移以减少迁移时间。
多路任务保障
如需比故障迁移更高的质量保障,你可以采用多路任务保障策略。每路输入在线媒体流任务单独计费,计费方式详见计费说明。实现步骤如下:
- 同时发起主任务和备份任务,向同一频道推送在线媒体流,观众端订阅主任务中的
uid
。 - 在客户端监听以下回调事件,可以及时通知观众端订阅备份任务中的
uid
:- 主播掉线回调
onUserOffline
- 主播音视频状态变化回调
onRemoteAudioStateChanged
/onRemoteVideoStateChanged
- 主播掉线回调
切换域名
切换域名的操作如下:
-
根据你的业务服务器所在地设置主域名:
- 业务服务器 DNS 地址位于中国大陆时,设置主域名为
api.sd-rtn.com
。 - 业务服务器 DNS 地址位于中国大陆以外的国家或地区时,设置主域名为
api.agora.io
。
- 业务服务器 DNS 地址位于中国大陆时,设置主域名为
-
当使用主域名发起 RESTful API 请求失败时,使用该域名重试一次。
-
如果步骤 2 的重试依然失败,使用备用的主域名重试:
- 如果当前设置的主域名为
api.sd-rtn.com
,备用的主域名指api.agora.io
。 - 如果当前设置的主域名为
api.agora.io
,备用的主域名指api.sd-rtn.com
。
- 如果当前设置的主域名为
-
如果步骤 3 的重试依然失败,使用与当前解析区域相邻的区域域名重试。
举例说明:假设你的业务服务器位于欧洲,你设置主域名为
api.agora.io
,而且业务服务器解析主域名解析到德国。德国位于欧洲中部api-eu-central-1.agora.io
,查域名信息表可知,相邻区域为欧洲西部api-eu-west-1.agora.io
或api-eu-west-1.sd-rtn.com
。因此,出现网络故障且步骤 2、3 的重试失败时,请使用api-eu-west-1.agora.io
或api-eu-west-1.sd-rtn.com
域名重试。
注意事项
- 为避免重试请求过于频繁,超过声网服务所规定的 QPS(每秒请求数),声网建议你使用退避策略。例如,第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试。
- 如果是网络问题而非 DNS 解析域名问题导致的请求失败,声网建议你跳过步骤 3,直接进行步骤 4。
- 切换至区域域名前,请确保你使用的业务(例如,云端录制、云信令、频道管理等 REST 服务)在该区域有部署服务。
域名信息
主域名 | 区域域名 | 地理区域 |
---|---|---|
api.sd-rtn.com | api-us-west-1.sd-rtn.com | 美国西部 |
api-us-east-1.sd-rtn.com | 美国东部 | |
api-ap-southeast-1.sd-rtn.com | 亚太东南 | |
api-ap-northeast-1.sd-rtn.com | 亚太东北 | |
api-eu-west-1.sd-rtn.com | 欧洲西部 | |
api-eu-central-1.sd-rtn.com | 欧洲中部 | |
api-cn-east-1.sd-rtn.com | 中国华东 | |
api-cn-north-1.sd-rtn.com | 中国华北 | |
api.agora.io | api-us-west-1.agora.io | 美国西部 |
api-us-east-1.agora.io | 美国东部 | |
api-ap-southeast-1.agora.io | 亚太东南 | |
api-ap-northeast-1.agora.io | 亚太东北 | |
api-eu-west-1.agora.io | 欧洲西部 | |
api-eu-central-1.agora.io | 欧洲中部 | |
api-cn-east-1.agora.io | 中国华东 | |
api-cn-north-1.agora.io | 中国华北 |
检查创建请求设置
创建一个云端播放器时,请关注如下事项:
-
你需要通过
region
参数分区域创建云端播放器:- 设置的
region
与你的媒体流源站在同一个区域。例如媒体流源站为阿里云 OSS,则需要将region
设置为cn。
- 传入
region
的值为小写。
- 设置的
-
声网推荐你对请求 Header 中的
X-Request-ID
字段赋值,声网服务器会在响应 Header 中返回一个X-Custom-Request-ID
字段,以用于问题排查。 -
选择设置 UID 或 Account 作为云端播放器的用户名(请勿同时设置这两个字段),并保证每个云端播放器在频道内的用户名唯一。
-
为避免重复创建多个云端播放器导致重复输入媒体流,推荐使用
name
字段管理指定项目下的云端播放器:- 同一时间,一个项目下不允许出现重名的云端播放器,否则在尝试创建同名的云端播放器时会收到响应状态码
409(Conflict)
。
- 同一时间,一个项目下不允许出现重名的云端播放器,否则在尝试创建同名的云端播放器时会收到响应状态码
-
请注意云端播放器支持的音视频格式与协议,避免因使用不支持的音视频格式与协议导致输入媒体流失败。
- 请设置合理的
idleTimeout
的参数值,推荐使用默认值 300 秒,表示当媒体流为非播放状态 300 秒后云端播放器会自动销毁,停止输入在线媒体流。
- 请设置合理的
-
监听云端播放器创建成功事件后,当你成功创建一个云端播放器时,消息通知服务器会向你的服务器通知该事件。报告事件
payload
中status
字段为"connecting"
,表示业务服务器正在连接媒体流地址或正在探测音视频数据。
检查查询请求设置
分页查询一个项目下所有云端播放器时,请关注如下事项:
- 首次调用
List
时不使用查询参数pageToken
,在响应报文中获取首页查询结果和声网服务器返回的nextPageToken
。 - 再次调用
List
时,将nextPageToken
值传入查询参数pageToken
,查询下一页云端播放器列表。 - 直到
nextPageToken
为0
,表示已查到一个项目下所有云端播放器。云端播放器根据创建时间(createTs
)升序排列。
使用退避重试策略
当输入在线媒体流过程中出现 404
、429
、5xx
错误码时,你需要采取退避策略,例如等待 5-6 秒、10-11 秒、15-16 秒后重试。
使用退避策略重试后,如果连续 3 次出现 404、5xx 错误码,或查询推流状态响应包体中的 status
字段为 failed
,说明输入在线媒体流失败,请按照如下步骤依次排查:
- 确认媒体流地址是否正确,或该媒体流是否能够播放。
- 如果媒体流地址正确且能够播放,请销毁当前云端播放器,并重新创建。
根据错误码排查
发起请求时,你可能会收到如下响应状态码:
- 2XX:请求成功。
- 非 2XX:请求失败。你可以根据
message
或reason
字段内容推测请求失败的具体原因,再结合响应头的字段排查问题。
下表列出所有响应状态码和可能的 message
或 reason
字段内容:
状态码 | 可能的 message 或 reason 字段内容 | 建议措施 |
---|---|---|
200 OK | N/A | 无需排查 |
400 Bad Request |
| 检查报错的字段是否符合 API 文档的描述 |
401 Unauthorized | Invalid authentication credentials. | 检查 HTTP 基本认证是否符合要求 |
403 Forbidden |
| 检查是否已开通服务 |
404 Not Found | Resource is not found and destroyed. | 使用退避重试策略 |
409 Conflict | Resource with the same name already exists. | 删除已存在的同名云端播放器,然后重新请求创建 |
429 Too Many Requests |
| 使用退避重试策略 |
500 Unknown | Some internal error happened. Contact us to help fix it. | 使用退避重试策略 |
503 Service Unavailable |
| 使用退避重试策略 |
504 Gateway Timeout | Gateway timeout. Query to check whether the player has been created, or to create another one instead. | 使用退避重试策略 |
如果以上排查方法并未解决问题,请务必在日志中打印出响应 Header 中的 X-Request-ID
和 X-Resource-ID
字段值,并请联系技术支持。
上线检查清单
参考下表,快速确认每条检查项是否符合集成要求:
编号 | 重要程度 | 检查项 | 检查内容 | 符合集成要求 |
---|---|---|---|---|
1 | 必要 | 频道模式 | 所在频道场景为直播,即 profile 设为 BROADCASTING 。 | ✓ |
2 | 必要 | 开通服务 | 开通服务。 | ✓ |
3 | 必要 | 请求速率限制条件 | API 限流。 | ✓ |
4 | 必要 | 最大并发任务数限制 | 最大并发数。 | ✓ |
5 | 可选 | 管理 Converter |
| ✓ |
6 | 必要 | 区域设置 |
| ✓ |
7 | 必要 | 超时逻辑 | 设置合理的 idleTimeout ,推荐设置为 300 秒。 | ✓ |
8 | 可选 | 问题排查 | 使用退避重试策略或根据错误码排查。 | ✓ |
9 | 可选 | 接收事件回调 | 开通消息通知服务,并监听输入在线媒体流事件。 | ✓ |