旁路推流最佳实践
为了保障旁路推流服务的可靠性,声网建议你参考本文档集成旁路推流 RESTful API。阅读本文档前,建议你参考旁路推流 RESTful API 概览了解旁路推流 RESTful API 的基础流程。
前提条件
开始使用旁路推流 RESTful API 前,你需要满足以下条件:
- 所在频道场景为直播(
profile
为BROADCASTING
)。 - 开通旁路推流 RESTful API 服务。
- 建议开通旁路推流消息通知服务,并监听旁路推流事件。
限制条件
本节介绍旁路推流的限制条件,包含配额限制和混音人数限制。如果你想增加配额或混音人数,联系技术支持。
API 调用速率限制
声网服务器限制旁路推流 RESTful API 的调用速率,超出限制速率时会返回状态码 429 (Too Many Requests)
。
API | 限流说明 |
---|---|
Create | 一个项目中,创建 Converter 的速率上限为 50 次/秒。 |
Delete | 一个项目中,销毁 Converter 的速率上限为 50 次/秒。 |
Update | 一个项目中,更新一个指定的 Converter 的速率上限为 50 次/秒。 |
Get | 一个项目中,获取一个指定的 Converter 的速率上限为 50 次/秒。 |
PCW 限制
PCW 限制与你使用旁路推流服务处理的视频流分辨率和所在地区有关,详见下表:
- 中国大陆
- 除中国大陆之外的亚太地区
- 北美
- 欧洲
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
300 | 50 | 20 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 5 | 0 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 5 | 0 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 5 | 0 |
推流路数限制
旁路推流服务支持的最大视频分辨率为 1920 × 1080,帧率为 30 fps。各档位支持推流的路数如下:
- 中国大陆
- 除中国大陆之外的亚太地区
- 北美
- 欧洲
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
300 | 50 | 20 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 5 | 0 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 5 | 0 |
标清 (≤ 640 × 360) | 高清(≤ 1280 × 720) | 全高清(≤ 1920 × 1080) |
---|---|---|
20 | 5 | 0 |
如果你需要同时推多种档位的流,则确保同时满足如下要求:
- 总路数不能超过所支持档位的最大路数,即 Max(标清支持路数, 高清支持路数, 全高清支持路数)。例如,如果你需要在中国大陆使用旁路推流服务既推标清,又推高清,则推流总路数不能超过 300;如果既推高清,又推全高清,则总路数不能超过 50。
- 各档位推流路数不能超过该档位支持的最大路数。
混音人数限制
暂时只支持不超过 3 名用户进行混音。如果参与混音的用户人数大于 3,请联系技术支持。
保障 REST 服务高可用
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供故障迁移和切换域名的方案。
故障迁移
针对网络故障,以及非声网云、非声网软件、设施和不可抗力因素等因素导致的推流中断,声网旁路推流为了保证更好的用户体验,提供自动故障迁移服务,该服务会在尽量短的时间内完成迁移(预计 2 分钟内),迁移期间推流任务中断,可能导致部分数据丢失。 如果对于频道内较多观众端的场景或关键性业务,你需要基于当前业务的重要性和声网提供的自动迁移时效性来考虑是否采用更高的质量保障,例如准备多路流保障以应对迁移期间的快速切换,或者可以采用退避重试策略主动迁移以减少迁移时间。
多路推流任务保障
如需比故障迁移更高的质量保障,你可以采用多路推流任务保障策略。每路推流任务单独计费,计费方式详见旁路推流计费说明。
你可以选择以下两种方式实现多路推流任务保障:
-
同时开启推流主任务和多个备份任务,在每个推流任务中设置不同的 CDN 地址,当主任务发生故障,CDN 观众端可以及时切换到备份的 CDN 地址。
-
如果你想要推送的 CDN 支持优先级功能,你可以开启一个推流任务 1,向优先级为 1 的 CDN 地址(例如:
rtmp://xxx/xxx/xxx?priority=1
)进行推流,如果任务 1 发生故障,及时开启推流任务 2,向优先级为 2 的 CDN 地址进行推流。此时,任务 1 会被 CDN 忽略。
不同 CDN 优先级字段不相同,你需要与 CDN 厂商确认是否支持优先级功能,以及优先级的字段名。
切换域名
切换域名的操作如下:
-
根据你的业务服务器所在地设置主域名:
- 业务服务器 DNS 地址位于中国大陆时,设置主域名为
api.sd-rtn.com
。 - 业务服务器 DNS 地址位于中国大陆以外的国家或地区时,设置主域名为
api.agora.io
。
- 业务服务器 DNS 地址位于中国大陆时,设置主域名为
-
当使用主域名发起 RESTful API 请求失败时,使用该域名重试一次。
-
如果步骤 2 的重试依然失败,使用备用的主域名重试:
- 如果当前设置的主域名为
api.sd-rtn.com
,备用的主域名指api.agora.io
。 - 如果当前设置的主域名为
api.agora.io
,备用的主域名指api.sd-rtn.com
。
- 如果当前设置的主域名为
-
如果步骤 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 | 中国华北 |
启动旁路推流
创建 Converter 注意事项
通过 Create
请求创建一个 Converter 时,你需要关注以下注意事项:
-
你需要通过
region
参数分区域创建 Converter:- 设置的
region
与你的 CDN 源站在同一个区域。 - 传入
region
的值为小写。 - 确保本地服务器覆盖本地推流服务。
- 设置的
-
声网推荐你对请求 Header 中的
X-Request-ID
字段赋值,声网服务器会在响应 Header 中返回一个X-Custom-Request-ID
字段,以用于问题排查。 -
为避免重复创建多个 Converter 导致重复推流,使用
name
字段管理指定项目下的 Converter:- 同一时间,一个项目下不允许出现重名的 Converter,否则在尝试创建同名的 Converter 时会收到响应状态码
409 (Conflict)
。 - 声网推荐你以频道名和 Converter 特性组合来为
name
赋值。例如show68_horizontal
和show68_vertical
,分别代表在频道show68
中创建的用户画面为水平布局和和垂直布局的 Converter。
- 同一时间,一个项目下不允许出现重名的 Converter,否则在尝试创建同名的 Converter 时会收到响应状态码
-
纯音频流或纯视频流场景下
audioOption
和videoOptions
设置如下:- 在纯视频流(无音频)场景中,无需设置
audioOptions
及其相关字段。 - 在纯音频流(无视频)场景中,默认情况下无需设置
videoOptions
及其相关字段。特殊情况请参考纯音频场景中输出 SEI。 - 在音视频场景中,
videoOptions
为必填字段,不可设置为空;audioOptions
为必填字段,可以设置为空。
- 在纯视频流(无音频)场景中,无需设置
-
请设置合理的
idleTimeout
的参数值,推荐使用默认值 300 秒,表示当频道内所有订阅主播都离开频道 300 秒后 Converter 自动销毁,旁路推流停止。
纯音频场景中输出 SEI
在纯音频流(无视频)场景中,默认情况下无需设置 videoOptions
及其相关字段。但是如果你需要在音频流中携带用户的额外信息,例如音量,你可以通过 videoOptions
中的 seiOptions
字段设置 SEI 信息。
如果你想在纯音频场景下输出用户携带的 Metadata 或 DataStream 类型的 SEI 信息,而且不想被收取视频转码费用,那么你需要进行如下设置:
- 在
videoOptions.seiOptions
中传入待输出的 SEI 信息。 - 确保
videoOptions.canvas
中的宽度和高度均设为 16,否则会产生视频转码费用。 - 在
videoOptions.layout
中将携带 SEI 信息的用户的 UID 传入rtcStreamUid
字段中。
更新旁路推流
通过 Update
请求更新指定的 Converter 时,你需要关注以下注意事项:
- 使用查询参数
sequence
对同一个 Converter 进行多次Update
时,请确保sequence
值递增,旁路推流服务会按照最新Update
请求(即最大序列号)更新 Converter。 Update
不支持更新 Converter 的如下配置:name
idleTimeOut
transcodeOptions.rtcChannel
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 次出现 404、5xx 错误码,或查询推流状态响应包体中的 state
字段为 failed
,说明推流失败,请按照以下步骤进行排查:
- 确认 CDN 推流地址是否正确。
- 如果 CDN 推流地址正确,请销毁当前 Converter,并重新创建。
其他异常情况下,旁路推流服务会自动更换推流服务器重新推流。
根据错误码排查
- 如果状态码为
200
,则请求成功。 - 如果状态码不为
200
,则请求失败。请根据对应的响应 Body 中的message
字段内容排查问题。
状态码 | 可能的 message 字段内容 | 原因 | 建议措施 |
---|---|---|---|
200 OK | / | 创建成功 | / |
400 Bad Request |
| 请求参数错误 | 参考 HTTP 响应 Body 中的 reason 字段进行排查。 |
401 Unauthorized | Invalid authentication credentials. | RESTful API 认证失败 | 重新进行 HTTP 基本认证。 |
403 Forbidden | No valid permission to use this function. Contact us. | 未开通服务 | 开通旁路推流 RESTful API 服务。 |
404 Not Found | Resource is not found and destroyed. | 并未成功启动推流任务、启动任务后中途退出、自动迁移中、正在销毁 Converter。 | 采用退避策略重试。 |
409 Conflict | Resource with the same name has already existed. Use the existing resource, otherwise delete it and create a new resource. | 已存在相同名称的 Converter。 | 删除已有 Converter 并重新创建。 |
429 Too Many Requests |
| 并发请求过多 | 采用退避策略重试。 |
500 Unknown | Internal errors. Contact us for troubleshooting. | 服务端内部错误 | 采用退避策略重试。 |
501 Not Implemented | The method requested has not been implemented. | 服务端内部错误 | 采用退避策略重试。 |
503 Service Unavailable |
| 服务端内部错误 | 采用退避策略重试。 |
504 Gateway Timeout | Gateway timeout. Check whether the resource is created, if not, re-create a new resource. | 服务端内部错误 | 采用退避策略重试。 |
联系声网技术支持
如果以上排查方法并未解决问题,请务必在日志中打印出响应 Header 中的 X-Request-ID
和 X-Resource-ID
字段值,并联系声网技术支持。
检查清单
参考以下表格,快速确认每条检查项是否符合集成要求,以保证旁路推流服务的可靠性。
编号 | 重要程度 | 检查项 | 检查内容 |
---|---|---|---|
1 | 必要 | 频道模式 | 所在频道场景为直播。 |
2 | 必要 | 开通服务 | 开通旁路推流 RESTful API 服务。 |
3 | 必要 | QPS 限制条件 | 确保一个项目中,API 的调用速率低于最大限制。详见 API 调用速率限制。 |
4 | 必要 | PCW 限制 | 确保一个项目中,并发任务数低于 300。详见 PCW 限制。 |
5 | 可选 | 管理 Converter | 使用 name 字段管理指定项目下的 Converter,以频道名和 Converter 特性组合来为 name 赋值。 |
6 | 必要 | 区域设置 | 设置的 region 与你的 CDN 源站在同一个区域。传入 region 值为小写。 |
7 | 必要 | 超时逻辑 | 设置合理的 idleTimeout ,推荐设置为 300 秒。 |
8 | 必要 | 更新 Converter | 对同一个 Converter 进行多次 Update 时,sequence 值递增。 |
9 | 可选 | 问题排查 | 请按照如下方案进行问题排查:
|
10 | 可选 | 消息通知 | 开通旁路推流消息通知服务,并监听旁路推流事件。 |