集成最佳实践
声网建议你在参考 API 文档集成云端转码服务后,依据本文进行检查,以保障云端转码服务的可靠性。
1. 确保开通服务
开始使用云端转码 RESTful API 前,你需要满足以下条件:
2. 检查服务配额
请检查如下各项服务配额,确保没有超出声网限制。
2.1 峰值并发任务数 PCW
峰值并发任务数(PCW)指最大并发任务数。PCW 限制和你使用云端转码服务处理的视频流分辨率、所在地区有关,详见下表:
服务类型 | 中国大陆 | 亚洲(除中国大陆) | 欧洲 | 美洲 |
---|---|---|---|---|
云端转码 |
|
|
|
|
视频分辨率说明:
- SD:标清视频,分辨率 ≤ 640 × 360
- HD:高清视频,640 × 360 < 分辨率 ≤ 1280 × 720
- FHD:全高清视频,1280 × 720 < 分辨率 ≤ 1920 × 1080
2.2 每秒请求数 QPS
每秒请求数(QPS)上限为 10。
请根据你的 PCW 和查询间隔,预估所需的 QPS。
2.3 转码分辨率和路数限制
云端转码支持处理的视频属性上限为:分辨率 1920 × 1080,帧率 30 fps。
云端转码支持处理的最大流路数详见下表:
服务类型 | 中国大陆 | 亚洲(除中国大陆) | 欧洲 | 美洲 |
---|---|---|---|---|
云端转码 |
|
|
|
|
如果你需要同时转多种档位的流,确保同时满足如下要求:
- 各档位转码路数不能超过该档位支持的最大路数。
- 总路数不能超过所有转码档位支持路数的最大值。
例如,当你需要在中国大陆使用云端转码时,如果你既转标清,又转高清视频,则标清转码路数不能超过 20,高清转码路数不能超过 10,转码总路数不能超过 20;如果你既转高清,又转全高清视频,则高清转码路线不能超过 10,全高清转码路数不能超过 5,转码总路数不能超过 10。
2.4 提升配额
如果你想提升配额,可以联系技术支持。
3. 保障服务高可用
为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供故障迁移、多路任务保障、切换域名的方案。
3.1 故障迁移
针对网络故障,以及非声网云服务,非声网软件,基础设施和不可抗力等因素可能导致的风险,声网云端转码服务为提升用户体验,提供高可用自动任务迁移服务。当故障确认后,该服务会在尽量短的时间(预计 90 秒内)完成迁移,在此期间会存在转码中断等风险。
对于频道内观众较多或对高可用有极高要求的场景,你需要根据业务需求判断能否接受高可用迁移的影响,决定是否要采用更高的质量保障措施。例如,使用多个不同的 uid
(在输出频道内)发起多路转码任务,或通过周期性频道查询和消息通知服务了解转码任务状态,以便在发生故障时及时使用备用 uid
重新发起新的转码任务,从而确保关键任务顺利完成。
3.2 多路任务保障
如需比故障迁移更高的质量保障,你可以采用多路任务保障策略。每路云端转码任务单独计费,计费方式详见计费说明。实现步骤如下:
-
同时发起主任务和备份任务,针对相同的主播源流进行转码,并向同一频道或不同频道推送转码输出的流,观众端订阅主任务中的输出频道内的
uid
。 -
在客户端监听以下回调事件,可以及时通知观众端订阅备份任务中的
uid
:-
主播掉线回调
onUserOffline
-
主播音视频状态变化回调
onRemoteAudioStateChanged
/onRemoteVideoStateChanged
-
3.3 切换域名
切换域名的操作如下:
-
根据你的业务服务器所在地设置主域名:
- 业务服务器 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 | 中国华北 |
4. 检查服务状态
你可以通过云端转码 RESTful API 和消息通知服务来获取转码服务状态。
4.1 检查服务启动状态
建议你通过如下步骤检查转码服务是否已成功启动:
4.1.1 检查 Acquire 和 Create 的调用方式
检查你是否在每次 Acquire
请求获取到 builderToken
后的 2 秒内都立即发起对应的 Create
请求。
如果你批量获取 builderToken
,再进行批量 Create
请求,可能会请求失败。
4.1.2 检查 Create 请求结果
如果 Create
请求响应的 HTTP 状态码为 200
,则请求成功。如果 Create
请求响应的 HTTP 状态码非 200
,则需要根据状态码采取相应措施:
- 如果返回的 HTTP 状态码为
206
,则表示请求超时,建议使用退避策略,如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试,以免超过 QPS 限制导致失败。如果三次重试均失败,建议更换 UID 再次调用Acquire
, 获得一个新的builderToken
,并用该builderToken
再次调用Create
方法。 - 如果返回的 HTTP 状态码为
409
,则表示转码任务已成功启动并在进行中,无需重试。 - 如果返回的 HTTP 状态码为
40x
(409
除外),则表示请求参数错误,需要进行排查。 - 如果返回的 HTTP 状态码为
50x
,可使用相同的参数重试多次,直到成功返回taskId
为止。建议使用退避策略,如第一次等待 3 秒后重试、第二次等待 6 秒后重试、第三次等待 9 秒后重试,以免超过 QPS 限制导致失败。如果三次重试均失败,建议更换 UID 再次调用Acquire
, 获得一个新的builderToken
,并用该builderToken
再次调用Create
方法。 - 如果收到错误码
65
,需要使用相同的参数再次调用Create
。建议使用退避策略重试两次,如第一次等待 3 秒后重试、第二次等待 6 秒后重试。
4.1.3 查询转码服务状态
Create
请求成功后,你会获得 taskId
。获得 taskId
之后的 5 秒后,使用退避策略调用 Query
方法,退避间隔建议小于 Create
请求中的 idleTimeout
(最长空闲频道时间)。如果 Query
请求成功,且 serverResponse
中的 status
参数值为 4
或 5
,则表示 cloud transcoder 已成功启动。如果在获得 taskId
之后的 90 秒后 status
仍非 4
或 5
, 则可以认为 cloud transcoder 在创建后未成功启动,超时退出。
频道内用户 UID 不能冲突,因此建议你为 cloud transcoder 准备一个备用 UID,以便在重新发起新的转码任务时使用。主用 UID 和备用 UID 可以交替使用。
4.2 检查 status 字段
以下是所有的转码服务状态(services.cloudTranscoder.status
):
服务状态 | 描述 |
---|---|
"serviceIdle" | 服务未开始。 |
"serviceStarted" | 服务已开始。 |
"serviceReady" | 服务已就绪。 |
"serviceInProgress" | 服务正在进行中。 |
"serviceCompleted" | 服务已经停止,任务全部完成。 |
"servicePartialCompleted" | 服务已经停止,任务部分完成。 |
"serviceValidationFailed" | 服务参数验证失败。 |
"serviceAbnormal" | 服务异常退出。 |
"serviceUnknown" | 服务未知状态。 |
4.3 监控转码任务状态
本节介绍监控转码任务状态的两种方式:
- 主要方式:周期性查询状态。
- 辅助方式:使用消息通知服务。
方式对比详见消息通知服务和 query 方法的对比。
4.3.1 周期性查询状态
你可以通过周期性调用 Query
方法来确认转码服务正在进行中且状态正常。如果你对状态查询的可靠性要求较高,声网强烈建议你使用 Query
方法周期性查询频道内的转码状态,例如每隔 2 分钟调用一次 Query
,并根据返回的 HTTP 状态码采取相应措施。
- 如果返回的 HTTP 状态码一直为
40x
,则表示请求参数错误,需要进行排查。 - 如果返回的 HTTP 状态码为
404
,且已经确认请求参数无误,则表示 cloud transcoder 并未成功启动、或启动后中途退出。建议采用退避策略多次调用Query
(例如间隔 5 秒、10 秒、15 秒)进行确认。 - 如果返回的 HTTP 状态码为
50x
,则表示Query
请求失败,但尚不明确 cloud transcoder 是否已退出。出现50x
错误的概率极小,建议使用退避策略 (例如间隔 5 秒,10 秒,15 秒,30 秒) 继续调用Query
。
4.3.2 使用消息通知服务
消息通知服务可以辅助监听云端转码的状态。为了避免消息投递时丢失,建议你开通该服务的冗余消息通知功能。开通后,你需要基于 taskId
对消息进行去重。举例来说,如果你需要在 cloud transcoder 超时退出后再次开启,消息去重的逻辑为:
- 你的服务器收到
111
事件,表示转码服务已正常退出。 - 收到步骤 1 的
111
事件后,你调用Acquire
重新开启转码服务。 - 在重新开启转码期间,你的服务器又收到了
111
事件。如果该事件和步骤 1 收到的111
事件对应的taskId
一致,则可以将该事件通知当冗余通知,可忽略。
如果你需要完全确认转码服务已成功开启,则还需调用 Query
进行查询。
- 消息通知服务需要联系技术支持开通。
- 冗余消息功能仍然不能保证 100% 的消息到达率。
5. 避免转码服务频繁退出
Create
方法中的 idleTimeout
参数默认值为 300 秒。对于要求 cloud transcoder 一直在频道中的场景,为避免 cloud transcoder 因主播频繁上下线而频繁启动和退出,你需要在设置 idleTimeout
取值时权衡实际场景,避免取值过小。合适的取值可以保证转码服务在短时间无发流端时也能稳定运行,避免转码服务频繁退出。
6. 根据错误码排查
本节列出使用云端转码服务发起请求时,你可能会收到的所有响应状态码:
状态码 | 含义和建议措施 |
---|---|
200 OK | 请求成功。 |
废弃 201 Created | 任务已经在进行中,请勿用同一个 builderToken 重复开启任务。 |
202 Accepted | 服务端已经收到任务请求,但未执行完成。请通过 Query 方法查询执行状态。 |
400 Bad Request | 请求的语法错误。可能是参数取值不符合要求,也可能是你的 App ID 未开通云端转码服务。请结合响应 Body 中的 message 字段进行排查。 |
401 Unauthorized | 用于 HTTP 基本认证的 Authorization 字段无效。详见实现 HTTP 基本认证。 |
403 Forbidden | 你的 App ID 尚未开通云端转码服务,请联系技术支持开通。 |
404 Not Found | 找不到 cloud transcoder。 |
409 Conflict | 已存在重名 instanceId 的 cloud transcoder 任务。如果你想创建新的 cloud transcoder,请先将旧的 cloud transcoder 删除。 |
429 Too Many Requests | 请求速率超过上限。 |
500 Unknown | 声网服务器内部错误,请联系技术支持。 |
501 Not Implemented | 该方法未实现。 |
503 Service Unavailable | 声网服务器暂时超载或在临时维护中。请使用重试机制或联系技术支持。 |
504 Gateway Timeout | 声网服务器内部错误,充当网关或代理的服务器未从上游服务器获取请求,上游服务器已关闭。请联系技术支持。 |
使用云端转码响应状态码进行问题排查时,你需要了解如下注意事项:
- 请不要对响应 Body 里的
message
字段的内容做任何逻辑处理,如果请求失败请结合状态码排查问题。 202
的状态码仅表示服务端已经收到任务请求,但不代表执行完成,需要继续通过Query
方法查询执行状态来判断任务是否执行完成。- 收到
404
的状态码后,如果Create
请求已返回成功且没有主动调用Delete
方法,或者 cloud transcoder 的空闲状态超过请求参数中的idleTimeout
字段,建议采取退避算法(例如间隔 5 秒、10 秒、15 秒)调用Query
方法进行确认。 - 收到
5XX
的响应状态码后,一般是服务端在响应的过程中出现了问题,建议采取退避算法(例如间隔 5 秒、10 秒、15 秒)调用Query
请求进行确认。