文档中心

事件回调接口说明

最近更新时间：2023.05.22 16:56:26

首次发布时间：2022.07.08 15:41:43

简介

火山引擎慢直播事件回调接口包括设备、通道、视频流、本地录像下载事件回调，具体如下表所示：

事件主体	事件 Key	事件说明	备注
设备	device_online	设备上线	部分设备可能存在一定延迟（约几十秒，与设备端配置的心跳周期有关）
设备	device_offline	设备下线	部分设备可能存在一定延迟（约几十秒，与设备端配置的心跳周期有关）
通道	channel_online	通道上线	部分设备可能存在几分钟延迟（设备侧实现协议不全）
通道	channel_offline	通道下线	部分设备可能存在几分钟延迟（设备侧实现协议不全）
视频流	stream_online	流上线	实时
	stream_offline	流下线	实时
	stream_record_aiot	流录制数据回调，需要配置录制模板	实时
	stream_snapshot_aiot	流截图数据回调，需要配置截图模板	实时
本地录像下载	gb_media_download	已生成可以下载的链接地址	根据下载模式不同，收到的回调次数也不同，参考本地视频下载事件说明
本地录像下载	gb_media_download_error	未生成可以下载的链接地址	根据报错信息提示进行处理
设备告警	device_alarm	报警事件	根据用户配置的报警类型，当设备有报警事件发送时，回调给用户

回调方式

参考示例：

POST <CallbackUrl>
{
    "CallbackMeta":{
        "MsgID":"c6cfbae4-0368-15af-aeab-2b622212e0c2",    # MSGID，唯一 
        "App":"2100042035-swb-test-e2e",    # 回调ID
        "Version":"v1",        # 回调版本号
        "Url":[                                     
            "http://10.xxx.xxx.xx:xxxxx/callback"    #回调地址
        ]
    },
    "CallbackHeader":{
        "EventObject":"stream",            
        "ObjectTag":"livestream0001",
        "EventType":"stream_online",
        "EventTime":1637831812009935076        #纳秒
    },
    "Detail":"xxxxxxaW1lIjoxNjM3Oxxxxxx"
}
# Detail：base64编码

resp
200

回调结构体

回调的基础数据结构为 EventCallbackMsg，所有的回调数据都采用这种结构。参考示例：

type EventCallbackMsg struct {
   CallbackMeta   *CallbackMeta   `json:"CallbackMeta"`
   CallbackHeader *CallbackHeader `json:"CallbackHeader"`
   Detail         string          `json:"Detail"`
}

type CallbackMeta struct {
   MsgID   string   `json:"MsgID"`
   App     string   `json:"App"`
   Version string   `json:"Version"`
   Url     []string `json:"Url"`    //回调的URL
}

type CallbackHeader struct {
   EventObject EventObject `json:"EventObject"`
   ObjectTag   string      `json:"ObjectTag"`
   EventType   EventType   `json:"EventType"`
   EventTime   int64       `json:"EventTime"`
}

回调的消息体，包括 CallbackMeta 、CallbackHeader 和 Detail 三个部分。

其中 Detail 部分是 Detail：回调具体内容 JSON 数据 base64 编码字符串。

CallbackMeta：回调元信息

字段	类型	说明
MsgID	String	回调消息唯一 ID，用于追溯消息
App	String	产生事件的主体 ID（比如流，App 即为 StreamID）
Version	String	回调版本号，目前为 v1
Url	[]String	回调的所有 URL

CallbackHeader：回调头

字段	类型	说明
EventObject	EventObject (String)	消息类型
ObjectTag	String	产生事件的对象名称，包括： device（设备） stream（通道） channel（流） gbMedia（本地录像）详细信息，参考以下 ObjectTag 说明
EventType	EventType (String)	事件类型，参考简介表格中的事件类型说明
EventTime	Int64	事件时间，单位：纳秒

ObjectTag 说明

主体	Tag	说明
流	流名	流名称
设备	deviceID	对于设备，回调的 ObjectTag 是设备 ID
通道	deviceID@channelID	对于通道，回调的 ObjectTag 是通道所属设备的 ID@通道ID
录像下载	streamID	视频流的 ID
截图/录像回调	streamID	视频流的 ID
设备告警	deviceID	对于设备告警，回调的 ObjectTag 是设备 ID

Detail：回调具体内容

设备事件

设备上下线

type DeviceEventDetail struct {
   DeviceID string `json:"DeviceID"`   //设备 ID
   DeviceNSID string `json:"DeviceNSID"`//设备国标ID
   DeviceStatus string `json:"DeviceStatus"` //设备状态，online/offline
}

设备报警

type DeviceAlarmInfo struct {
   DeviceID      string `json:"DeviceID"` //设备 ID
   DeviceNSID    string `json:"DeviceNSID"` //设备国标 ID
   ChannelID     string `json:"ChannelID"` //通道 ID
   AlarmPriority uint32 `json:"AlarmPriority"` //报警级别
   AlarmMethod   uint32 `json:"AlarmMethod"` //告警方式
   AlarmTime     string `json:"AlarmTime"` //报警时间
   AlarmType     uint32 `json:"AlarmType"` //报警类型
   Longitude     string `json:"Longitude"` //经度
   Latitude      string `json:"Latitude"`  //纬度
}

参考示例：

{34020044991320666666 34020044991320666666 1 5 2022-08-10T17:09:01 2  }

本地视频下载

(带水印的下载，会收到两次地址回调：第一次为 m3u8 地址，第二次为 mp4 地址）

type GBCallBackDetail struct {
    StreamID    string `json:"StreamID"`  //视频流 ID
    Status      string `json:"Status"`  // 状态
    StartTime   int64  `json:"StartTime"`  //视频流开始时间
    EndTime     int64  `json:"EndTime"`  //视频流结束时间  
    Url         string `json:"Url"`  //下载地址
    SubtitleUrl string `json:"SubtitleUrl"`  //带水印的地址
    DeviceMsg   string `json:"DeviceMsg"`    //发生错误时，会给出错误原因
    Type        string `json:"Type"` //m3u8/mp4
}

通道上线离线

type ChannelCallBackDetail struct {
    DeviceID  string `json:"DeviceID"`  //设备 ID
    DeviceNSID string `json:"DeviceNSID"`  //设备国标 ID
    ChannelID string `json:"ChannelID"`  //通道 ID
    Event     string `json:"Event"`   //通道事件，channel_online/channel_offline
}

流事件

流上线

type CallbackStartEventMetaCallback struct {
    Domain       string `json:"Domain"`  //域名
    Stream       string `json:"Stream"`   //流名
    StartTime    int64  `json:"StartTime"`
    LocationIP   string `json:"LocationIP"`
    LocationPort int64  `json:"LocationPort"`
    URI          string `json:"URI"`
    StreamID     string `json:"StreamID"`   //流 ID
}

参考示例：

{
    "Domain":"push-rtmp-xxx-xxxx-e2e-9135.fcdn-xxx-push.xxxxx.org",
    "Stream": "一条流",
    "StreamID":"13483xxx-d2iud2ui42uhd-3dhxxxxxx",
    "StartTime":1637834465954,
    "LocationIP":"10.xxx.xxx.xx",
    "LocationPort":1935,
    "Uri":"/2100042035-xxx-xxxx-e2e/livestream009?volcTime=1637834865"
}

流下线

type CallbackEndEventMetaCallback struct {
    Domain       string `json:"Domain"`  //渔民
    Stream       string `json:"Stream"`   //流名
    StartTime    int64  `json:"StartTime"`
    LocationIP   string `json:"LocationIP"`
    LocationPort int64  `json:"LocationPort"`
    URI          string `json:"URI"`
    StreamID     string `json:"StreamID"`   //流 ID
}

参考示例：

{
    "Domain":"push-rtmp-xxx-xxxx-e2e-9135.fcdn-xxx-push.xxxxx.org",
    "Stream": "一条流",
    "StreamID":"asdhjkha8ahjbda823nxxxxxx-2dne2uxxxx",
    "StartTime":1637834684189,
    "LocationIP":"10.xxx.xxx.xx",
    "LocationPort":1935,
    "URI":"/2100042035-xxx-xxxx-e2e/livestream009?volcTime=1637834865"
}

截图

type AIoTSnapshotCallbackDetail struct {
   //StreamID      string `json:"StreamID"`
   Format        string `json:"Format"`    //jpg/...
   Url           string `json:"Url"`
   FileSize      int64  `json:"FileSize"`
   CreateAt      int64  `json:"CreateAt"`
   ExpireAt      int64  `json:"ExpireAt"` //截图文件过期时间，-1表示永不过期
   TokenExpireAt int64  `json:"TokenExpireAt"`//URL过期时间
}

录制

type AIoTRecordCallbackDetail struct {
   //StreamID      string `json:"StreamID"`
   Format        string `json:"Format"` //ts/mp4/m3u8
   Url           string `json:"Url"`
   FileSize      int64  `json:"FileSize"` 
   CreateAt      int64  `json:"CreateAt"` //视频创建时间
   ExpireAt      int64  `json:"ExpireAt"` //视频过期时间
   TokenExpireAt int64  `json:"TokenExpireAt"` //视频URL过期时间
   StartAt       int64  `json:"StartAt"` //视频开始时间，UNIX（ms）
   EndAt         int64  `json:"EndAt"`   //视频结束时间，UNIX（ms）
}

说明

回调以收到返回结果表示成功，不关注 HTTP 状态码；
如果请求失败，比如回调方服务异常导致请求不可达，会记录失败次数，连续失败后会放弃回调。在确认服务可用后，联系技术支持放开限制即可接收到回调；
调用超时时间为10s，请勿再同步执行耗时操作。

简介

回调方式

回调结构体

CallbackMeta：回调元信息

CallbackHeader：回调头

ObjectTag 说明

Detail：回调具体内容

设备事件

设备上下线

设备报警

本地视频下载

通道上线离线

流事件

流上线

流下线

截图

录制

说明