实现云端录制
本文介绍如何通过发送 RESTful API 请求开始云端录制、查询云端录制状态以及结束云端录制。
技术原理
实现云端录制的完整流程如下所示：
1. 获取 resource ID
在开始录制前，必须调用 acquire 方法获取云端录制资源。调用该方法成功后，你可以在响应包体中得到一个 resource ID。
2. 开始录制
调用 start 方法加入频道开始录制。调用该方法成功后，你可以从响应包体中获得一个录制 ID，标记当前录制进程。
3. 查询录制状态
在整个录制过程中调用 query 方法查询云端录制的状态。
4. 结束录制
调用 stop 方法停止录制。
5. 上传录制文件
录制结束后，云端录制服务上传录制文件到你指定的第三方云存储。
前提条件
- 有效的声网账户。
- 有效的声网项目，获取项目的 App ID，并生成一个临时 Token。详情请参考开始使用声网平台。
- 可以访问互联网的计算机。如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。
- 请确保已开通第三方云存储服务。目前仅支持公有云，支持的第三方云存储服务商如下：
- 请确保频道内有用户且正在发流。
示例项目
声网在 GitHub 上提供一个 Postman collection，包含了云端录制 RESTful API 的所有示例请求。你只需将该 collection 导入 Postman，并设置环境变量，便可快速体验云端录制 RESTful API 的基本功能。
你还可以使用 Postman 自动生成各种语言的代码片段。选择某个请求，点击 Code，在 GENERATE CODE SNIPPETS 窗口选择你需要的语言，即可生成该语言的示例代码。
开通云端录制服务
第一次使用云端录制首先需要开通服务，步骤如下：
- 登录控制台，在项目管理页面，选择需要开通输入云端录制的项目，点击编辑按钮进入编辑项目页面。
- 在编辑项目页面的实时互动拓展能力模块找到云录制，点击启用。
- 点击开启云端录制。
- 点击应用。
开通成功后你可以在产品用量页面看到云端录制的使用情况。
实现云端录制
下图为实现云端录制需要调用的 API 时序图。
查询录制状态（query）、更新订阅名单（update）和更新合流布局（updateLayout）均为可选，且可多次调用，但须在录制过程中，即开始录制后到结束录制前调用。
通过 Basic HTTP 认证
云端录制 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。
acquire：获取云端录制资源
在开始录制前，必须先调用 acquire 方法获取一个云端录制 resource ID。
调用该方法成功后，你可以在响应包体中得到一个 resource ID。resource ID 的时效为 5 分钟，你需要在 5 分钟内使用该 resource ID 开始录制。一个 resource ID 仅可用于一次录制。
- 录制服务相当于频道中一个不发流的客户端。请求包体中的
uid参数用于标识录制服务，不可与频道内的任何已有 UID 重复。例如，如果频道内已有两个用户，UID 分别为 123 和 456，则uid不可为"123"或"456"。 - 云端录制不支持 String 用户 ID（User Account）。请确保频道内所有用户均使用整型 UID。
uid参数的字符串内容也必须为整型。
示例代码
你可以使用命令行工具发送以下命令调用 acquire 方法。
# 将 <appid> 替换为你的声网项目的 App ID
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/acquire' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
# 将 <YourChannelName> 替换为你需要录制的频道名称
"cname": "<YourChannelName>",
# 将 <YourRecordingUID> 替换为你标识该录制服务的 UID
"uid": "<YourRecordingUID>",
"clientRequest": {}
}'start：开始录制
获得 resource ID 后，在五分钟內调用 start 方法加入频道开始录制。你可以选择录制模式为单流录制或合流录制。
调用该方法成功后，你可以从响应包体中获得一个 sid （录制 ID)。该 ID 是一次录制周期的唯一标识。
示例代码
你可以使用命令行工具发送以下命令，调用 start 方法。
# 将 <appid> 替换为你的声网项目的 App ID
# 将 <resourceid> 替换为通过 acquire 方法获取的 resource ID
# 将 <mode> 替换为 individual（单流录制）或 mix（合流录制）
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
# 将 <YourChannelName> 替换为你需要录制的频道名称
"cname": "<YourChannelName>",
# 将 <YourRecordingUID> 替换为你标识该录制服务的 UID
"uid": "<YourRecordingUID>",
"clientRequest": {
# 将 <YourToken> 替换成你在控制台获取的临时 Token
"token": "<YourToken>",
# 设置云存储相关参数
"storageConfig": {
"secretKey": "<YourSecretKey>",
"vendor": 0,
"region": 0,
"bucket": "<YourBucketName>",
"accessKey": "<YourAccessKey>"
},
# 设置录制相关参数
"recordingConfig": {
# 确保与声网 RTC SDK 的设置一致
"channelType": 0
}
}
}'query：查询录制状态
录制过程中，你可以多次调用 query 方法查询录制的状态。
调用该方法成功后，你可以从响应包体中获得当前录制的状态和录制文件的相关信息。你可以参考云端录制最佳集成实践来实现录制过程中的服务状态监控和获取 M3U8 文件名。
示例代码
你可以使用命令行工具发送以下命令，调用 query 方法。
# 将 <appid> 替换为你的声网项目的 App ID
# 将 <resourceid> 替换为通过 acquire 方法获取的 resource ID
# 将 <sid> 替换为通过 start 方法获取的 sid
# 将 <mode> 替换为 individual（单流录制）或 composite（合流录制）
curl --location --request GET 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \stop：停止录制
调用 stop 方法停止录制。
调用该方法成功后，你可以从响应包体中获得录制文件上传的状态和录制文件的信息。
示例代码
你可以使用命令行工具发送以下命令，调用 stop 方法。
# 将 <appid> 替换为你的声网项目的 App ID
# 将 <resourceid> 替换为通过 acquire 方法获取的 resource ID
# 将 <sid> 替换为通过 start 方法获取的 sid
# 将 <mode> 替换为 individual（单流录制）或 mix（合流录制）
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-type: application/json;charset=utf-8' \
--data-raw '{
# 将 <YourRecordingUID> 替换为你标识该录制服务的 UID
"uid": "<YourRecordingUID>",
# 将 <YourChannelName> 替换为你正在录制的频道名称
"cname": "<YourChannelName>",
"clientRequest": {}
}'后续步骤
管理录制文件
开始录制后，声网服务器会将录制内容切片为多个 TS/WebM 文件并不断上传至预先设定的第三方云存储，直至录制结束。你可以参考管理录制文件了解录制文件的命名规则、文件大小以及切片规则。
Token 鉴权
为保障通信安全，在正式生产环境中，你需要在自己的 app 服务端生成 Token。详见使用 Token 鉴权。
开发注意事项
参数设置
- 如果请求包体中的
uid参数与频道内的 UID 重复、或使用了非整型 UID，均会导致录制失败。详见获取云端录制资源一节中关于uid参数的注意事项。 start请求返回200后，仅代表 RESTful API 请求成功。要确保录制成功启动并正常进行，你还需要调用query查询录制状态。transcodingConfig参数设置不合理、第三方云存储信息有误、token 信息有误等均会导致query方法返回 404。详见为什么成功开启云端录制后调用 query 方法返回 404？。- 请结合你的实际业务需求合理设置
maxIdleTime。在maxIdleTime设置的时间范围内，即使频道空闲，录制仍会持续进行，并产生计费。
API 调用
- 获得 resource ID 后，必须在 5 分钟内调用
start方法开始录制，超时后需要重新请求一个 resource ID。 - 从获得
sid（录制 ID）起，超过resourceExpiredHour设定的时间后，你将无法调用query，updateLayout和stop方法。
故障迁移
针对网络故障，以及非声网云服务，非声网软件，基础设施和不可抗力等因素可能导致的风险，声网云录制为了更好的用户体验，提供高可用自动任务迁移服务。当故障确认后，该服务会在尽量短的时间（预计 90 秒内）完成，在此期间会存在录制中断，录制文件丢失等风险。
对于频道内较多观众端或对高可用要求极高场景，你需要基于自身业务特点综合考虑能否接受高可用迁移影响，决策是否要采用更高的质量保障措施，例如关键任务多路录制（使用不同 uid 发起多路录制任务），或通过周期性频道查询和消息通知服务获知录制任务状态，及时重新发起录制任务。
