输入在线媒体流最佳实践

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

前提条件

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

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

限制条件

API 调用速率

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

API	限流说明
Create	一个项目中，创建有名字（name）的云端播放器时，每个不同名字的云端播放器的创建速率上限为 2 次/秒。 一个项目中，创建没有名字（name）的云端播放器时，云端播放器的创建速率上限为 50 次/ 秒。
Delete	一个项目中，销毁云端播放器的速率上限为 100 次/秒。
List	一个项目中，有过滤条件（filter）时，查询速率上限为 2 次/秒 和 15 次/分钟。 一个项目中，没有过滤条件（filter）时，查询速率上限为 10 次/秒和 20 次/分钟。

最大并发任务数

最大并发任务数默认为 50，表示允许在一个项目下最多同时运行 50 个输入在线媒体流任务。如需更高配额，请联系技术支持。

保障 REST 服务高可用

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

故障迁移

针对网络故障，以及非声网云、非声网软件、设施和不可抗力因素等因素导致的输入在线媒体流中断，声网流为了保证更好的用户体验，提供自动故障迁移服务，该服务会在尽量短的时间内完成迁移（预计 4 分钟内），迁移期间输入在线媒体流任务中断，可能导致部分数据丢失。
如果对于频道内较多观众端的场景或关键性业务，你需要基于当前业务的重要性和声网提供的自动迁移时效性来考虑是否采用更高的质量保障，例如准备多路流保障以应对迁移期间的快速切换，或者可以采用退避重试策略主动迁移以减少迁移时间。

多路任务保障

如需比故障迁移更高的质量保障，你可以采用多路任务保障策略。每路输入在线媒体流任务单独计费，计费方式详见输入在线媒体流计费说明。实现步骤如下：

1. 同时发起主任务和备份任务，向同一频道推送在线媒体流，观众端订阅主任务中的 uid。

2. 在客户端监听以下回调事件，可以及时通知观众端订阅备份任务中的 uid：

   • 主播掉线回调 onUserOffline
   • 主播音视频状态变化回调 onRemoteAudioStateChanged/onRemoteVideoStateChanged

切换域名

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 服务）在该区域有部署服务。

域名信息

主域名	区域域名	地理区域
api.sd-rtn.com	api-us-west-1.sd-rtn.com	美国西部
	api-us-east-1.sd-rtn.com	美国东部
	api-ap-southeast-1.sd-rtn.com	亚太东南
	api-ap-northeast-1.sd-rtn.com	亚太东北
	api-eu-west-1.sd-rtn.com	欧洲西部
	api-eu-central-1.sd-rtn.com	欧洲中部
	api-cn-east-1.sd-rtn.com	中国华东
	api-cn-north-1.sd-rtn.com	中国华北
api.agora.io	api-us-west-1.agora.io	美国西部
	api-us-east-1.agora.io	美国东部
	api-ap-southeast-1.agora.io	亚太东南
	api-ap-northeast-1.agora.io	亚太东北
	api-eu-west-1.agora.io	欧洲西部
	api-eu-central-1.agora.io	欧洲中部
	api-cn-east-1.agora.io	中国华东
	api-cn-north-1.agora.io	中国华北

创建云端播放器

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

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

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

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

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

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

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

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

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

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

查询云端播放器

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

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

问题排查及建议措施

使用退避策略重试

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

使用退避策略重试后，如果连续 3 次出现 404、5xx 错误码，或查询推流状态响应包体中的 state 字段为 failed，说明输入在线媒体流失败，请按照以下步骤进行排查：

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

根据错误码排查

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

状态码	可能的 message 字段内容	原因	建议措施
200 OK	/	创建成功	/
400 Bad Request	Parameter 'streamUrl' is invalid formatted.Parameter channelName is invalid. Fix it in your request and retry.	请求参数错误	参考 HTTP 响应 Body 中的 reason 字段进行排查。
401 Unauthorized	Invalid authentication credentials.	RESTful API 认证失败	重新 HTTP 基本认证。
403 Forbidden	This project has not enabled Cloud Player product yet. Contact us to enable it.This project's permission to use Cloud Player was revoked. Contact us for details.	未开通服务	开通输入在线媒体流服务。
404 Not Found	Resource is not found and destroyed.	并未成功启动任务，或启动任务后中途退出，或自动迁移中，或正在销毁云端播放器。	采用退避策略重试。
409 Conflict	Resource with the same name already exists.	频道中已存在相同用户名的云端播放器。	删除已有的云端播放器并重新创建。
429 Too Many Requests	Request rate limit exceeded.Resources quota limit exceeded.no available resources	并发请求过多	采用退避策略重试。
500 Unknown	Some internal error happened. Contact us to help fix it.	服务端内部错误	采用退避策略重试。
502 Bad gateway	Internal errors. Contact us for troubleshooting.	服务端内部错误	采用退避策略重试。
503 Service Unavailable	Service overload. Retry with back off strategy, and contact us to help fix it.Service unavailable temporarily. Retry with back off strategy.	服务端内部错误	采用退避策略重试。
504 Gateway Timeout	Gateway timeout. Query to check whether the player has been created, or to create another one instead.	服务端内部错误	采用退避策略重试。

联系声网技术支持

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

检查清单

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

编号	重要程度	检查项	检查内容	符合集成要求
1	必要	频道模式	所在频道场景为直播。	✓
2	必要	开通服务	开通输入在线媒体流服务。	✓
3	必要	QPS 限制条件	确保一个项目中，API 的调用速率低于最大限制。详见 API 调用速率限制。	✓
4	必要	最大并发任务数限制	确保一个项目中，并发任务数低于 50。详见 最大并发任务数限制。	✓
5	可选	管理 Converter	选择设置 uid 或 account 作为云端播放器的用户名（请勿同时设置这两个字段）。 使用 name 字段管理指定项目下的云端播放器。	✓
6	必要	区域设置	设置的 region 与你的媒体流源站在同一个区域。 传入 region 值为小写。	✓
7	必要	超时逻辑	设置合理的 idleTimeout，推荐设置为 300 秒。	✓
8	可选	问题排查	请按照如下方案进行问题排查： 使用退避策略。 根据错误码排查。 如果以上排查方法并未解决问题，请打印出响应 Header 中的 X-Request-ID 和 X-Resource-ID 字段值，并联系声网技术支持。	✓
9	可选	消息通知	开通输入在线媒体流消息通知服务，并监听输入在线媒体流事件。	✓