更新时间:2024-07-25 GMT+08:00
分享

直播事件回调

视频直播服务目前提供了推流回调、录制回调和截图回调三种功能回调。若在直播前配置了相关回调,则当直播过程触发了对应的事件时,视频直播会通过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"
}

配置回调地址

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

    回调地址为用户的通知服务器地址,格式样例:http://test.example.com/notify

    • 推流回调

      在左侧导航栏中,选择“模板配置 > 开停播通知”,单击“添加”,配置推流回调地址。

      图2 推流回调
    • 录制回调
      在左侧导航栏中,选择“模板配置 > 录制配置(新版)”,单击“新建回调配置”,配置录制回调地址。
      图3 录制回调
    • 截图回调

      在左侧导航栏中,选择“模板配置 > 截图配置”,在新增截图配置中配置对应的回调地址。

      图4 截图回调

相关文档