云端录制集成最佳实践

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

保障 REST 服务高可用

为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供故障迁移和切换域名的方案。

故障迁移

针对网络故障，以及非声网云服务，非声网软件，基础设施和不可抗力等因素可能导致的风险，声网云录制为了更好的用户体验，提供高可用自动任务迁移服务。当故障确认后，该服务会在尽量短的时间（预计 90 秒内）完成，在此期间会存在录制中断，录制文件丢失等风险。
对于频道内较多观众端或对高可用要求极高场景，你需要基于自身业务特点综合考虑能否接受高可用迁移影响，决策是否要采用更高的质量保障措施，例如关键任务多路录制（使用不同 uid 发起多路录制任务），或通过周期性频道查询和消息通知服务获知录制任务状态，及时使用不同的 uid 重新发起新的录制任务。

切换域名

1. 根据你的业务服务器所在地设置主域名：
   • 业务服务器 DNS 地址位于中国大陆时，设置主域名为 api.sd-rtn.com。
   • 业务服务器 DNS 地址位于中国大陆以外的国家或地区时，设置主域名为 api.agora.io。
2. 当使用主域名发起 RESTful API 请求失败时，使用该域名重试一次。
3. 如果步骤 2 的重试依然失败，使用备用的主域名重试：
   • 如果当前设置的主域名为 api.sd-rtn.com，备用的主域名指 api.agora.io。
   • 如果当前设置的主域名为 api.agora.io，备用的主域名指 api.sd-rtn.com。
4. 如果步骤 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 服务）在该区域有部署服务。

域名信息

获取服务状态

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

确认录制服务已成功启动

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

1. 确认 start 请求成功，即成功获得 sid (录制 ID)。如果 start 请求返回 HTTP 状态码非 200，则需要根据状态码采取相应措施：
   • 如果返回的 HTTP 状态码为 201，则表示录制任务已成功启动并在进行中。
   • 如果返回的 HTTP 状态码为 206，则表示请求超时，建议使用退避策略，如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试，以免超过 QPS 限制导致失败。如果三次重试均失败，建议更换 UID 再次调用 acquire， 获得一个新的 resource ID，并用该 resource 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， 则可以认为录制未启动或成功后超时退出。

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

你可以通过周期性调用 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 对消息进行去重。举例来说，如果你需要在录制超时退出后再次开启录制，流程为：

1. 你的服务器收到 31、32、或 11 事件，表示录制服务已正常退出。
2. 收到事件后，你的应用调用 acquire，重新开启录制服务。
3. 在此期间你的服务器又收到了 31、32、或 11 事件。如果以上事件中的 sid 与前一次的 31、32、或 11 事件一致，则可以作为冗余事件通知忽略。
4. 如果你需要完全确保成功开启了录制服务，则仍然需要调用 query 进行查询。

获取 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 小时以上。

检查清单

参考以下表格，快速确认每条检查项是否符合集成要求，以保证云端录制服务的可靠性。