录制状态回调

注意

回调服务不能保证完全可靠，请慎重考虑使用回调方案构建核心业务流程的风险。
该回调接口为 v2 版本的回调，仅 2021-11-29 之后开通云端录制服务的用户会收到本回调。请 2021-11-29 之前开通云端录制服务的用户参考旧版回调接口。

描述

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

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

回调参数

参数	类型	描述
app_id	Int64	ZEGO 给开发者分配的 AppID，唯一标识一个应用。
task_id	String	录制任务 ID，长度固定为 16 个字节的字符串。
room_id	String	录制房间 ID。
event_type	Int	事件通知类型。 1：录制文件上传状态通知，详细信息请查看 `detail` 参数。 2：录制任务异常结束状态通知，详细信息请查看 `detail` 参数。 3：录制过程中自定义背景图/水印图下载失败通知，详细信息请查看 `detail` 参数。 4：录制过程中房间内流数量为 0 通知。房间内流的数量变为 0 后的 30 秒内会触发此事件。首次触发后，若房间内一直无流，会每隔 30 秒触发一次此事件直到有流或者任务因无流超时异常结束。 5：录制正常退出通知。 6：录制的流不存在，详细信息请查看 `detail` 参数。 7：录制已停止，正在上传录制的文件。 102：实时上传分片时，通知 M3U8 文件地址。 201：暂停录制成功。 202：恢复录制成功。
message	String	事件描述。
nonce	String	随机数，用于检验串计算。
timestamp	String	回调发送时的 Unix 时间戳，用于检验串计算。
signature	String	检验串，验证回调发送方身份。
sequence	Int	消息序列号，从 0 开始计数。
detail	JSON Object	事件详细信息，详情请参考 detail

detail

请根据 event_type 的不同取值，查看 detail 包含字段详情。

4、5、7、201 或 202

102

说明

录制状态回调的相关参数，ZEGO 会在之后的迭代计划中，持续优化更新（例如：新增字段、或新增某些字段的参数取值）。开发者在接入时，请避免将代码写死，造成后期更新后，无法兼容新版本。

回调示例

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

Untitled

{
    "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"
}

Copied!

验证签名

为提高数据安全性，建议开发者在收到 ZEGO 服务端发出的回调时，进行本地签名计算，并与 signature 进行对比，判断该请求是否合法。

校验的使用流程如下：

参数说明如下：

参数	说明
callbacksecret	服务端校验密钥。在 ZEGO 控制台注册项目时生成，可在 “控制台 > 项目配置 > 项目信息 > 配置信息” 中查看。
timestamp	Unix 时间戳。
nonce	随机数。

使用示例

返回响应

当您收到回调后，请返回 HTTP status code 为 2XX （例如 200），表示接收成功。返回其他，都表示接收失败。

回调重试策略

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