直播事件回调

视频直播服务目前提供了推流回调、录制回调和截图回调三种功能回调。若在直播前配置了相关回调，则当直播过程触发了对应的事件时，视频直播会通过HTTP接口向用户服务器发送POST请求，将事件回调信息实时反馈到用户服务器。

回调协议

请求：HTTP POST请求，请求Body的内容为JSON格式。
应答：HTTP STATUS CODE = 200，应答内容为JSON格式，用户可以根据实际需求自定义应答内容。
示例如下：
```
{ 
  "status": 1, 
  "result" : "success" 
}
```

整体流程

图1 回调流程

推流回调

推流回调用于推送推流状态信息，包括推流成功和推流中断，回调消息字段如表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_FILE_COMPLETE”。直播断流时长超过了最大断流合并时长，当前录制任务结束，产生该事件回调。

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

配置回调地址

登录视频直播控制台。
在左侧导航栏中，选择“域名管理”，进入域名管理页面。
在需要配置回调的推流域名行单击“管理”。
配置回调地址。

回调地址为用户的通知服务器地址，格式样例：http://test.example.com/notify
- 推流回调
   在左侧导航栏中，选择“模板配置 > 开停播通知”，单击“添加”，配置推流回调地址。
  
  图2 推流回调
- 录制回调
   在左侧导航栏中，选择“模板配置 > 录制配置（新版）”，单击“新建回调配置”，配置录制回调地址。
  图3 录制回调
- 截图回调
   在左侧导航栏中，选择“模板配置 > 截图配置”，在新增截图配置中配置对应的回调地址。
  
  图4 截图回调