输入在线媒体流最佳实践

为了保障输入在线媒体流服务的可靠性，Agora 建议你参考本文档集成输入在线媒体流 RESTful API。阅读本文档前，建议你参考输入在线媒体流 RESTful API 了解输入在线媒体流 RESTful API 的基础流程。

前提条件

开始使用输入在线媒体流 RESTful API 前，你需要满足以下条件：

• 所在频道场景为直播（profile 为 BROADCASTING）。
• 开通输入在线媒体流服务。
• 建议开通输入在线媒体流消息通知服务，并监听输入在线媒体流事件。

限制条件

API 调用速率限制

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

PCW 限制

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

创建云端播放器

创建一个云端播放器（Create）时，你需要关注以下注意事项：

• 你需要通过 region 参数分区域创建云端播放器：

  • 设置的 region与你的媒体流源站在同一个区域。例如媒体流源站为阿里云 OSS，则需要将 region 设置为 cn。
  • 传入 region 的值为小写。

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

• 选择设置 UID 或 Account 作为云端播放器的用户名（请勿同时设置这两个字段），并保证每个云端播放器在频道内的用户名唯一。

• 为避免重复创建多个云端播放器导致重复输入媒体流，推荐使用 name 字段管理指定项目下的云端播放器：

  • 同一时间，一个项目下不允许出现重名的云端播放器，否则在尝试创建同名的云端播放器时会收到响应状态码 409(Conflict)。

• 请注意云端播放器支持的音视频格式与协议，避免因使用不支持的音视频格式与协议导致输入媒体流失败。

  • 请设置合理的 idleTimeout 的参数值，推荐使用默认值 300 秒，表示当媒体流为非播放状态 300 秒后云端播放器会自动销毁，停止输入在线媒体流。

• 监听云端播放器创建成功事件后，当你成功创建一个云端播放器时，消息通知服务器会向你的服务器通知该事件。报告事件 payload 中 status字段为 "connecting"，表示业务服务器正在连接媒体流地址或正在探测音视频数据。

查询云端播放器

Agora 建议你按照以下方式分页查询一个项目下所有云端播放器（List）：

1. 首次调用 List 时不使用查询参数 pageToken，在响应报文中获取首页查询结果和 Agora 服务器返回的 nextPageToken。
2. 再次调用 List 时，将 nextPageToken 值传入查询参数 pageToken，查询下一页云端播放器列表。
3. 直到 nextPageToken 为 0，表示已查到一个项目下所有云端播放器。云端播放器根据创建时间（createTs）升序排列。

问题排查及建议措施

使用退避策略重试

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

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

1. 确认媒体流地址是否正确，或该媒体流是否能够播放。
2. 如果媒体流地址正确且能够播放，请销毁当前云端播放器，并重新创建。

根据错误码排查

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

联系 Agora 技术支持

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

检查清单

参考以下表格，快速确认每条检查项是否符合集成要求，以保证输入在线媒体流服务的可靠性。