跳到主要内容

状态回调

云端录制在开始录制、文件切片、录制结束、上传的时候均提供 HTTP 录制状态回调，您可以拿到录制元信息和录制文件名、录制文件最终 URL 的对应关系。如果您已开通「云端录制」服务，并配置了公网可访问的回调 URL，融云会将录制的状态变化实时通知您在控制台配置的服务器地址。

请在控制台的云端录制页面，填写接收 HTTP 回调的 URL，配置后 30 分钟内生效。

回调方法​

POST：<your-receiving-server-url>

数据格式：application/json

回调地址 <your-receiving-server-url> 是您在控制台为当前 App Key 和服务所配置的回调接收地址。请务必配置可正常访问的回调接收地址。如果您的网络有 IP 访问限制，请务必配置 IP 白名单，否则无法正常接收服务端回调。

为了验证数据有效性并确保调用者为融云 Server，每个请求前添加数据签名。回调签名规则详见服务端回调。

状态回调公共字段​

下表描述了云端录制服务不同状态的 HTTP 回调请求结果（JSON 对象）中的公共字段：

字段名称类型说明
timestampNumber时间戳，单位为毫秒。
typeNumber回调事件类型，如下：
1: 录制开始；
2: 录制切片；
3: 录制结束；
4: 文件上传
appKeyString当前使用的 App Key。
recordIdString录制 ID，每次录制任务的唯一标识。如果文件切片，可以通过此 ID 进行关联。
roomIdString房间 ID 。
sessionIdString会话 ID，每次通话的唯一标识。您可以通过融云服务端回调获取该 sessionId，请参见房间状态同步。
userIdString用户 ID。如果录制模式为 Mix，此字段为空。
modeNumber录制模式，如下：
0：音视频 single 模式；
1：纯视频 single 模式；
2：纯音频 single 模式；
3：音视频 mix 模式；
4：纯视频 mix 模式；
5：纯音频 mix 模式；
6：单人 mix 音视频模式。
详见知识库文档配置云端录制服务中的录制模式详解
extraString扩展字段，内容为手动录制时传入的 extra 字段的值。
codeNumber状态码，200 为正常。
errorMessageString错误信息。

云端录制服务不同状态专属的回调字段请参见下文。

录制开始的回调​

云端录制服务会在录制开始时，回调此次录制任务的模式、配置、封装文件格式等信息。

录制开始回调的专属字段类型说明
config.triggerNumber录制启动模式: 1 自动启动录制任务
config.mixLayoutNumberMix模式下布局：2 悬浮布局(默认) 3 自适应布局
config.slicesMinNumber文件切片时间（分钟）
config.audioFormatString设置的音频文件格式
config.videoFormatString设置的视频文件格式
output.fileNameString缓存的文件名。具体请参考下文中的切片文件命名规则。
output.audioSampleNumber音频采样率，如 48000。如果当前录制任务没有录制音频，该字段为空。
output.videoResoulationString视频分辨率，如 640x480。如果当前录制任务没有录制视频，该字段为空。

回调请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":1,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "config":{
        "trigger":0,
        "mixLayout":2,
        "slicesMin":30,
        "audioFormat":"aac",
        "videoFormat":"mp4"
    },
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "audioSample":48000,
        "videoResoulation":"640x480"
    },
    "code": 200,
    "errorMessage": "Success"
}

录制切片的回调​

当录制任务的时长大于切片时长时，会将缓存的所有音视频数据封装成一个完整的文件并上传。

切片完成时会回调相关信息，具体字段说明如下。

录制切片回调的专属字段类型说明
output.fileNameString缓存的文件名。文件名规则见「配置云端录制服务」中的切片文件命名规则。
output.fileSizeNumber切片生成的录制文件大小。

回调请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":2,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "fileSize":333
    },
    "code": 200,
    "errorMessage": "Success"
}

录制结束的回调​

云端录制服务在录制完成时会回调相关信息，具体字段说明如下。

录制结束回调的专属字段类型说明
output.fileNameString缓存的文件名。文件名规则见「配置云端录制服务」中的切片文件命名规则。
output.fileSizeNumber切片生成的录制文件大小。

回调请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":3,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "fileSize":333
    },
    "code": 200,
    "errorMessage": "Success"
}

上传文件的回调​

云端录制服务录制完成时会自动上传到您配置的第三方存储。上传成功或失败都会回调相关状态。

上传文件回调的专属字段类型说明
output.fileNameString缓存的文件名。文件名规则见「配置云端录制服务」中的切片文件命名规则。
output.fileUrlString已上传到的第三方存储的 URL。

回调请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":4,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "fileUrl":"http://oss/record/XXXXXXXX.mp4?abc"
    },
    "code": 200,
    "errorMessage": "Success"
}

切片文件命名规则​

注意

以下命名规则仅供参考，不建议您解析具体字段。

录制模式命名规则说明
mix 模式SessionId_RoomId_时间戳.文件格式

例：1K6-Q3uj6w7cfbGSq0ahA9_1775_1577616009233.mkv
single 模式SessionId_RoomId_UserId_StreamTag_时间戳.文件格式

例：1K6-Q3uj6w7cfbGSq0ahA9_1775_123456_RongCloudRTC_1577616009233.mkv
单人 mix 音视频模式SessionId_RoomId_UserId_时间戳.文件格式

例：1K6-Q3uj6w7cfbGSq0ahA9_1775_123456_1577616009233.mkv

字段说明

切片文件名字段说明
SessionId当前通话的会话 ID。如果使用 RTCLib，可以在创建房间后从房间对象上获取。如果使用 CallLib，可以在建立通话后从当前 call sesion 上获取。
RoomId通话所在的房间 ID。
如您使用 RTCLib，RoomId 为加入房间方法的入参；
如您使用 CallLib，可以通过 getCallId 接口获取 RoomId。
UserId通话的用户 ID。
StreamTag用户发布自定义视频或屏幕共享时，客户端给流设置的 Tag 字段。
时间戳Unix 时间戳，单位为毫秒。

响应回调请求​

您的服务在收到 HTTP 回调之后，需要返回 200 OK 表示接收成功。

回调状态码说明：

  • 当第三方存储服务出现故障时，录制的文件会在融云录制服务器上暂存，并会每隔 10s 重试一次。融云暂存时间最长为 24 小时，超出后暂存数据会被清除。
  • 建议在您收到失败回调后检查第三方存储的服务状态。如服务商出现故障，您可以及时配置为新的存储单元，降低您的损失（配置生效时间为 30 分钟）。
最后于 更新