本文为您介绍HTTP回调事件通知的回调机制、使用流程及鉴权原理。
HTTP回调机制
- 您需要自行部署一个HTTP服务来接收回调消息,并在点播中配置回调URL。
- 当事件产生时,点播服务端会向该URL发起HTTP POST请求,事件通知内容将通过HTTP Body送达。
- 您的HTTP服务对HTTP POST请求进行签名认证鉴权,鉴权成功则响应状态码200即视为回调成功,若响应其他状态码或响应超时则视为回调失败。鉴权原理请参见HTTP回调鉴权原理。
- 回调成功后,您配置的回调URL中将接收到相应的事件通知内容。回调失败后,点播服务会继续重试回调2次,即总共最多回调3次;超过3次后则会丢弃本次回调事件通知。详细的回调判断与重试逻辑请参见回调判断与重试。
HTTP回调鉴权原理
点播服务支持在HTTP(含HTTPS)回调时增加特定签名头,供回调消息接收服务端进行签名认证,以防止非法或无效请求。
注意事项
- HTTP回调鉴权是否开启由您自行决定(建议开启)。一旦设置了AuthKey(鉴权密钥),则回调时会携带所有鉴权相关内容,供回调消息接收服务端进行鉴权使用,即设置AuthKey不会影响原有功能,具体是否校验由您自行决定。
- 如果未设置AuthKey,也不会受任何影响。
鉴权参数
在回调HTTP头部增加的具体鉴权参数如下:
字段 | 描述 |
---|---|
X-VOD-TIMESTAMP | UNIX时间戳,整型正数,固定长度10,1970年1月1日以来的秒数,表示回调请求发起时间。 |
X-VOD-SIGNATURE | 签名字符串,为32位MD5值,详细说明请参见下文签名算法。 |
签名算法
X-VOD-SIGNATURE的计算依赖如下字段:
字段 | 示例 | 描述 |
---|---|---|
回调URL | https://www.example.com/your/callback | 用户设置的回调地址。 |
X-VOD-TIMESTAMP | 1519375990 | UNIX时间戳,整型正数,固定长度10,1970年1月1日以来的秒数,表示回调请求发起时间。 |
AuthKey | Test123 | 用户预设的鉴权Key(对应 | 设置的鉴权密钥),最长32位,必须同时包含大写字母、小写字母和数字。
将上述三个字段进行拼接,字段中间以竖线(|)分割,后计算MD5值,即:
MD5Content = 回调URL|X-VOD-TIMESTAMP|AuthKey
X-VOD-SIGNATURE = md5sum(MD5Content)
X-VOD-SIGNATURE字段计算方法示例如下:
X-VOD-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****
回调消息接收服务端校验规则
- 回调消息接收端将回调所设置的回调URL、X-VOD-TIMESTAMP取值、AuthKey字符串拼接后,进行MD5值计算,得到加密串,再将加密串与X-VOD-SIGNATURE字段进行对比,如果不一致,则请求非法。
- 回调消息接收端获取当前时间,与回调请求所带的X-VOD-TIMESTAMP字段时间相减,如果超过回调消息接收服务端所设定的指定时间(如5分钟,由回调消息接收服务端自行定义),则认为该请求无效。说明 由于时间设置等问题,时间差值可能会有误差,回调消息接收服务端可自行决定是否进行该校验。
AuthKey切换
用户在切换AuthKey时,为保证回调功能不受影响,回调消息接收服务端需要兼容新旧两个AuthKey的平滑切换,即在一段时间内兼容新旧两个AuthKey的鉴权,由回调消息接收服务端完成。
建议操作顺序如下:
- 用户定义新的AuthKey。
- 用户升级回调消息接收服务端,兼容新、旧两个AuthKey的鉴权。
- 在点播控制台将AuthKey更新成最新。
- 观察一段时间后,回调消息接收服务端去掉对原来旧AuthKey的兼容。
- 切换完成。
HTTP回调使用方法
前提条件
- 您已部署用于接收回调消息的HTTP/HTTPS服务。
您已经注册了阿里云账号并完成账号实名认证。注册地址请参见阿里云官网。注册指引请参见注册阿里云账号。实名认证指引请参见个人实名认证或企业实名认证。
您已经开通了视频点播服务。开通步骤请参见开通视频点播服务。
使用限制
视频点播服务支持多个存储地域,各存储地域之间事件通知的配置是相互独立的,即每个地域可以单独配置事件通知的回调方式和回调地址。您可以上传视频到不同地域的存储中,当视频处理(如上传、转码等)完成后,视频点播服务会根据存储地域配置的回调地址及时通知您。
使用流程
- 在视频点播服务中配置HTTP回调方式的事件通知。
在视频点播服务中配置回调URL、按需选择配置相应类型的事件通知,视频点播支持的事件通知类型及各事件通知含义请参见事件列表。
视频点播支持通过控制台或API/SDK的方式配置事件通知,具体配置方法如下:- 控制台方式
登录视频点播控制台,在左侧导航栏选择 ,进入回调设置页面,配置回调URL并选择需要回调的事件。详细操作请参见回调设置。
说明- 控制台方式设置的回调为针对视频点播服务全局的配置。
- 勾选视频AI处理完成后,所有的AI事件如AIMediaAuditComplete、AIMediaDNAComplete、AIVideoTagComplete等完成后都会触发通知。
- API/SDK方式
通过API/SDK的方式,通过调用不同的接口,支持对视频点播服务进行全局配置回调或单此请求覆盖回调。
- 全局配置:调用SetMessageCallback - 设置事件通知配置接口,请求参数
CallbackType
指定为HTTP
,并配置CallbackURL
(回调地址)、EventTypeList
(回调事件类型)等其他参数。 - 单次请求覆盖:通过CreateUploadVideo - 获取音视频上传地址和凭证、SubmitTranscodeJobs - 提交媒体转码作业等接口上传媒资文件或发起媒体处理任务时,通过指定请求参数
UserData
中的MessageCallback字段来设置单次请求的回调地址。
说明 通过指定UserData
中的MessageCallback
字段来设置回调时,仅支持设置HTTP方式的回调,且需要在已开启全局的事件通知并配置相应的回调事件类型后,此处的回调配置才能生效。 - 全局配置:调用SetMessageCallback - 设置事件通知配置接口,请求参数
- 控制台方式
- 触发回调事件。
完成事件通知配置后,您可以在视频点播服务中执行上传媒资文件(音/视频或图片),发起媒体处理(转码、截图等)等操作来触发相应的回调事件产生。
- 接收回调事件。
当回调事件产生后,若回调成功,您可以在您部署的回调接收服务中查看回调事件通知。
相关文档
- 有关HTTP回调与MNS回调的对比,请参见HTTP回调与MNS回调对比。
- 使用过程中遇到问题时,请参见事件通知常见问题。