文档中心
云端录制
Agora.io 社区
中文
search-icon
云端录制集成最佳实践
更新时间 2021/03/09 07:10:02

为了保障录制服务的可靠性，Agora 建议你在集成云端录制 RESTful API 时注意以下几点：

使用双域名

如果你使用域名 api.agora.io 发起 RESTful API 请求失败，可以先用该域名重试一次；如再次失败，可将域名替换为 api.sd-rtn.com，再次发送请求。建议使用退避策略，如第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试，以免超过每秒请求数（QPS）限制导致失败。

获取服务状态

你可以通过云端录制 RESTful API 来获取录制服务状态。相比于云端录制 RESTful API，消息通知服务可以作为辅助手段。

消息通知服务只能作为辅助手段来获取服务录制状态。不建议你的核心业务逻辑依赖消息通知服务。如果你的业务对该服务强依赖，建议提交工单开通冗余消息功能，即接收双路消息通知，降低消息丢失的概率。开通冗余消息功能后，需要你基于 sid 对消息进行去重。冗余消息功能仍然不能保证 100% 的消息到达率。
每个 App ID 每秒钟的请求数（QPS）限制默认为 10 次。请根据你的同时最大并发频道量（PCU）和查询间隔，预估所需的 QPS，并通过提交工单的方式申请调整 QPS 限制。

确认录制服务已成功启动

建议你通过如下步骤确认录制服务已成功启动：

  1. 确认 start 请求成功，即成功获得 sid (录制 ID)。如果 start 请求失败，需要根据状态码采取相应措施：
    • 如果返回的 HTTP 状态码为 40x，则表示请求参数错误，需要进行排查。
    • 如果返回的 HTTP 状态码为 50x，可使用相同的参数重试多次，直到成功返回 sid 为止。建议使用退避策略，如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试，以免超过 QPS 限制导致失败。如果三次重试均失败，建议更换 UID 再次调用 acquire， 获得一个新的 resource ID，并用该 resource ID 再次调用 start 方法。
    • 如果收到错误码 65，需要使用相同的参数再次调用 start。建议使用退避策略重试两次，如第一次等待 3 秒后重试、第二次等待 6 秒后重试。
  2. 获得 sid 之后的 5 秒后，使用退避策略调用 query 方法，退避间隔建议小于 start 请求中的 maxIdleTime (最长空闲频道时间)。如果 query 请求成功，且 serverResponse 中的 status 参数值为 4 或 5，则表示录制服务已成功启动。如果在获得 sid 之后的 90 秒后 status 仍非 4 或 5， 则可以认为录制未启动或成功后超时退出。
建议你准备一个备份 UID，在重新启动录制时使用，以避免频道内两个相同 UID 互踢。主备 UID 可以交替使用。

录制过程中的服务状态监控

你可以通过周期性调用 query 来确认录制服务正在进行中且状态正常。相比于 query，消息通知服务可以作为辅助手段。详见消息通知服务和 query 方法的对比。

周期性频道查询

如果你对状态查询的可靠性要求较高，Agora 强烈建议你使用 query 方法周期性查询频道内的录制状态，例如每隔 2 分钟调用一次 query，并根据返回的 HTTP 状态码采取相应措施。

  • 如果返回的 HTTP 状态码一直为 40x，则表示请求参数错误，需要进行排查。
  • 如果返回的 HTTP 状态码为 404，且已经确认请求参数无误，则表示录制并未成功启动、或启动后中途退出。建议采用退避策略多次调用 query （例如间隔 5 秒、10 秒、15 秒）进行确认。
  • 如果返回的 HTTP 状态码为 50x，则表示 query 请求失败，但尚不明确录制是否已退出。出现 50x 错误的概率极小，建议使用退避策略 (5 秒, 10 秒, 15 秒，30 秒) 继续调用 query。

冗余消息通知服务

开通冗余消息功能后，需要你基于 sid 对消息进行去重。举例来说，如果你需要在录制超时退出后再次开启录制，流程为：

  1. 你的服务器收到 31、32、或 11 事件，表示录制服务已正常退出。
  2. 收到事件后，你的应用调用 acquire，重新开启录制服务。
  3. 在此期间你的服务器又收到了 31、32、或 11 事件。如果以上事件中的 sid 与前一次的 31、32、或 11 事件一致，则可以作为冗余事件通知忽略。
  4. 如果你需要完全确保成功开启了录制服务，则仍然需要调用 query 进行查询。
一旦录制服务启用了高可用机制，某些消息可能会发送两次，你可以根据消息中的 UID 进行区分：如果 UID 与发起录制时使用的 UID 一致，则该消息为原有录制进程的事件；如果不一致，则该消息为启用高可用机制后的事件。

获取 M3U8 文件名

获取 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 分钟，保证整堂课的录制不中断。