回调管理 - 开发指南| 阿里云

回调简介

当直播过程中某些事件被触发时，阿里云将主动发送请求到客户服务器，客户服务器负责应答请求，验证通过后，您可接收到事件回调信息的JSON数据包。

视频直播支持回调如下事件的信息：

直播推流状态
直播录制
按需录制
直播截图

回调方式

视频直播服务目前支持HTTP回调（兼容HTTPS）方式获取事件通知。您需要部署一个HTTP服务来接收回调消息，并在控制台或通过API配置回调地址。

当推流或断流事件产生时，直播服务端会向该地址发起HTTP GET请求，具体内容将通过URL参数送达。
当其他事件产生时，直播服务端会向该地址发起HTTP POST请求，具体内容将通过JSON Body送达。

注意事项

回调地址URL无需标识，只需可正常访问，URL的应答有如下要求：如果访问超时，会重试URL，目前超时时间是5秒，重试次数5次，重试间隔1秒。

直播推流状态回调

通知当前域名推流状态，包括推流成功、断流状态，支持通过控制台或API配置回调地址。

直播推流状态回调设置方式

控制台
在视频直播控制台的域名管理页面，选择需要配置的推流域名，单击域名配置，进入直播管理 > 基本配置 > 推流信息页面，添加或修改推流回调地址。

API


接口	描述	参考文档
SetLiveStreamsNotifyUrlConfig	设置推流回调配置。	设置直播推流回调配置
DescribeLiveStreamsNotifyUrlConfig	查询推流回调配置。	查询直播推流回调配置
DeleteLiveStreamsNotifyUrlConfig	删除推流回调配置。	删除直播推流回调配置

直播推流状态回调

推断流状态回调会将参数封装在MultiDict内。

直播推流状态回调中开播（publish）状态回调逻辑
1. RTMP推流在阿里云直播服务收到On Publish消息后2秒内，如果推流端不主动断开，阿里云直播服务就会发推流成功回调。如果您的业务需要阿里云直播收到On Publish建联并真正收到直播流数据后才发推流成功回调，请提交工单联系我们后台配置。
2. 假设您有推流域名A和播流域名B，如果您的域名B使用拉流直播（固定拉流和触发回源拉流）需要回调，请在域名A配置推流回调。配置后域名B的拉流回调逻辑与上一条一致，建联后默认2秒无主动断开即认为拉流成功，需要真正收到数据才认为成功。请提交工单申请配置。
说明建议业务方不仅根据回调通知判断推流、拉流接入正常，同时配合在线流列表查询推流正常后，再下发直播流播放地址。

直播推流状态回调参数


参数	描述
action	事件。 publish：推流。 publish_done：断流。
ip	推流的客户端IP。
id	推流流名称。
app	推流域名。默认为自定义的推流域名，如果未绑定推流域名即为播流域名。
appname	推流应用名称。
time	Unix时间戳。单位：秒。
usrargs	用户推流的参数。
node	CDN接受流的节点或者机器名。
height	分辨率的高。单位：像素。说明分辨率信息（height和width）仅在首次回调时产生。
width	分辨率的宽。单位：像素。

推流状态回调参数示例

http:// 1.1.1.1?action=publish&ip=192.168.0.1&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={用户参数}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280

断流流状态回调参数示例

http:// 1.1.1.1?action=publish_done&ip=192.168.0.0&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={用户参数}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280

直播推流状态回调鉴权
推流回调鉴权功能默认关闭，用户可在配置推流回调地址时启用鉴权。启用功能后，鉴权逻辑如下：
1. 阿里云视频直播发起回调请求时在HTTP(S)请求头中带上ALI-LIVE-TIMESTAMP和 ALI-LIVE-SIGNATURE 字段，供回调消息接收服务端进行签名认证。其中，ALI-LIVE-SIGNATURE的值由如下计算而得：
  ALI-LIVE-SIGNATURE=MD5SUM（MD5CONTENT)
  
  MD5CONTENT=回调域名|ALI-LIVE-TIMESTAMP取值|鉴权KEY
  
  说明回调域名指配置回调URL的推流域名。鉴权Key指用户为推流回调URL配置的鉴权Key。
2. 回调消息接收服务端接收回调消息时，将回调域名、ALI-LIVE-TIMESTAMP取值、鉴权Key进行拼接后计算MD5值，得到加密字符串，再将计算出的加密字符串与视频直播发起的HTTP(S)请求头中的ALI-LIVE-SIGNATURE字段值进行对比。如果不一致，则请求非法。

直播录制回调

直播录制回调包括录制状态回调、文件生成回调，支持通过控制台和API进行配置。

录制状态回调：在文件开始录制与结束录制时发出，主要表示文件已经开始和结束录制。
文件生成回调：在文件生成时发出，主要包括文件名称，开始结束时间与时长信息。

直播录制回调设置方式

控制台
在视频直播控制台的域名管理页面，选择需要配置的播流域名，单击域名配置，进入模版配置 > 录制配置页面，添加或修改回调地址。

API


接口	描述	参考文档
AddLiveRecordNotifyConfig	添加域名级别录制回调配置。若需要开启录制任务状态回调，请将NeedStatusNotify参数值设置为true。	添加直播录制回调配置
DescribeLiveRecordNotifyConfig	查询域名级别录制回调配置。	查询直播录制回调配置
DeleteLiveRecordNotifyConfig	删除域名级别录制回调配置。	删除直播录制回调配置

录制状态回调

录制状态回调参数


参数	描述
domain	录制的播流域名。
app	应用名。
stream	流名。
event	事件名。 record_started：录制已经成功开始。 record_paused：录制已经成功暂停。 record_resumed：录制已经成功恢复继续录制。

录制状态回调参数示例

{
"domain": "demo.aliyundoc.com",
"app": "liveApp****",
"stream": "liveStream****",
"event": "record_started"
}

文件生成回调

文件生成回调参数


参数	描述
domain	录制的播流域名。
app	应用名。
stream	流名。
uri	目标录制文件在用户录制OSS Bucket下的路径。
duration	目标录制文件录制内容时长，单位：秒。
start_time	录制开始时间。Unix时间戳，单位：秒。
stop_time	录制结束时间。Unix时间戳，单位：秒。
push_args	推流参数中以callback_为前缀的参数，如callback_arg1、callback_myid等。说明同一个参数名只能有一个参数值，如果传入多个值，回调仅包含第一个值。如推流参数包含`callback_args1=value1&callback_args1=value2`，回调中仍为`"callback_args1": "value1"`。

文件生成回调参数示例

推流URL为：

rtmp://demo.aliyundoc.com/liveApp****/liveStream****?callback_args1=value1&callback_myid=1231389741

则回调内容为：

{
  "domain": "demo.aliyundoc.com",
  "app": "liveApp****",
  "stream": "liveStream****",
  "uri": "liveApp****/liveStream****/0_2017-03-08-23:09:46_2017-03-08-23:10:40.flv",
  "duration": 69.403,
  "start_time": 1488985786,
  "stop_time": 1488985840,
  "push_args": {
    "callback_args1": "value1",
    "callback_myid": "1231389741"
  }
}

说明以上回调示例，适用于所有没有定制回调模版的客户。

按需录制回调

按需录制回调是录制之前通过回调的方式，传递直播流的相关参数给用户，由用户判断是否需要录制的功能。

用户指定一个回调地址，并设置一个domain、app或stream级别的录制为按需录制。当录制服务收到匹配domain、app或stream名称的流时，向用户的回调地址发送请求（请求包含5个参数），来询问用户是否需要录制这路流。

请求参数


参数	类型	描述
domain	String	主播流域名。
app	String	播流所属应用名称。
stream	String	播流名称。
codec	String	编码方式。取值： h264 h265
vbitrate	String	视频码率。单位：kbps。

返回参数


参数	类型	是否必选	描述
ApiVersion	String	否	API版本。默认为1.0版本。
NeedRecord	Bool	是	是否需要录制。
Interval	Json Object	否	具体格式的录制周期变化。取值范围：5~21600。单位：秒。
Format	Array	否	录制格式。支持MP4、FLV、M3U8。

请求示例

GET /?app=seq_all&domain=demo.aliyundoc.com&stream=ondemand8&vbitrate=2000&codec=h264 HTTP/1.1
Host: example.aliyundoc.com
User-Agent: Go-http-client/1.1
Accept-Encoding: gzip

返回示例

{
    "ApiVersion" : "1.0",
    "NeedRecord" : true,
    "Interval" : {
        "Mp4": 300,
        "Flv": 120,
        "M3U8": 180
    },
    "Format" : ["mp4","flv"]
}

返回参数处理
录制服务会对用户返回的参数配置和既有配置进行覆盖。例如，显示指定了Interval，那么录制服务会覆盖数据库中的录制配里面的Interval，Format会和数据库中的配置取交集。如果用户指定的格式全不在既有配置之中，则不会录制这路直播流。
说明
- 所有非200 http status code，都会被认为是调用用户接口失败。
- 对于范围body长度有限制，超过2048会被截断，以防恶意攻击。

直播截图回调

直播提供截图文件回调，您可以通过调用UpdateLiveAppSnapshotConfig接口，配置Callback参数开启。更多信息，请参见更新直播截图配置。

截图文件回调参数


参数	描述
Event	事件。
DomainName	截图的播流域名。
AppName	应用名。
StreamName	流名。
OssBucket	存储截图的Bucket名。
OssEndpoint	存储截图的OSS。
OssObject	截图的文件名。
CreateTime	截图时间。
SnapshotUrl	截图文件在用户录制OSS Bucket下的路径。
Size	图片大小。
Width	图片宽。单位：像素。
Height	图片高。单位：像素。

截图文件回调参数示例

{
    "Event":"Snapshot",
    "DomainName":"demo.aliyundoc.com",
    "AppName":"liveApp****",
    "StreamName":"liveStream****",
    "OssBucket":"liveBucket****",
    "OssEndpoint":"oss-cn-shan****.aliyuncs.com",
    "OssObject":"1****.jpg",
    "CreateTime":"2015-12-01T17:36:00Z",
    "SnapshotUrl":"http://liveBucket****.oss-cn-shan****.aliyuncs.com/1****.jpg",
    "Size":"36291",
    "Width":"1280",
    "Height":"720"
}

直播截图支持截图回调鉴权配置。详细信息请参见设置截图回调鉴权配置、截图回调鉴权说明。