为了保障录制服务的可靠性,声网建议你在集成云端录制 RESTful API 时注意以下几点:
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供故障迁移和切换域名的方案。
针对网络故障,以及非声网云服务,非声网软件,基础设施和不可抗力等因素可能导致的风险,声网云录制为了更好的用户体验,提供高可用自动任务迁移服务。当故障确认后,该服务会在尽量短的时间(预计 90 秒内)完成,在此期间会存在录制中断,录制文件丢失等风险。
对于频道内较多观众端或对高可用要求极高场景,你需要基于自身业务特点综合考虑能否接受高可用迁移影响,决策是否要采用更高的质量保障措施,例如关键任务多路录制(使用不同 uid
发起多路录制任务),或通过周期性频道查询和消息通知服务获知录制任务状态,及时使用不同的 uid
重新发起新的录制任务。
主域名 | 区域域名 | 地理区域 |
---|---|---|
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 | 中国华北 |
你可以通过云端录制 RESTful API 来获取录制服务状态。相比于云端录制 RESTful API,消息通知服务可以作为辅助手段。
sid
对消息进行去重。冗余消息功能仍然不能保证 100% 的消息到达率。建议你通过如下步骤确认录制服务已成功启动:
start
请求成功,即成功获得 sid
(录制 ID)。如果 start
请求返回 HTTP 状态码非 200
,则需要根据状态码采取相应措施:201
,则表示录制任务已成功启动并在进行中。206
,则表示请求超时,建议使用退避策略,如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试,以免超过 QPS 限制导致失败。如果三次重试均失败,建议更换 UID 再次调用 acquire
, 获得一个新的 resource ID,并用该 resource ID 再次调用 start
方法。40x
,则表示请求参数错误,需要进行排查。50x
,可使用相同的参数重试多次,直到成功返回 sid
为止。建议使用退避策略,如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试,以免超过 QPS 限制导致失败。如果三次重试均失败,建议更换 UID 再次调用 acquire
, 获得一个新的 resource ID,并用该 resource ID 再次调用 start
方法。65
,需要使用相同的参数再次调用 start
。建议使用退避策略重试两次,如第一次等待 3 秒后重试、第二次等待 6 秒后重试。sid
之后的 5 秒后,使用退避策略调用 query
方法,退避间隔建议小于 start
请求中的 maxIdleTime
(最长空闲频道时间)。如果 query
请求成功,且 serverResponse
中的 status
参数值为 4
或 5
,则表示录制服务已成功启动。如果在获得 sid
之后的 90 秒后 status
仍非 4
或 5
, 则可以认为录制未启动或成功后超时退出。你可以通过周期性调用 query
方法来确认录制服务正在进行中且状态正常。相比于 query
,消息通知服务可以作为辅助手段。详见消息通知服务和 query 方法的对比。
如果你对状态查询的可靠性要求较高,声网强烈建议你使用 query
方法周期性查询频道内的录制状态,例如每隔 2 分钟调用一次 query
,并根据返回的 HTTP 状态码采取相应措施。
40x
,则表示请求参数错误,需要进行排查。404
,且已经确认请求参数无误,则表示录制并未成功启动、或启动后中途退出。建议采用退避策略多次调用 query
(例如间隔 5 秒、10 秒、15 秒)进行确认。50x
,则表示 query
请求失败,但尚不明确录制是否已退出。出现 50x
错误的概率极小,建议使用退避策略 (5 秒, 10 秒, 15 秒,30 秒) 继续调用 query
。开通冗余消息功能后,需要你基于 sid
对消息进行去重。举例来说,如果你需要在录制超时退出后再次开启录制,流程为:
31
、32
、或 11
事件,表示录制服务已正常退出。acquire
,重新开启录制服务。31
、32
、或 11
事件。如果以上事件中的 sid
与前一次的 31
、32
、或 11
事件一致,则可以作为冗余事件通知忽略。query
进行查询。获取 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 | 必选 | 请求方式 | query (查询录制状态)使用 GET 外,其余均使用 POST 请求方式。 |
✓ |
3 | 必选 | 获取录制资源 | uid 不能与当前频道内的任何 UID 重复。 start 方法开始录制。 |
✓ |
4 | 必选 | 频道场景 | 确保频道场景(channelType )与声网 RTC SDK 的设置一致。 |
|
5 | 必选 | 录制参数 | ✓ | |
6 | 必选 | 确认录制服务已成功启动 | start 请求成功,即成功获得 sid (录制 ID)。sid 之后的 90 秒内 status 为 4 或 5 。 |
✓ |
7 | 必选 | PCW & QPS 限制 | ✓ | |
8 | 可选 | NCS 服务开通 | 开通云端录制回调服务并订阅以下事件作为监控录制服务状态的辅助手段:40 recorder_started :录制服务已启动。11 session_exit :录制服务结束任务并退出。1 cloud_recording_error :录制服务发生错误。12 session_failover :录制启用高可用机制。31 uploaded :所有录制文件已上传至指定的第三方云存储。 |
✓ |
9 | 可选 | 使用双域名 | 使用主域名(api.agora.io )发起请求失败时,先用主域名重试一次;如再次失败,则切换至副域名(api.sd-rtn.com )再次发送请求。 |
✓ |
10 | 可选 | 超时逻辑 | 设置合理的 maxIdleTime ,推荐设置为 300 秒。 |
✓ |