文档中心
云端录制旧版文档
API 文档
录制结束回调

录制结束回调

更新时间：2023-09-18 15:54

1 描述

通过主动调用 query 方法可以查询录制任务和文件的状态，如需要第一时间获知任务结束事件，需要在开通云端录制服务时提供回调地址。

录制任务结束后会以 POST 方式向回调地址发起 HTTP 请求，请求包体为 JSON 格式。

2 回调参数

参数	类型	描述
app_id	Int64	ZEGO 给开发者分配的 AppID，唯一标识一个应用。
task_id	String	录制任务 ID，长度固定为 16 个字节的字符串。
room_id	String	录制房间 ID。
event_type	Int	事件通知数型。 1：录制正常结束，所有录制文件上传成功。 2：录制异常结束，部分录制文件上传失败（file_info 中有至少一个文件状态不为 3）。 3：录制正常结束，没有产生录制文件（房间内没有用户推流）。
message	String	事件描述。
nonce	String	随机数，用于检验串计算。
timestamp	String	回调发送时的 Unix 时间戳，用于检验串计算。
signature	String	检验串，验证回调发送方身份。
sequence	Int	消息序列号，从 0 开始计数。只有使用视频截图功能时会返回该字段。
file_info	Array of Object	文件信息。列表为空表示没有产生录制文件（房间内没有用户推流）。

file_info成员如下：

参数	类型	描述
user_id	String	录制流对应的推流用户 ID（混流时，为 mix_output_stream_id）。
user_name	String	录制流对应的推流用户昵称（混流时，为 mix_output_stream_id）。
stream_id	String	录制流对应的流 ID（混流时，为 mix_output_stream_id）。
file_id	String	请参考开始录制中的 output_file_rule 参数。
video_id	String	阿里云 Vod、腾讯云 Vod 上传成功得到的视频 ID 参数。阿里云 Vod 对应的是 VideoId，腾讯云 Vod 对应的是 FileId。
file_url	String	文件访问 URL。第三方存储为七牛云或阿里云 Vod 时不返回。
output_file_format	String	输出录制文件的格式，包括 “mp4”、“flv”、“hls”、“aac” 和 “jpg”。
file_size	Int64	文件大小，单位：字节。
duration	Int	文件时长，单位：ms。
resolution_width	Int	视频分辨率宽，单位：像素。
resolution_height	Int	视频分辨率高，单位：像素。
media_track_type	Int	文件媒体类型。 1：只有音频 2：只有视频 3：音视频
begin_timestamp	Int64	接收到房间流新增信令时的 Unix 时间戳，单位：ms。
custom_begin_timestamp	Int64	用户自定义时间戳，该时间戳带在流 SEI 信息中，按照约定的协议从 SEI 中解析。
status	Int	文件状态。 1：录制中，表示正在录制文件。 2：上传中，表示正在上传录制文件至客户指定云存储。 3：上传成功，表示上传录制文件至客户指定云存储成功。 4：已经上传至备份云存储，表示上传客户指定云存储失败，已上传至 ZEGO 备份云存储。 5：上传失败，表示上传客户指定云存储和 ZEGO 备份云存储均失败。

3 回调示例

以下是录制结束回调的请求示例。

{
    "app_id": 0000,
    "task_id": "X3CgNeE4I1qAAABN",
    "room_id": "xxxx",
    "event_type": 1,
    "message": "succeed",
    "nonce": "445266",
    "timestamp": "1611557246",
    "signature": "23485d0bd35c2dba6211bf3837a732640b4c64e4",
    "file_info": [
        {
            "user_id": "my_out",
            "user_name": "my_out",
            "stream_id": "my_out",
            "file_id": "X3CgNeE4I1qAAABN_xxxx_my_out_VA_20200927154419775.mp4",
            "video_id": "820e50e52e0a490caf44eec8aec527a7",
            "output_file_format": "mp4",
            "duration": 33874,
            "media_track_type": 3,
            "begin_timestamp": 1601221459830,
            "custom_begin_timestamp": 0,
            "status": 3,
            "file_url": "https://xxxx.oss-cn-shanghai.aliyuncs.com/record/X3CgNeE4I1qAAABN_xxxx_my_out_VA_20200927154419775.mp4"
        }
    ]
}

4 来源校验

校验回调请求的发起来源是否为 ZEGO 云端录制。

4.1 校验方法

通过比较自行计算的 signature 与回调请求中的 signature 是否一致可以验证请求的发起方是否为 ZEGO 云端录制。计算 signature 的流程如下图：

nonce：回调请求中的参数。
timestamp：回调请求中的参数。
callbacksecret：在 ZEGO 控制台注册项目时生成，可在控制台 > 项目配置 > 服务端API密钥中查看。

4.2 示例代码

PHP 代码如下：

$signature = $_POST["signature"];
$timestamp = $_POST["timestamp"];
$nonce = $_POST["nonce"];

$secret = callbacksecret;//后台获取的callbacksecret
$tmpArr = array($secret, $timestamp, $nonce);
sort($tmpArr, SORT_STRING);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );

if( $tmpStr == $signature ){
    return true;
} else {
    return false;
}

Java 代码如下：

// 从请求参数中获取到 signature, timestamp, nonce
String signature = request.getParameter("signature");
long timestamp = request.getParameter("timestamp");
String nonce = request.getParameter("nonce");

// 后台获取的callbacksecret
String secret = callbacksecret;

String[] tempArr = {secret, ""+timestamp, nonce};
Arrays.sort(tempArr);

String tmpStr = "";
for (int i = 0; i < tempArr.length; i++) {
    tmpStr += tempArr[i];
}
tmpStr = org.apache.commons.codec.digest.DigestUtils.sha1Hex(tmpStr);

return tmpStr.equals(signature);

4.3 输出示例

$timestamp = 1470820198;
$nonce = 123412;
$secret = 'secret';

排序拼接后需要加密的原始串为:1234121470820198secret
加密的结果为:5bd59fd62953a8059fb7eaba95720f66d19e4517

5 返回响应

返回 HTTP status code 为 2XX （例如 200）表示成功，其他响应都表示失败。