录制状态回调

---

1 描述

如需要第一时间获知任务状态事件，需要在开通云端录制服务时提供回调地址，详情请参考 项目管理 - 服务配置 中的“云端录制”。

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

2 回调参数

• event_type 为 1 时，detail 属性列表如下：

  参数	类型	描述
  upload_status	int	录制文件上传整体状态。 1: 全部文件上传成功 2: 部分文件上传成功（文件信息列表中有至少一个文件的 status 不为 3）。
  file_info	Array of Object	文件信息列表。列表为空表示没有产生录制文件（房间内没有用户推流）。

  file_info 属性如下：

  参数	类型	描述
  user_id	String	录制流对应的推流用户 ID（混流时，为 MixOutputStreamId）。
  user_name	String	录制流对应的推流用户昵称（混流时，为 MixOutputStreamId）。
  stream_id	String	录制流对应的流 ID（混流时，为 MixOutputStreamId）。
  file_id	String	录制文件名称，详情请参考 开始录制 中的 OutputFileRule 参数。
  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。
  status	Int	文件状态。 1：录制中，表示正在录制文件。 2：上传中，表示正在上传录制文件至客户指定云存储。 3：上传成功，表示上传录制文件至客户指定云存储成功。 4：已经上传至备份云存储，表示上传客户指定云存储失败，已上传至 ZEGO 备份云存储。请注意，ZEGO 备份云存储的有效期为 3 天，请您及时下载录制文件，保存到本地。 5：上传失败，表示上传客户指定云存储和 ZEGO 备份云存储均失败。

• event_type 为 2 时，detail 属性列表如下：

  参数	类型	描述
  quit_reason	int	录制服务异常退出原因。 1：录制服务启动失败，建议重新发起录制请求。 2：录制服务登录房间失败，请确保要录制的房间可登录。 3：房间内没有任何流、白板的时间超过了 开始录制 时 MaxIdleTime 设置的值（默认 30 秒），导致录制任务自动结束。 4：达到 开始录制 时 设置的最大录制时长 MaxRecordTime（默认 24 小时），导致录制任务自动结束。 5：录制引擎启动失败，建议重新发起录制请求。 6：录制服务网络连接断开，建议重新发起录制请求。 1001：录制未知错误，建议重新发起录制请求。 1002：录制文件名太长，请参考 OutputFileRule。 1003：录制文件打开失败，建议重新发起录制请求。 1004：录制服务存储空间不足，建议重新发起录制请求。 1005：录制引擎初始化失败，建议重新发起录制请求。 1006：录制写文件头失败，建议重新发起录制请求。 1007：录制写文件 EBADF，建议重新发起录制请求。 1008：录制写文件 EIO，建议重新发起录制请求。 1009：录制内部 Channel 错误，建议重新发起录制请求。 1010：不支持的录制文件格式，请参考 OutputFileFormat。 1011：录制非法状态，建议重新发起录制请求。

• event_type 为 3 时，detail 属性列表如下：

  参数	类型	描述
  image_type	int	下载失败的图片类型，对应 开始录制 时设置的图片类型。 1: 视频画布背景图（MixOutputBackgroundImage）。 2: 水印图（MixOutputWatermarkImage） 3: 流画面默认背景图（DefaultMixStreamBackgroundImage） 4: 自定义布局流画面背景图（BackgroundImage）
  image_url	String	下载失败的图片 url。

• event_type 为 4、5 或 7 时，detail 内容为空。

• event_type 为 6 时，detail 属性列表如下：

  参数	类型	描述
  stream_id	String	录制流对应的流 ID。

• event_type 为 102 时，detail 属性列表如下：

  参数	类型	描述
  stream_id	String	录制流对应的流 ID。
  file_id	String	录制文件名称。
  file_url	String	文件访问 URL。
  media_track_type	Int	文件媒体类型。 1：只有音频。 2：只有视频。 3：音视频。

3 回调示例

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

{
    "app_id": 1234567890, 
    "detail": {
        "file_info": [
            {
                "begin_timestamp": 1637753762084, 
                "duration": 170039, 
                "file_id": "YZ4joOE4IwmFAAAT_6677_800221_800221_VA_20211124113602084.mp4", 
                "file_size": 25349026, 
                "file_url": "file_url", 
                "media_track_type": 3, 
                "output_file_format": "mp4", 
                "resolution_height": 720, 
                "resolution_width": 1280, 
                "status": 3, 
                "stream_id": "800221", 
                "user_id": "800221", 
                "user_name": "play_800221", 
                "video_id": ""
            }
        ], 
        "upload_status": 1
    }, 
    "event_type": 1, 
    "message": "", 
    "nonce": "100480", 
    "room_id": "6677", 
    "sequence": 1, 
    "signature": "12345678987654321", 
    "task_id": "YZ4joOE4IwmFAAAT", 
    "timestamp": "1637753949"
}

4 来源校验

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

4.1 校验方法

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

• nonce：回调请求中的参数。
• timestamp：回调请求中的参数。
• callbacksecret：在 ZEGO 控制台 注册项目时生成，可在“控制台 > 项目配置 > 项目信息 > 配置信息”中查看。

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）表示成功，其他响应都表示失败。

6 回调重试策略

如果 ZEGO 服务器没有收到响应，会尝试重试，最多进行 2 次重试。每次重试请求与上一次请求的间隔时间为 5s。若第 2 次重试后仍然失败，将不再重试，该回调丢失。