文档中心
云端录制
Console Agora.io 社区 提交工单
简体中文
search-icon

获取云端录制资源

更新时间 2022/06/16 10:51:41

在开始云端录制之前，你需要调用 acquire 方法获取一个 resource ID。一个 resource ID 只能用于一次云端录制服务。

  • 方法：POST
  • 接入点：/v1/apps/<appid>/cloud_recording/acquire

对于每个 Agora 账号， 每秒钟的请求数限制为 10 次。如需提高此限制，请提交工单联系技术支持。

  • 调用该方法获取的 resource ID 的时效为 5 分钟，你需要在 5 分钟内使用该 resource ID 去调用 start 方法开始云端录制，如果超时则需要重新获取。
  • 如需开启多个录制进程，声网建议你按照 acquire - start 的调用顺序逐个开启，请勿多次调用 acquire 获取多个 resource ID 而导致资源过期。

    • HTTP 请求

    该 API 需要在 URL 中传入以下参数。

    参数 类型 描述
    appid String 你的项目使用的 App ID。
    • 对于页面录制，只需输入开通了云端录制服务的 App ID。
    • 其他情况下，必须使用和待录制的频道相同的 App ID，且该 App ID 需要开通云端录制服务。

    该 API 需要在请求包体中传入以下参数：

    参数 类型 描述
    cname String
    • 非页面录制模式下，该参数用于设置待录制的频道名。
    • 对于页面录制，该参数用于区分录制进程。字符串长度不得超过 128 字节。通过 appid, cname 以及 uid 可以定位一个唯一的录制实例。如果你想多次录制同一个页面，可以使用相同的 cname 和不同的 uid 来进行组织和区分。
    uid String 字符串内容为云端录制服务在频道内使用的 UID，用于标识该录制服务，例如"527841"。需满足以下条件：
    • 取值范围 1 到 (232-1)，不可设置为 0。
    • 不能与当前频道内的任何 UID 重复。
    • 云端录制不支持 String 用户 ID（User Account），请确保该字段引号内为整型 UID，且频道内所有用户均使用整型 UID。
    clientRequest JSON 特定的客户请求参数，对于该请求包含以下参数：
    • region：（选填）String 类型，用于限定云端录制服务访问的区域。一旦指定了访问区域，云端录制服务将不会访问指定区域以外的服务器。区域可设为："CN"（中国大陆），"AP"（除中国大陆以外的亚洲区域），"EU"（欧洲），"NA"（北美）。
    • resourceExpiredHour：（选填）Number 类型，单位为小时，用于设置云端录制 RESTful API 的调用时效，从成功开启云端录制并获得 sid （录制 ID）后开始计算。
      • 超时后，你将无法调用 query，update，updateLayout 和 stop 方法。
      • 超时后录制不会自动停止，最大录制时长为你通过 start 方法中的 maxRecordingHour 参数设置的值。
      • resourceExpiredHour 需大于等于 1， 且小于等于 720，默认值为 72。
    • scene：（选填）Number 类型，用于设置云端录制资源使用场景：
      • 0：（默认）实时音视频录制或延时混音：
        • 实时音视频录制：录制服务会在录制结束后将录制文件实时上传至你指定的第三方云存储。
        • 延时混音：录制服务会在录制结束后 24 小时内将指定频道内所有 UID 的录制文件合并并转码生成一个 MP3/M4A/AAC 文件，并将文件上传至你指定的第三方云存储（不支持七牛云）。该场景仅适用于音频单流不转码录制模式。
      • 1：页面录制。
      • 2：延时转码。设置该场景后，录制服务会在录制后 24 小时内对录制文件进行转码生成 MP4 文件，并将 MP4 文件上传至你指定的第三方云存储（不支持七牛云）。该场景仅适用于单流录制模式。你需要同时在 start 方法中设置 appsCollection 参数。
    目前仅支持在中国内陆地区使用延时转码功能，即你发起请求的应用服务器必须在中国大陆地区，且调用 start 方法时第三方云存储的 region 必须设置为中国大陆区域内。

    请求示例

    • 请求 URL：
    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire
    • Content-type 为 application/json;charset=utf-8
    • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。
    • 请求包体内容：
    {
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "region": "CN",
        "resourceExpiredHour": 24
    }
}

    HTTP 响应

    如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

    • code: Number 类型，详见响应状态码。
    • resourceId: String 类型，云端录制资源 resource ID，使用这个 resource ID 可以开始一段云端录制。这个 resource ID 的有效期为 5 分钟，超时需要重新请求。

    响应示例

    "Code": 200,
"Body":
{
    "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}