集成最佳实践
为了保障单流录制、合流录制、页面录制、视频截图等云端录制服务的可靠性,声网建议你参考本文了解集成最佳实践。
保障 REST 服务高可用
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供故障迁移、多路任务保障、切换域名的方案。
故障迁移
针对网络故障,以及非声网云服务、非声网软件、基础设施和不可抗力等因素可能导致的风险,声网云端录制提供高可用自动任务迁移服务。当故障确认后,该服务会在尽量短的时间(预计 90 秒内)完成,在此期间会存在录制中断,录制文件丢失等风险。
对于频道内较多观众端或对高可用要求极高场景,你需要基于自身业务特点综合考虑能否接受高可用迁移影响,决策是否要采用更高的质量保障措施,例如多路任务保障,或通过周期性频道查询和消息通知服务获知录制任务状态,及时使用不同的 uid
重新发起新的录制任务。
多路任务保障
如需比故障迁移更高的质量保障,你可以采用多路任务保障策略。每路云端录制任务单独计费,计费方式详见计费说明。实现步骤如下:
-
同时发起主任务和备份任务,实现对同一个频道进行多路录制。为此,你需要使用相同
appId
和cname
,以及不同的uid
来发起多个录制任务。发起后一路录制任务时,你需要在acquire
请求的 Body 中设置clientRequest.excludeResourceIds
字段,将其设置为前一路或前几路录制任务的resourceId
,以排除后一路录制任务使用此前录制任务所在区域的资源。当此前录制任务所在区域的网络故障时,后一路录制任务不会受到影响。 -
在客户端监听以下回调事件,可以及时通知观众端订阅备份任务中的
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 | 中国华北 |
检查服务配额
请检查如下各项服务配额,确保没有超出声网限制。
峰值并发任务数 PCW
峰值并发任务数(PCW)指最大并发任务数。PCW 限制和你使用云端录制服务处理的视频流分辨率、所在地区有关,详见下表:
服务类型 | 中国大陆 | 欧洲 | 美洲 | 亚洲(除中国大陆) |
---|---|---|---|---|
单流录制 | 1000 | 200 | 400 | 300 |
合流录制 |
|
|
|
|
页面录制 |
|
|
|
|
视频分辨率说明:
- SD:标清视频,分辨率 ≤ 640 × 360
- HD:高清视频,640 × 360 < 分辨率 ≤ 1280 × 720
- FHD:全高清视频,1280 × 720 < 分辨率 ≤ 1920 × 1080
每秒请求数 QPS
对于每个声网账号,每秒请求数(QPS)上限为 10。
请根据你的 PCW 和查询间隔,预估所需的 QPS。
录制分辨率和路数限制
云端录制支持处理的视频属性上限为:分辨率 1920 × 1080,帧率 30 fps。
云端录制支持处理的最大流路数详见下表:
服务类型 | 中国大陆 | 欧洲 | 美洲 | 亚洲(除中国大陆) |
---|---|---|---|---|
云端录制 |
|
|
|
|
页面录制 |
|
|
|
|
如果你需要同时多种档位的流,确保同时满足如下要求:
- 各档位录制路数不能超过该档位支持的最大路数。
- 总路数不能超过所有录制档位支持路数的最大值。
例如,当你需要在中国大陆使用云端录制时,如果你既录制标清,又录制高清视频,则标清录制路数不能超过 100,高清录制路数不能超过 50,录制总路数不能超过 100;如果你既录制高清,又录制全高清视频,则高清录制路线不能超过 50,全高清录制路数不能超过 30,录制总路数不能超过 50。
提升配额
如果你想提升配额,可以联系技术支持。
获取服务状态
你可以通过云端录制 RESTful API 来获取录制服务状态。相比于云端录制 RESTful API,消息通知服务可以作为辅助手段。
消息通知服务只能作为辅助手段来获取服务录制状态。不建议你的核心业务逻辑依赖消息通知服务。如果你的业务对该服务强依赖,建议联系技术支持开通冗余消息功能,即接收双路消息通知,降低消息丢失的概率。开通冗余消息功能后,需要你基于 sid
对消息进行去重。冗余消息功能仍然不能保证 100% 的消息到达率。
确认录制服务已成功启动
建议你通过如下步骤确认录制服务已成功启动:
- 每次
acquire
请求获取到 Resource ID 后的 2 秒内立即发起对应的start
请求。批量获取 Resource ID 后进行批量start
请求可能导致请求失败。acquire
和start
的请求需配对调用。Resource ID 在获取到的 5 分钟内有效,需尽快使用。超时需要重新申请 Resource ID。 - 确认
start
请求成功,即成功获得sid
(录制 ID)。如果start
请求返回 HTTP 状态码非200
,则需要根据状态码采取相应措施:- 如果返回的 HTTP 状态码为
201
,则表示录制任务已成功启动并在进行中,无需重试。 - 如果返回的 HTTP 状态码为
206
或50x
,则表示请求超时,建议使用退避策略,如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试,以免超过 QPS 限制导致失败。如果三次重试均失败,建议更换 UID 再次调用acquire
, 获得一个新的 Reource ID,并用该 Reource ID 再次调用start
方法。 - 如果返回的 HTTP 状态码为
40x
,则表示请求参数错误,需要进行排查。
- 如果返回的 HTTP 状态码为
- 获得
sid
之后的 5 秒后,使用退避策略调用query
方法,退避间隔建议小于start
请求中的maxIdleTime
(最长空闲频道时间)。如果query
请求成功,且serverResponse
中的status
参数值为4
或5
,则表示录制服务已成功启动。如果在获得sid
之后的 90 秒后status
仍非4
或5
, 则可以认为录制未启动或成功后超时退出。
建议你准备一个备份 UID,在重新启动录制时使用,以避免频道内两个相同 UID 互踢。主备 UID 可以交替使用。
录制过程中的服务状态监控
你可以通过周期性调用 query
方法来确认录制服务正在进行中且状态正常。相比于 query
,消息通知服务可以作为辅助手段。详见消息通知服务和 query 方法的对比。
周期性频道查询
如果你对状态查询的可靠性要求较高,声网强烈建议你使用 query
方法周期性查询频道内的录制状态,例如每隔 2 分钟调用一次 query
,并根据返回的 HTTP 状态码采取相应措施。
- 如果返回的 HTTP 状态码一直为
40x
,则表示请求参数错误,需要进行排查。 - 如果返回的 HTTP 状态码为
404
,且已经确认请求参数无误,则表示录制并未成功启动、或启动后中途退出。建议采用退避策略多次调用query
(例如间隔 5 秒、10 秒、15 秒)进行确认。 - 如果返回的 HTTP 状态码为
50x
,则表示query
请求失败,但尚不明确录制是否已退出。出现50x
错误的概率极小,建议使用退避策略 (5 秒, 10 秒, 15 秒,30 秒) 继续调用query
。
冗余消息通知功能
开通消息通知服务后,为避免消息投递的确认消息可能丢失,声网会重传消息。因此你需要基于 sid
对消息进行去重。举例来说,如果你需要在录制超时退出后再次开启录制,流程为:
- 你的服务器收到
31
、32
、或11
事件,表示录制服务已正常退出。 - 收到事件后,你的应用调用
acquire
,重新开启录制服务。 - 在此期间你的服务器又收到了
31
、32
、或11
事件。如果以上事件中的sid
与前一次的31
、32
、或11
事件一致,则可以作为冗余事件通知忽略。 - 如果你需要完全确保成功开启了录制服务,则仍然需要调用
query
进行查询。
一旦录制服务启用了高可用机制,某些消息可能会发送两次,你可以根据消息中的 UID 进行区分:如果 UID 与发起录制时使用的 UID 一致,则该消息为原有录制进程的事件;如果不一致,则该消息为启用高可用机制后的事件。
获取 M3U8 文件名
获取 M3U8 文件名有两种方式,一种是按照文件命名规则拼接,另一种是通过 query
来查询。声网推荐通过拼接的方式获取文件名。
按照文件命名规则拼接
合流录制模式下,M3U8 文件名的格式为 <sid>_<cname>.m3u8
。因此,你还可以通过拼接的方式获取 M3U8 文件名。详见录制文件命名规则。
通过 query 请求获得 M3U8 文件的文件名
M3U8 文件名是第一份切片文件生成后产生的,所以需要在第一次切片完成后查询。详见切片规则。
合流录制模式下,建议在成功开启云端录制 15 秒后调用 query
查询 M3U8 文件名;单流录制模式下,建议在成功开启云端录制 1 分钟后调用 query
查询 M3U8 文件名。如果第一次查询失败,可以在 1 分钟后重试。
避免录制服务频繁退出
start
方法中的 maxIdleTime
字段默认值为 30 秒。如果实际场景中主播频繁上下线,过短的 maxIdleTime
会导致录制服务频繁退出。对于要求录制服务一直在频道中的场景,需要加大 maxIdleTime
,避免因频道内短时间无发流端导致的录制退出。
举例来说,如果每堂课中固定有 5 分钟的休息时间,则可以将 maxIdleTime
设置为 10 分钟,保证整堂课的录制不中断。
录制上传
录制结束后,正常情况下录制文件会在 20 分钟内上传至第三方云存储,但在网络异常等特殊情况下上传时间会达到 24 小时以上。
检查清单
参考以下表格,快速确认每条检查项是否符合集成要求,以保证云端录制服务的可靠性。
编号 | 重要程度 | 检查项 | 检查内容 |
---|---|---|---|
1 | 必选 | 开通服务 | 确保已开通云端录制服务。 |
2 | 必选 | 请求方式 |
|
3 | 必选 | 获取录制资源 |
|
4 | 必选 | 频道场景 | 确保频道场景(channelType )与声网 RTC SDK 的设置一致。 |
5 | 必选 | 录制参数 | |
6 | 必选 | 确认录制服务已成功启动 |
|
7 | 必选 | PCW & QPS 限制 |
|
8 | 可选 | 使用回调服务 | 开通云端录制回调服务并订阅以下事件作为监控录制服务状态的辅助手段:
|
9 | 可选 | 使用双域名 | 使用主域名(api.agora.io )发起请求失败时,先用主域名重试一次;如再次失败,则切换至副域名(api.sd-rtn.com )再次发送请求。 |
10 | 可选 | 超时逻辑 | 设置合理的 maxIdleTime ,推荐设置为 300 秒。 |