停止云端录制

更新时间

停止一个云端录制任务。

POST
https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop

stop 方法用于停止云端录制。

开始录制后,你可以调用 stop 方法离开频道,停止录制。录制停止后如需再次录制,必须再调用 acquire 方法请求一个新的 Resource ID。

注意

  • stop 请求仅在会话内有效。如果录制启动错误,或录制已结束,调用 stop 将返回 404。
  • 非页面录制模式下,当频道空闲(无用户)超过预设时间(默认为 30 秒) 后,云端录制也会自动退出频道,停止录制。
  • 录制结束后,正常情况下录制文件会在 20 分钟内上传至第三方云存储,但在网络异常等特殊情况下上传时间会达到 24 小时以上。

路径参数

appidstring
必填

你的项目使用的 App ID。

  • 对于页面录制模式,只需输入开通了云端录制服务的 App ID。
  • 对于单流和合流录制模式,必须使用和待录制的频道相同的 App ID,且该 App ID 需要开通云端录制服务。
resourceidstring
必填

通过 acquire 请求获取到的 Resource ID。

sidstring
必填

通过 start 获取的录制 ID。

modestring
必填

录制模式:

请求 Header

Authorizationstring
必填

声网云端录制 RESTful API 仅支持 HTTPS 协议。发送请求时,你需要使用声网提供的客户 ID 和客户密钥生成 Base64 编码凭证,并填入请求头部的 Authorization 字段中。详见实现 HTTP 基本认证。

Content-Typestring

application/json。

请求 Body

字段
cnamestring
必填

录制服务所在频道的名称。需要和你在 acquire 请求中输入的 cname 相同。

uidstring
必填

字符串内容为录制服务在 RTC 频道内使用的 UID,用于标识该录制服务,需要和你在 acquire 请求中输入的 uid 相同。

async_stopboolean

设置 stop 方法的响应机制:

  • true:异步。调用 stop 后立即收到响应。
  • false:同步。调用 stop 后,你需等待所有录制文件上传至第三方云存储方后会收到响应。声网预期上传时间不超过 20 秒,如果上传超时,你会收到错误码 206。

响应

如果返回的 HTTP 状态码为 200,表示请求成功。

响应 Body

字段
resourceIdstring

云端录制使用的 Resource ID。

sidstring

录制 ID。标识一次录制周期。

cnamestring

录制的频道名。

uidstring

字符串内容为云端录制服务在 RTC 频道内使用的 UID,用于标识频道内的录制服务。

请求示例

curl --request POST \
  --url "https://api.sd-rtn.com/v1/apps/:appid/cloud_recording/resourceid/:resourceid/sid/:sid/mode/:mode/stop" \
  --header 'Authorization: Basic <credentials>' \
  -H 'Content-Type: application/json' \
  -d '{
  "cname": "<your_channel_name>",
  "uid": "<unique_user_id>",
  "clientRequest": {
    "async_stop": false
  }
}'

响应示例

{
  "resourceId": "云端录制使用的 Resource ID。",
  "sid": "录制 ID。标识一次录制周期。",
  "serverResponse": {
    "extensionServiceState": [
      {
        "playload": {
          "uploadingStatus": "当前录制上传的状态:\n- `\"uploaded\"`:本次录制的文件已经全部上传至指定的第三方云存储。\n- `\"backuped\"`:本次录制的文件已经全部上传完成,但是至少有一个 TS 文件上传到了声网备份云。声网服务器会自动将这部分文件继续上传至指定的第三方云存储。\n- `\"stranded\"`:v2 新增状态。部分录制文件尚未上传至指定的第三方云存储,录制服务会继续自动重试上传,直至上传成功。该状态不表示文件丢失,业务侧应将其视为“上传未完成”,等待文件上传完成后再进行依赖完整录制文件的播放或处理。\n- `\"unknown\"`:未知状态。"
        },
        "serviceName": "服务类型:\n- `\"upload_service\"`:上传服务。\n- `\"web_recorder_service\"`:页面录制服务。"
      }
    ]
  },
  "cname": "录制的频道名。",
  "uid": "字符串内容为云端录制服务在 RTC 频道内使用的 UID,用于标识频道内的录制服务。"
}