为了保障录制服务的可靠性,Agora 建议你在集成云端录制 RESTful API 时注意以下几点:
如果你使用域名 api.agora.io
发起 RESTful API 请求失败,可以先用该域名重试一次;如再次失败,可将域名替换为 api.sd-rtn.com
,再次发送请求。建议使用退避策略,如第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试,以免超过每秒请求数(QPS)限制导致失败。
你可以通过云端录制 RESTful API 来获取录制服务状态。相比于云端录制 RESTful API,消息通知服务可以作为辅助手段。
sid
对消息进行去重。冗余消息功能仍然不能保证 100% 的消息到达率。建议你通过如下步骤确认录制服务已成功启动:
start
请求成功,即成功获得 sid
(录制 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 方法的对比。
如果你对状态查询的可靠性要求较高,Agora 强烈建议你使用 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
来查询。Agora 推荐通过拼接的方式获取文件名。
合流录制模式下,M3U8 文件名的格式为 <sid>_<cname>.m3u8
。因此,你还可以通过拼接的方式获取 M3U8 文件名。详见录制文件命名规则。
query
请求获得 M3U8 文件的文件名M3U8 文件名是第一份切片文件生成后产生的,所以需要在第一次切片完成后查询。详见切片规则。
合流录制模式下,建议在成功开启云端录制 15 秒后调用 query
查询 M3U8 文件名;单流录制模式下,建议在成功开启云端录制 1 分钟后调用 query
查询 M3U8 文件名。如果第一次查询失败,可以在 1 分钟后重试。
start
方法中的 maxIdleTime
参数默认值为 30 秒。如果实际场景中主播频繁上下线,过短的 maxIdleTime
会导致录制服务频繁退出。对于要求录制服务一直在频道中的场景,需要加大 maxIdleTime
,避免因频道内短时间无发流端导致的录制退出。
举例来说,如果每堂课中固定有 5 分钟的休息时间,则可以将 maxIdleTime
设置为 10 分钟,保证整堂课的录制不中断。