旁路推流最佳实践

为了保障旁路推流服务的可靠性，Agora 建议你参考本文档集成旁路推流 RESTful API。阅读本文档前，建议你参考旁路推流 RESTful API 概览了解旁路推流 RESTful API 的基础流程。

前提条件

开始使用旁路推流 RESTful API 前，你需要满足以下条件：

• 所在频道场景为直播（profile 为 BROADCASTING）。
• 开通旁路推流 RESTful API 服务。
• 建议开通旁路推流消息通知服务，并监听旁路推流事件。

限制条件

API 调用速率限制

Agora 服务器限制旁路推流 RESTful API 的调用速率，超出限制速率时会返回状态码 429(Too Many Requests)。如果你有更高调用速率需求，请提交工单联系技术支持。

PCW 限制

PCW（最大并发任务数）默认为 300，表示允许在一个项目下最多同时运行 300 个推流任务，如需更高配额，请提交工单联系技术支持。

启动旁路推流

创建一个 Converter（Create）时，你需要关注以下注意事项：

• 你需要通过 region 参数分区域创建 Converter：

  • 设置的 region与你的 CDN 源站在同一个区域。
  • 传入 region 的值为小写。
  • 确保本地服务器覆盖本地推流服务。

• Agora 推荐你对请求报文的 Header 中的 X-Request-ID 字段赋值，Agora 服务器会在响应 Header 中返回一个 X-Custom-Request-ID 字段，以用于问题排查。

• 为避免重复创建多个 Converter 导致重复推流，使用 name 字段管理指定项目下的 Converter：

  • 同一时间，一个项目下不允许出现重名的 Converter，否则在尝试创建同名的 Converter 时会收到响应状态码 409(Conflict)。
  • Agora 推荐你以频道名和 Converter 特性组合来为 name 赋值。例如 show68_horizontal 和 show68_vertical，分别代表在频道 show68 中创建的用户画面为水平布局和和垂直布局的 Converter。

• 纯音频流或纯视频流场景下 audioOption 和 videoOptions 设置如下：

  • 在纯视频流（无音频）场景中，无需设置 audioOptions 及其相关字段。
  • 在纯音频流（无视频）场景中，无需设置 videoOptions 及其相关字段。
  • 在音视频场景中，videoOptions 为必填字段，不可设置为空；audioOptions 为必填字段，可以设置为空。

• 请设置合理的 idleTimeout 的参数值，推荐使用默认值 300 秒，表示当频道内所有订阅主播都离开频道 300 秒后 Converter 自动销毁，旁路推流停止。

更新旁路推流

更新指定的 Converter（Update）时，你需要关注以下注意事项：

• 使用查询参数 sequence 对同一个 Converter 进行多次 Update 时，请确保 sequence 值递增，旁路推流服务会按照最新 Update 请求（即最大序列号）更新 Converter。
• Update 不支持更新 Converter 的如下配置：
  • name
  • idleTimeOut
  • transcodeOptions.rtcChannel
  • transcodeOptions.audioOptions
  • transcodeOptions.audioOptions.codecProfile
  • transcodeOptions.audioOptions.sampleRate
  • transcodeOptions.audioOptions.bitrate
  • transcodeOptions.audioOptions.audioChannels
  • transcodeOptions.videoOptions.codec
  • transcodeOptions.videoOptions.codecProfile

问题排查及建议措施

使用退避策略重试

当推流过程中出现 404、429、5xx 错误码时，你需要采取退避策略，例如次等待 5-6 秒、10-11 秒、15-16 秒后重试。

使用退避策略重试后，如果连续 3 次响应包体中的 state 字段为 failed，说明推流失败，请按照以下步骤进行排查：

1. 确认 CDN 推流地址是否正确。
2. 如果 CDN 推流地址正确，请销毁当前 Converter，并重新创建。

其他异常情况下，旁路推流服务会自动更换推流服务器重新推流。

根据错误码排查

• 如果状态码为 200，则请求成功。
• 如果状态码不为 200，则请求失败。请根据对应的响应报文 Body 中的 message 字段内容排查问题。

联系 Agora 技术支持

如果以上排查方法并未解决问题，请务必在日志中打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值，并联系 Agora 技术支持。

检查清单

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