云端录制 RESTful API 快速开始

最近更新时间：2023-04-28 07:20:19

前提条件
开通云端录制服务
API Basic HTTP 认证
实现云端录制
开始录制
查询录制状态
更新订阅名单
更新合流布局
停止录制
上传和管理录制文件
录制文件索引
上传录制文件
开发注意事项
常见调用错误
调用 query 返回 404
其他问题

anyRTC 云端录制提供 RESTful API，业务可以通过发送请求来使用云端录制的功能

  • 提供回调功能，业务配置后就可以收到云端录制的回调通知。
  • 请求仅支持 HTTPS 协议。

回调服务，开通后你会收到云端录制的事件通知。

下表列出回调服务和使用 RESTful API 查询录制状态的区别，你可以根据自己的需要选择是否开通回调服务。

查询状态回调服务
调用 query 方法即可查询需配置用于接收回调的 HTTP 服务器，并单独开通服务
需主动查询，无法保证及时性事件发生时及时通知
仅提供 M3U8 文件名和录制的状态提供云端录制所有的事件通知和具体信息

如需使用回调服务，请参考 RESTful API回调 。

前提条件

开通云端录制服务

首次使用云端录制需要先开通服务，步骤如下：

  1. 登录 控制台，点击左侧导航栏用量统计 按钮进入用量统计页面。
  2. 在页面左上角展开下拉列表选择需要开通云端录制的项目，然后点击云端录制选项。
  3. 点击开启云端录制。
  4. 点击应用。

开通成功后你就可以在用量页面看到云端录制的使用情况。

API Basic HTTP 认证

anyRTC RESTful API 要求 Basic HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入 Authorization 字段。关于如何生成该字段的值，请参考 HTTP 基本认证 。

实现云端录制

云端录制 API 时序图如下。

调用acquire 后，返回的 resource ID，用于记录该录制的整个生命周期，直到调用stop方法结束录制。

查询状态(query)，更新订阅名单(update)，和更新合流布局(updateLayout)都是可选的，且可以多次调用，但是必须在录制过程中（开始录制后到结束录制前）调用。

开始录制

1. 获取 resource ID

在开始录制前，需要调用 acquire 方法请求一个用于云端录制的 resource ID。

调用该方法成功后，你可以从 HTTP 响应包体中的 resourceId 字段得到一个 resource ID。这个 resource ID 的时效为 5 分钟，你需要在 5 分钟内用这个 resource ID 开始录制。

一个 resource ID 仅可用于一次录制。

2. 加入频道

获得 resource ID 后，在五分钟內调用 start 方法加入频道开始录制。

云端录制 UID 字段，请确保跟频道中的其他用户不同，如果跟频道中的用户 UID 一致，会导致该用户退出频道。

调用该方法成功后，你可以从 HTTP 响应包体中获得一个 sid （录制 ID)。该 ID 是一次录制周期的唯一标识，所有的回调中也都包含该录制 ID。

查询录制状态

录制过程中，你可以多次调用 query 方法查询录制的状态。

调用该方法成功后，你可以从 HTTP 响应包体中获得录制生成的索引文件和当前录制的状态。

更新订阅名单

录制过程中， 你可以多次调用 update 方法更新订阅的 UID 名单。详见 设置订阅名单 。

更新订阅名单的场景为特定化需求，比如在某个时候只录制特定人员的音视频信息。

更新合流布局

录制过程中，你可以多次调用 updateLayout 方法设置或更新合流布局。详见 设置合流布局 。

anyRTC 提供了三种合流布局样式：悬浮布局（默认）、自适应布局、垂直布局。如果这三种布局不能满足用户的需求，可以用该方法自定义录制合流布局。

停止录制

调用 stop 方法停止录制。 当频道空闲（无用户）超过预设时间（默认为 30 秒） 后，云端录制也会自动退出频道停止录制。 调用该方法成功后，你可以从 HTTP 响应包体中获得录制生成的索引文件和当前录制上传的状态。

上传和管理录制文件

开始录制后，anyRTC 服务器会将录制内容切片为多个 TS 文件并不断上传至预先设定的第三方云存储，直至录制结束。

录制文件索引

在单流录制模式下，如只录制音频或视频，则每次录制每个 UID 均会生成一个 M3U8 文件；如同时录制音视频，则每次录制每个 UID 会生成两个 M3U8 文件。M3U8文件用于索引该次录制所有的 TS 文件。你可以通过 M3U8 文件播放和管理录制文件。单流模式下 M3U8 文件以及 TS 文件的命名规则详见 管理录制文件 。

上传录制文件

录制文件的上传由 anyRTC 服务器自动完成，你需要关注下面的回调。

RESTful API 回调服务需单独开通，详见 云端录制 RESTful API 回调服务 。

  • 录制过程中:
    uploading_progress：录制开始后约每分钟触发一次，该回调中的 progress ，该参数表示已上传文件占已录制文件的百分比。

  • 停止录制后，根据上传情况，SDK 会触发以下回调之一：
    uploaded：如果录制文件全部成功上传至预先设定的云存储，最后一个录制切片文件上传完成时触发该回调，通知上传完成。

    backuped：如果有录制文件未能成功上传至第三方云存储，anyRTC 服务器会将这部分文件自动上传至 anyRTC 云备份，当录制结束后会触发该回调。anyRTC 云备份会继续尝试将这部分文件上传至设定的第三方云存储。如果等待五分钟后仍然不能正常播放录制文件，请联系 anyRTC 技术支持。

如果上传比较耗时，会在 stop 的响应中收到 HTTP 状态码 206，表示录制已经停止，但是上传状态未知，需要结合回调事件了解上传状态。

开发注意事项

  • 调用 start 之前必须调用 acquire 获取一个 resource ID
  • 一个 resource ID 只可用于一次 start 请求
  • 调用 stop 之后不要再调用 query
  • 调用 start 成功之后可以多次调用 query、update、updateLayout方法

常见调用错误

  • acquire--> start --> start

    用同一个 resource ID 重复调用 start，会收到 HTTP 状态码 201，错误码 7。

  • acquire--> start --> acquire--> start

用相同的参数重复调用 acquire 和 start，会收到 HTTP 状态码 400，错误码 53。

  • acquire--> start --> 停止录制--> query 停止录制后再去调用 query，会收到 HTTP 状态码 404，错误码 404。停止录制有以下几种情况：

    1. 主动调用 stop。
    2. 频道内没有用户超过设定的时间自动停止录制。
    3. 异步检查参数错误导致录制停止，包括 start 请求的 transcodingConfig 和

    storageConfig 中的参数错误。

  • acquire--> start --> stop & query

    调用 stop 的过程中调用 query，会影响 stop 的响应内容：响应的 HTTP 状态码为 206，并且响应中没有 fileList 字段。

调用 query 返回 404

调用 query 方法返回 404，可能由多种原因造成。一个常见的原因为第三方云存储信息有误，如

accessKey 或 secretKey 错误，导致录制文件上传失败。如果你开通了 anyRTC 消息通知服务 ，当你的云存储配置出错时，你会收到 cloud_recording_error 事件的通知。

详见 为什么成功开启云端录制后调用 query 方法返回 404？

其他问题

如果你在集成和使用中遇到其他问题，可以参考以下文档：