直播事件回调
视频直播服务目前提供了推流回调、录制回调和截图回调三种功能回调。若在直播前配置了相关回调，则当直播过程触发了对应的事件时，视频直播会通过HTTP接口向用户服务器发送POST请求，将事件回调信息实时反馈到用户服务器。
回调协议
- 请求：HTTP POST请求，请求Body的内容为JSON格式。
- 应答：HTTP STATUS CODE = 200，应答内容为JSON格式，用户可以根据实际需求自定义应答内容。
整体流程
推流回调
推流回调用于推送推流状态信息，包括推流成功和推流中断，回调消息字段如表1所示。
|
字段 |
描述 |
|---|---|
|
domain |
推流域名。 |
|
app |
应用名称。 |
|
stream |
流名称。 |
|
user_args |
推流参数。 |
|
client_ip |
推流客户端IP。 |
|
node_ip |
接受流的节点IP。 |
|
publish_timestamp |
推流Unix时间戳，一次推流活动会产生相同时间戳的推流和断流消息。 |
|
event |
直播推流和断流标识。 取值为：
|
|
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所示。
|
字段 |
描述 |
|---|---|
|
project_id |
项目ID。 |
|
job_id |
用于标识同一个文件。当“event_type”为“RECORD_NEW_FILE_START”或“RECORD_FILE_COMPLETE”时，携带该字段。 |
|
task_id |
录制任务ID，用于唯一标识一个录制任务。 |
|
event_type |
消息类型。 取值如下：
|
|
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 |
事件通知签名。当配置了“鉴权密钥”时，携带该字段。
其中，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所示。
|
字段 |
描述 |
|---|---|
|
domain |
推流域名。 |
|
app |
应用名称。 |
|
stream_name |
流名称。 |
|
snapshot_url |
截图下载链接。 |
|
width |
图片宽度。 单位：像素。 |
|
height |
图片高度。 单位：像素。 |
|
obs_addr |
截图所在的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"
}
