如何通过控制台配置回调服务-阿里云帮助中心

低代码音视频工厂支持配置回调来接收某些重要事件的通知。当事件被触发时，回调服务将主动发送请求到客户的服务器，服务器应答请求并验证通过后，可以接收到该事件回调消息的JSON数据包。本文介绍了回调服务支持的事件、配置步骤、回调参数说明和示例。

支持回调的事件

重要

旧版低代码方案（原低代码音视频工厂，以下简称低代码1.0）计划于2023年9月30日下线，在此之前低代码1.0的客户可继续使用旧版互动直播或互动课堂的功能直至2023/9/30停服，请您尽快切换至低代码2.0或视频直播。
升级说明请参见低代码方案升级说明。升级咨询可加钉钉群10570030108（仅限升级咨询，如您有售后问题请提交工单）。
新旧方案计费规则不同，资源包不可互通使用。低代码音视频工厂未消费的资源包可以申请按比例退款。

回调事件	事件说明
推流状态	推流域名的推流状态变更的通知回调，包括推流成功和断流状态。
直播状态	直播状态变更的事件通知回调，包括直播开始、直播结束。
直播审核结果	直播视频审核的结果回调，只会对有问题的视频内容进行回调通知，通知内容包含问题视频截图的审核信息和存储信息。
消息审核结果	互动消息审核的结果回调，只会对于有问题的文本信息进行回调通知。
用户进出	用户进出房间的事件通知回调，包括进入房间和离开房间。
消息转存	支持将通过客户端SDK发送的文本消息回调至客户的业务服务端，而不会进行下行推送。客户服务端可以按照自己的业务逻辑进行相应处理，调用服务端发送文本消息接口将消息推送至客户端。
课堂状态	课堂状态变更的事件通知回调，包括课程开始、课程结束。
视频录制	课堂视频录制变更的事件通知回调，包括视频录制结束。

操作步骤

登录低代码音视频工厂控制台。
在左侧导航栏选择应用列表，进入应用列表页面。单击目标应用对应在操作列的应用配置。
在回调配置中，勾选您需要接收通知的回调事件，并填写回调地址。填写说明详见下表。
部署一个HTTP（HTTPS）服务用于接收回调消息。请求类型详见下表。

解析回调消息内容。回调格式详见下表，具体参数说明详见本文档不同事件的回调参数说明。

当回调事件是...	控制台需要填写...	回调服务会...	回调格式是...
推流状态	推流回调地址	向推流回调地址发起HTTP GET请求，具体内容将通过URL参数送达	特殊回调格式
直播审核结果	直播审核回调地址	向直播审核回调地址发起HTTP POST请求，具体内容将通过Form表单送达	特殊回调格式
直播状态、消息审核结果、用户进出、消息转存、课堂状态、视频录制事件	统一回调地址中的回调地址和回调鉴权码	向统一回调地址发起HTTP POST请求，具体内容将通过Form表单送达	通用回调格式，格式介绍见下表

通用回调格式介绍：

参数	类型	描述
requestId	String	回调消息的唯一ID标识。
source	String	回调消息的类别。 event_live：当前回调消息属于直播事件。 event_security：当前回调消息属于安全审核事件。 event_chat：当前回调消息属于消息事件。 event_user：当前回调消息属于用户事件。
eventType	String	回调消息的类型，表明当前回调消息是具体哪一个回调事件。详情请参考本文下方各回调事件介绍。
body	JSONString	具体的消息内容，不同的eventType对应的body内容不同。详情请参考本文下方各回调事件介绍。
data	JSONString	已废弃，请使用body字段。

不同事件的回调参数说明

推流状态

将当前域名的推流状态转发至推流回调地址，包括推流成功和断流状态。

回调参数说明

推流状态回调格式和通用回调格式不同，具体如下：

参数	类型	说明
action	String	推流事件。 publish：推流。 publish_done：断流。
ip	String	推流的客户端IP。
id	String	直播的id，即liveId的值。
app	String	推流域名。默认为自定义的推流域名，如果未绑定推流域名即为播流域名。
appname	String	推流应用名称。
time	Long	Unix时间戳，单位：秒。
usrargs	String	用户推流的参数。
node	String	CDN接受流的节点或者机器名。
height	String	分辨率的高。单位：像素。
width	String	分辨率的宽。单位：像素。

推流参数示例

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

断流参数示例

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

更多直播推流状态说明，请参见视频直播-直播推流状态回调。

直播状态

支持直播状态变更的事件通知回调，包括直播开始、直播结束。

回调参数说明

采用通用回调格式，具体如下：

参数	类型	说明
requestId	String	每次回调都对应不同的requestId。
source	String	取值event_live。
eventType	String	直播开始：live_publish。直播结束：live_stop。
body	JSON	取值参考下表。

body参数取值表：

参数	类型	说明
type	String	回调消息类型。同eventType。
liveId	String	直播实例ID。
uuid	String	直播实例ID，与liveId值相同，推荐使用liveId。
operatorId	String	操作者ID。
roomId	String	所属房间ID。
timestamp	Long	操作发生时间戳。单位：毫秒。

直播开始参数示例

{
    "requestId": "08b3****c923",
    "source": "event_live",
    "eventType": "live_publish",
    "body": {
        "type":"live_publish",
        "uuid":"831b****c2ea",
        "operatorId":"user01",
        "roomId" : "bf67b****1e33",
        "timestamp":1624982400000
    }
}

直播审核结果

支持直播视频审核的结果回调，只会对有问题的视频内容进行回调通知，通知内容包含问题视频截图的审核信息和存储信息。

回调参数说明

直播审核结果回调格式和通用回调格式不同，具体如下：

参数	类型	说明
DomainName	String	播流域名。
AppName	String	应用名称。
StreamName	String	流名称，这里默认填写liveId。
OssEndPoint	String	存储对象EndPoint。
OssBucket	String	存储对象的Bucket。
OssObject	String	存储对象的文件名。
Result	JSONArray	检测结果，请参见下表。

直播审核检测结果表：

参数	类型	说明
BizType	String	业务类型。可用于选择模型，默认值为域名。
Scene	String	检测场景，根据控制台选择的直播审核级别不同有如下取值：普通审核，包含如下取值： porn：鉴黄 terrorism：暴恐涉政。严格审核，包含如下取值： porn：鉴黄。 terrorism：暴恐涉政。 ad：图文违规。 live：不良场景。
Label	String	检测结果的分类。不同检测场景的结果分类不同，具体如下：图片智能鉴黄（porn）结果分类： normal：正常。 sexy：性感。 porn：色情。图片暴恐涉政（terrorism）结果分类： normal：正常。 bloody：血腥。 explosion：爆炸烟光。 outfit：特殊装束。 logo：特殊标识。 weapon：武器。 politics：涉政。 violence：打斗。 crowd：聚众。 parade：游行。 carcrash：车祸现场。 flag：旗帜。 location：地标。 others：其他。图文违规（ad）结果分类： normal：正常。 ad：其他广告。 npx：牛皮癣广告。 qrcode：含二维码。 programCode：含小程序码。不良场景（live）结果分类： normal：正常。 meaningless：图片中无内容（例如，黑屏、白屏）。 PIP：画中画。 smoking：吸烟。 drivelive：车内直播。
Rate	Float	置信度分数。取值范围：0（表示置信度最低）~100（表示置信度最高）说明该值仅作为参考，强烈建议您不要在业务中使用。建议您参考Label结果用于内容违规判定。
Extent	String	预留字段。

示例

{
 "DomainName": "example.aliyundoc.com",
 "AppName": "app****_name",
 "StreamName": "stream****_name",
 "OssEndpoint": "oss-cn-hang****.aliyuncs.com",
 "OssBucket": "example",
 "OssObject": "example.jpg",
 "Result": [
     {
         "BizType": "example.aliyundoc.com",
         "Result": [
             {"Label": "Porn", "Rate":11, "Suggestion": "review", "Scene":"porn", "Extent": {}},
             {"Label": "Ad", "Rate":11, "Suggestion": "review", "Scene":"ad", "Extent": {}}
         ]
     }
 ]
}

互动消息审核

支持对互动消息审核的结果回调，只会对于有问题的文本信息进行回调通知。

回调参数说明

采用通用回调格式，具体如下：

参数	类型	说明
requestId	String	每次回调都对应不同的requestId。
source	String	取值event_security。
eventType	String	取值comment_security_refused。
body	JSON	取值参考下表。

body参数取值表：

参数	类型	说明
appId	String	应用ID。
roomId	String	房间ID。
commentId	String	互动消息的唯一ID标识。
creatorId	String	互动消息的发送者ID。
creatorNick	String	互动消息的发送者昵称。
createAt	Long	互动消息的发送时间，Unix时间戳，单位：毫秒。
content	String	互动消息的具体内容。
extension	Map	扩展字段，该字段是调用sendComment时传入的字段。
result	String	被拦截的原因。取值： porn：色情。 politics：非法政治。 unknown：未知风险点。

示例

{
    "requestId":"08b3****c923",
    "source":"event_security",
    "event_type":"comment_security_refused",
    "body":{
        "appId":"example",
        "roomId":"bf67b****1e33",
        "commentId":"0d**Kg",
        "content":"example message",
        "createAt":1632380515534,
        "creatorId":"62**59",
        "creatorNick":"张三",
        "extension":{},
        "result":"unknown"
     }"
}

用户进出

支持用户进出房间的事件通知回调，包括进入房间和离开房间。

回调参数说明

采用通用回调格式，具体如下：

参数	类型	说明
requestId	String	每次回调都对应不同的requestId。
source	String	取值event_user。
eventType	String	取值user_enter_room。
body	JSON	取值参考下表。

body参数取值表：

参数	类型	说明
appId	String	应用ID。
roomId	String	房间ID。
userId	String	用户ID。
deviceId	String	设备ID。
type	Integer	0-进入房间，1-离开房间。
timestamp	Long	事件发生的Unix时间戳，单位：毫秒。

进入房间示例

{
    "requestId":"08b3****c923",
    "source":"event_user",
    "event_type":"user_enter_room",
    "body":{
        "appId":"example",
        "roomId":"bf67b****1e33",
        "userId":"62**59",
        "deviceId":"a2sh***12de",
        "type":0,
        "timestamp":1632380515534
     }
}

消息转存回调

支持将通过客户端SDK发送的文本消息回调至客户的业务服务端，而不会进行下行推送。客户服务端可以按照自己的业务逻辑进行相应处理，调用服务端发送文本消息接口将消息推送至客户端。

回调参数说明

采用通用回调格式，具体如下：

参数	类型	说明
requestId	String	每次回调都对应不同的requestId。
source	String	取值event_chat。
eventType	String	取值comment_forward。
body	JSON	取值参考下表。

body参数取值表。

参数	类型	说明
appId	String	应用ID。
roomId	String	房间ID。
commentId	String	互动消息的唯一ID标识。
creatorId	String	互动消息的发送者ID。
creatorNick	String	互动消息的发送者昵称。
createAt	Long	互动消息的发送时间，Unix时间戳，单位：毫秒。
content	String	互动消息的具体内容。
extension	Map	扩展字段，该字段是调用sendComment时传入的字段。

示例

{
    "requestId":"08b3****c923",
    "source":"event_chat",
    "event_type":"comment_forward",
    "body":{
        "appId":"example",
        "roomId":"bf67b****1e33",
        "commentId":"0d**Kg",
        "content":"example massage",
        "createAt":1632380515534,
        "creatorId":"62**59",
        "creatorNick":"张三",
        "extension":{}
     }

课堂状态

支持课堂状态变更的事件通知回调，包括课程开始、课程结束。

回调参数说明

采用通用回调格式，具体如下：

参数	类型	说明
requestId	String	每次回调都对应不同的requestId。
source	String	取值event_class。
eventType	String	课程开始：class_begin。课程结束：class_end。
body	JSON	取值参考下表。

body参数取值表：

参数	类型	说明
appId	String	应用ID。
classId	String	课程ID。
operatorId	String	操作者ID。
timestamp	Long	事件发生的Unix时间戳。单位：毫秒。

课程开始示例

{
    "requestId":"08b3****c923",
    "source":"event_class",
    "event_type":"class_begin",
    "body":{
        "appId":"example",
        "classId":"bf67b****1e33",
        "operatorId":"62**59",
        "timestamp":1632380515534
     }
}

视频录制回调

支持课堂视频录制变更的事件通知回调，包括视频录制结束。

回调参数说明

采用通用回调格式，具体如下：

参数	类型	说明
requestId	String	每次回调都对应不同的requestId。
source	String	event_class。
eventType	String	record_finished。
body	JSON	取值参考下表。

body参数取值表：

参数	类型	描述
appId	String	应用ID。
classId	String	课程ID。
fileType	String	文件类型。取值：m3u8
playbackUrl	String	文件地址，存在有效期，需要通过接口动态获取。
status	String	是否生成回放。取值： success：成功，请从playbackUrl中获取回放文件。 fail：失败，请参考错误码，进一步排查。
errorCode	String	错误码。取值： NoRecordContent：没有回放内容。请检查录制配置，并确认录制时长大于一分钟。 OssNotAuthorized：OSS没有授权。授权请参见授权访问OSS。 InternalError：内部错误。请检查录制配置或请稍后重试。
timestamp	Long	事件发生的Unix时间戳。单位：毫秒。

视频录制结束示例

{
    "requestId":"08b3****c923",
    "source":"event_class",
    "event_type":"record_finished",
    "body":{
        "appId":"example",
        "classId":"bf67b****1e33",
        "fileType":"m3u8",
        "playbackUrl":"http://rtc-record.****.aliyuncs.com/record/0902-1/9q****/record-004_task-005/2020-09-02-18-23-56_2020-09-02-18-53-56.m3u8",
        "status":"success",
        "errorCode":"",
        "timestamp":1632380515534
     }
}

回调服务实现

以Java语言为例，回调服务接口的主要实现逻辑如下所示：

public ResponseResult<Object> callback(HttpServletRequest request){
    // 假设控制台设置的回调地址为（如部署在ecs **.**.**.**，端口为****，建议使用HTTPS和域名）
    String appCallbackUrl = "https://example.aliyundoc.com";
        
    // 假设控制台设置的回调鉴权码为callbackSecret
    String appCallbackAuthKey = "callbackSecret";

    // 获取source和eventType
    String source = request.getParameterMap().get("source")[0];
    String eventType = request.getParameterMap().get("eventType")[0];

    // 从request提取params和headers
    // ...

    // 验证签名（可选，根据控制台设置的回调鉴权码进行鉴权，保证回调安全性，具体实现请参照回调示例代码）
    boolean verify = SignUtil.verifySign(appCallbackAuthKey, "POST", appCallbackUrl, params, headers);
    // 回调鉴权失败
    if(!verify){
        // 鉴权失败处理逻辑
        // return...
    }

    switch (source) {
        // 直播能力回调处理
        case "event_live":
            // 回调处理逻辑，出入参数详见上文：回调接口详情
        // ***回调处理
        case "event_***": 
            // 回调处理逻辑
    }
}

回调服务验签

本产品服务会根据配置的回调鉴权码在HTTP（含HTTPS）回调时增加特定签名头，供回调消息接收服务端进行签名认证，以防止非法或无效请求。

签名机制：本产品服务在发起回调请求时，会根据应用配置的回调鉴权码+公共参数+自定义参数进行签名，签名结果串与参与签名的公共参数一起包含在Headers中发起请求，回调消息接收方可依此进行验签。签名公共参数如下所示：

参数	类型	是否必选	描述
a-app-id	String	是	签名App标识，取值：IMP。
a-signature	String	是	签名结果串。
a-signature-method	String	是	签名方式。取值：HMAC-SHA1。更多信息，请参见HMAC-SHA1签名逻辑。
a-timestamp	String	是	请求的时间戳。日期格式按照ISO8601标准表示，使用UTC时间，格式为yyyy-MM-ddTHH:mm:ssZ。例如：2020-06-30T12:00:00Z为北京时间2020年6月30日的12点0分0秒。
a-signature-version	String	是	签名算法版本。取值：1.0。
a-signature-nonce	String	是	唯一随机数。在不同请求间使用不同的随机数值，防止网络重放攻击。

以Java语言为例，HMAC-SHA1验签逻辑如下所示：

private static final String ALGORITHM_NAME = "HmacSHA1";
private static final String ENCODING = "UTF-8";
public static final String SIGNATURE = "a-signature"; // 签名结果串

/**
 * @param signSecret 回调鉴权码
 * @param method     请求方式，取值POST
 * @param path       回调服务URL
 * @param params     请求参数，KV形式
 * @param headers    请求头部（含签名结果串和签名公共参数），header名全小写
 */
public static boolean verifySign(String signSecret, String method, String path,
                                 Map<String, String> params,
                                 Map<String, String> headers){
    
    // 1. 获取签名结果串
    String signature = headers.remove(SIGNATURE);
        
    // 2. 请求params、headers、结果串等入参数检查，非空检查及签名方式、算法版本检查
    // ...
    
    // 3.构造签名字符串stringToSign
    //   3.1 从headers中提取签名公共参数signedHeaders
    //   3.2 构造规范化的params/signedHeaders字符串（参数按key排序后，组合成&key=value形式）
    //   3.3 与method, path一起构造签名字符串stringToSign
    
    // 4. 计算签名
    String expectedSignature = sign(stringToSign, signSecret + "&");
   
    // 5. 校验签名
    return signature.equals(expectedSignature);   
}
    

/**
 * HMAC-SHA1签名计算
 */
public static String sign(String stringToSign, String signSecret) {
    try {
        Mac mac = Mac.getInstance(ALGORITHM_NAME);
        mac.init(new SecretKeySpec(
                signSecret.getBytes(ENCODING),
                ALGORITHM_NAME
        ));
        byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));
        String signBase64 = DatatypeConverter.printBase64Binary(signData);
        return percentEncode(signBase64);
    } catch (NoSuchAlgorithmException | UnsupportedEncodingException | InvalidKeyException e) {
        throw new IllegalArgumentException(e.toString(), e);
    }
}

完整代码请参见GitHub。