# 云直播事件回调功能帮助用户实时查看直播事件 视频直播服务目前提供了推流回调、录制回调和截图回调三种功能回调。若在直播前配置了相关回调，则当直播过程触发了对应的事件时，视频直播会通过HTTP接口向用户服务器发送POST请求，将事件回调信息实时反馈到用户服务器。 #### 回调协议 - 请求：HTTP POST请求，请求Body的内容为JSON格式。 - 应答：HTTP STATUS CODE = 200，应答内容为JSON格式，用户可以根据实际需求自定义应答内容。 示例如下： ``` { "status": 1, "result" : "success" } ``` #### 整体流程 图1回调流程 ![](https://support.huaweicloud.com/bestpractice-live/zh-cn_image_0261395428.png) #### 推流回调 推流回调用于推送推流状态信息，包括推流成功和推流中断，回调消息字段如[表1]所示。 表1消息体字段说明 | 字段 | 描述 | |:---|:---| | domain | 推流域名。 | | app | 应用名称。 | | stream | 流名称。 | | user_args | 推流参数。 | | client_ip | 推流客户端IP。 | | node_ip | 接受流的节点IP。 | | publish_timestamp | 推流Unix时间戳，一次推流活动会产生相同时间戳的推流和断流消息。 | | event | 直播推流和断流标识。 取值为： - PUBLISH：开播。 - PUBLISH_DONE：停播。 | | auth_timestamp | 事件通知签名过期UNIX时间戳。当配置了"鉴权密钥"时，携带该字段。 格式为十进制的UNIX时间戳，即从1970年1月1日（UTC/GMT的午夜）以来的当前时间秒数。 示例：1592639100（即2020-06-20 15:45） | | auth_sign | 事件通知签名。当配置了"鉴权密钥"时，携带该字段。 ``` auth_sign = HmacSHA256（event + domain + app + stream + auth_timestamp, key） ``` 其中，key为鉴权密钥值。 | 消息示例，如下所示： ``` { "domain":"push.example.com", "app":"live", "stream":"example_stream", "user_args":"auth_info=yz1TG0PVN/5isfyrGrRj10gKPCWqSS2X02t6QsRrocH+mEq0gQ0g8k6KhalS84sQ+kDprFyqI0yajbYiFmUO8e45B7ryaS+MpJBlYkhwnuFLnRiKK/IXG7.33436b625354564f6e4d4d434f55&cdn=hw", "client_ip":"100.111.*.*", "node_ip":"112.11.*.*", "publish_timestamp":"1587954134,", "event":"PUBLISH" "auth_timestamp":1587954140, "auth_sign":"ff3b2bxxx5cfd56e76d72bed4c4aa2dxxxca8c2e46467d205a6417d4fc" } ``` #### 录制回调 直播录制至OBS提供了录制回调功能，用于推送录制状态信息，包括录制开始、开始创建新的录制文件、录制文件生成完成、录制结束和录制失败。回调消息字段如[表2]所示。 表2消息体字段说明 | 字段 | 描述 | |:---|:---| | project_id | 项目ID。 | | job_id | 用于标识同一个文件。当"event_type"为"RECORD_NEW_FILE_START"或"RECORD_FILE_COMPLETE"时，携带该字段。 | | task_id | 录制任务ID，用于唯一标识一个录制任务。 | | event_type | 消息类型。 取值如下： - RECORD_START：表示录制开始。若配置了录制模板和录制回调，则直播推流开始时，开始录制，触发该事件。 - RECORD_NEW_FILE_START：表示开始创建新的录制文件。以下情况会触发该事件： - 直播推流开始，开始创建第一个录制文件。 - 直播断流恢复后，若"最大断流合并时长"配置为"断流后生成新文件"，则开始创建新的录制文件。 - 当前录制时长超过了配置的录制周期，则开始新的录制文件生成。 - RECORD_FILE_COMPLETE：表示录制文件生成完成。以下情况会触发该事件： - 录制时长达到配置的录制周期，则当前录制文件生成完成，并开始新的录制生成。 - 直播断流后，若"最大断流合并时长"配置为"断流后生成新文件"，则当前录制文件生成完成，若断流恢复，将开始新的录制文件生成。 - RECORD_OVER：表示录制结束，直播断流时长超过了最大断流合并时长，当前录制任务结束，触发该事件。 - RECORD_FAILED：表示录制失败，当拉流失败、录制文件上传OBS失败等因素导致录制失败时，触发该事件。 | | publish_domain | 直播推流域名。 | | app | 应用名。 | | stream | 录制的流名。 | | record_format | 录制格式，支持HLS、FLV和MP4格式。 | | download_url | 录制文件的下载地址。当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 说明： 使用该下载地址用于视频播放无法保证播放效果。 | | asset_id | 用于标识一个录制文件。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | file_size | 文件大小。 单位：Byte。 | | record_duration | 录制文件的时长。 单位：秒。 | | start_time | 录制文件的开始时间，即接收到第一帧数据的时间，格式为yyyy-mm-ddThh:mm:ssZ。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | end_time | 录制文件的结束时间，格式为yyyy-mm-ddThh:mm:ssZ。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | width | 录制文件分辨率的宽。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | height | 录制文件分辨率的高。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | obs_location | 存储录制文件的OBS桶所在区域。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | obs_bucket | 存储录制文件的OBS桶。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | obs_object | OBS桶存储录制文件的路径。 当"event_type"为"RECORD_FILE_COMPLETE"时，携带该字段。 | | auth_sign | 事件通知签名。当配置了"鉴权密钥"时，携带该字段。 - MD5方式：auth_sign=MD5(key + auth_timestamp) - HMACSHA256方式：HMACSHA256(auth_timestamp + event_type + publish_domain + app + stream + download_url + play_url，key) 其中，key为鉴权密钥值。 | | auth_timestamp | 事件通知签名过期UNIX时间戳。当配置了"鉴权密钥"时，携带该字段。 格式为十进制的UNIX时间戳，即从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数。 若消息通知中的auth_timestamp值所指定的时间已经过期，则此消息通知无效，进而防止网络重放攻击。 | | error_message | 录制失败的描述信息。 当"event_type"为"RECORD_FAILED"时，携带该字段。 | 消息示例如下所示： - 录制开始事件，即"event_type"="RECORD_START"，若配置了录制模板和录制回调，则直播推流开始时，开始录制，产生该事件回调。 ``` { "project_id" : "70b76xxxxxx34253880af501cdxxxxxx", "publish_domain" : "push.example.com", "event_type" : "RECORD_START", "app" : "live", "stream" : "mystream", "record_format" : "HLS", "file_size" : 3957964, "record_duration" : 120 } ``` - 开始创建新的录制文件事件，即"event_type"="RECORD_NEW_FILE_START"。 以下情况会产生该事件回调： - 直播推流开始，开始创建第一个录制文件。 - 直播断流恢复后，若"最大断流合并时长"配置为"断流后生成新文件"，则开始创建新的录制文件。 - 当前录制时长超过了配置的录制周期，则开始新的录制文件生成。 ``` { "project_id" : "70b76xxxxxx34253880af501cdxxxxxx", "publish_domain" : "push.example.com", "event_type" : "RECORD_NEW_FILE_START", "app" : "live", "stream" : "mystream", "record_format" : "HLS", "file_size" : 3957964, "record_duration" : 120 } ``` - 录制文件生成完成事件，即"event_type"="RECORD_FILE_COMPLETE"。 以下情况会产生该事件回调： - 当前录制时长达到配置的录制周期时，则当前录制文件生成完成。 - 直播断流后，若"最大断流合并时长"配置为"断流后生成新文件"，则当前录制文件生成完成。 ``` { "project_id" : "70b76xxxxxx34253880af501cdxxxxxx", "publish_domain" : "push.example.com", "event_type" : "RECORD_FILE_COMPLETE", "app" : "live", "stream" : "mystream", "record_format" : "HLS", "download_url" : "https://obs.cn-north-4.myhuaweicloud.com/live/record-xxxx-mystream-1589967495/record-push.example.com-live-mystream-1589967495.m3u8", "asset_id" : "1a0d8e9bfae388ccbbe5021e62aa1e96", "file_size" : 3957964, "record_duration" : 120, "start_time" : "2020-03-08T14:10:25Z", "end_time" : "2020-03-08T14:12:25Z", "width" : 1280, "height" : 720, "obs_location" : "https://obs.cn-north-4.myhuaweicloud.com", "obs_bucket" : "mybucket", "obs_object" : "live/record-xxxx-mystream-1589967495/record-hwpublish.myun.tv-live-mystream-1589967495.m3u8" "auth_sign" : "4f97f46759axxxxxx7ad21e9935dc175", "auth_timestamp" : 1583676745 } ``` - "download_url"：录制文件下载地址，即录制文件存储在OBS桶中的地址。 - "asset_id"：媒资ID。 - 录制结束事件，即"event_type"="RECORD_OVER"。直播断流时长超过了最大断流合并时长，当前录制任务结束，产生该事件回调。 ``` { "project_id" : "70b76xxxxxx34253880af501cdxxxxxx", "publish_domain" : "push.example.com", "event_type" : "RECORD_FILE_COMPLETE", "app" : "live", "stream" : "mystream", "record_format" : "HLS", "file_size" : 3957964, "record_duration" : 120 } ``` - 录制失败事件，即"event_type"="RECORD_FAILED"。当拉流失败、录制文件上传OBS失败等因素导致录制失败时，产生该事件回调。 ``` { "project_id" : "70b76xxxxxx34253880af501cdxxxxxx", "publish_domain" : "push.example.com", "event_type" : "RECORD_FAILED", "app" : "live", "stream" : "mystream", "record_format" : "HLS", "file_size" : 3957964, "record_duration" : 120, "error_message": "Message example" } ``` #### 截图回调 直播截图回调用于推送截图状态信息，当截图文件生成时触发该回调事件。回调消息字段如[表3]所示。 表3消息体字段说明 | 字段 | 描述 | |:---|:---| | domain | 推流域名。 | | app | 应用名称。 | | stream_name | 流名称。 | | snapshot_url | 截图下载链接。 | | width | 图片宽度。 单位：像素。 | | height | 图片高度。 单位：像素。 | | obs_addr | 截图所在的OBS桶地址，具体结构体说明如下所示： - bucket：OBS的桶名称。 - location：OBS桶所在数据中心。 - object：OBS对象路径。 | | auth_timestamp | 事件通知签名过期UNIX时间戳。当配置了"鉴权密钥"时，携带该字段。 格式为十进制的UNIX时间戳，即从1970年1月1日（UTC/GMT的午夜）以来的当前时间秒数。 示例：1592639100（即2020-06-20 15:45） | | auth_sign | 事件通知签名。当配置了"鉴权密钥"时，携带该字段。 ``` auth_sign = HmacSHA256（domain + app + stream_name + snapshot_url + width + height + obs_addr.bucket + obs_addr.location + obs_addr.object + auth_timestamp,key） ``` 其中，key为鉴权密钥值。 | 消息示例如下所示： ``` { "domain": "play.example.com", "app": "live", "stream_name": "test001", "snapshot_url": "https://xxx.obs.cn-north-4.myhuaweicloud.com:443...", "width":"720", "height":"1280", "obs_addr": { "bucket": "xxx", "location": "cn-north-4", "object": "xxx.jpg" }, "auth_timestamp":1587954140, "auth_sign":"4918b1axxxxxxb583cffa119d72513bbc35a989f8569fxxxxxx057646154a04a" } ``` #### 配置回调地址 1. 登录[视频直播控制台](https://console.huaweicloud.com/live2/#/live/home)。 2. 在左侧导航栏中，选择"域名管理"，进入域名管理页面。 3. 在需要配置回调的推流域名行单击"管理"。 4. 配置回调地址。回调地址为用户的通知服务器地址，格式样例：http://test.example.com/notify 包含下述3种类型的回调配置： **推流回调** ：选择"开停播通知"页签，单击"添加"，配置推流回调地址，如[图2]所示。 图2开停播通知配置 ![](https://support.huaweicloud.com/bestpractice-live/zh-cn_image_0258827150.png) **录制回调** ：选择"录制配置（新版）"页签，单击"新建回调配置"，配置录制回调地址，如[图3]所示。 图3添加录制回调URL ![](https://support.huaweicloud.com/bestpractice-live/zh-cn_image_0000001394104401.png) **截图回调** ：选择"截图配置"页签，在新增截图配置中配置对应的回调地址，如[图4]所示。 图4配置直播截图模板 ![](https://support.huaweicloud.com/bestpractice-live/zh-cn_image_0000001882763585.png)