回调管理

回调简介

当直播过程中某些事件被触发时，阿里云将主动发送请求到客户服务器，客户服务器负责应答请求，验证通过后，您可接收到事件回调信息的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秒内，如果推流端不主动断开，阿里云直播服务就会发推流成功回调。
    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进行配置。

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

• 直播录制回调设置方式
  • 控制台

    在视频直播控制台的域名管理页面，选择需要配置的播流域名，单击域名配置，进入直播管理 > 回调事件 > 回调设置页面，开启录制至OSS回调开关，添加或修改回调地址。具体操作请参见录制至OSS回调。

  • 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	JSONObject	否	具体格式的录制周期变化。取值范围：5~21600。单位：秒。
  Format	JSONArray	否	录制格式。支持MP4、FLV、M3U8。

• 请求示例

  GET /?app=seq_all&domain=demo.aliyundoc.com&stream=ondemand8&vbitrate=2000&codec=h264 HTTP/1.1
  Host: pull.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会被截断，以防恶意攻击。

直播截图回调

视频直播支持直播截图结果回调，您可以在控制台或通过API配置回调地址。

• 截图回调设置方式
  • 控制台

    在视频直播控制台的域名管理页面，选择需要配置的播流域名，单击域名配置，进入直播管理 > 回调事件 > 回调设置页面，开启截图回调开关，添加或修改回调地址。具体操作请参见截图回调。

  • API

    接口	描述	参考文档
    AddLiveSnapshotNotifyConfig	添加截图回调配置。	添加截图回调配置
    UpdateLiveSnapshotNotifyConfig	修改截图回调配置。	修改截图回调配置
    DescribeLiveSnapshotNotifyConfig	获取截图回调配置。	获取截图回调配置
    DeleteLiveSnapshotNotifyConfig	删除截图回调配置。	删除截图回调配置

• • 截图文件回调参数

    参数	描述
    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"
    }

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

智能审核回调

视频直播支持视频审核和语音审核的结果回调，您可以在控制台或通过API配置回调地址。

• 视频审核回调设置方式
  • 控制台

    您可以在视频直播控制台的域名管理页面需要选择配置的播流域名，单击域名配置，进入直播管理 > 回调事件 > 回调设置页面，开启视频审核回调开关，添加或修改回调地址。具体操作请参见视频审核回调。

    说明 目前仅部分直播中心支持直播智能审核，具体支持该功能的直播中心，请参见 服务地域。
  • API

    接口	描述	参考文档
    AddLiveDetectNotifyConfig	添加直播视频审核回调配置。	添加直播审核回调配置
    DescribeLiveAudioAuditNotifyConfig	查询直播视频审核回调配置。	查询直播审核回调配置
    UpdateLiveDetectNotifyConfig	更新直播视频审核回调配置。	更新直播审核回调配置
    DeleteLiveDetectNotifyConfig	删除直播视频审核回调配置。	删除直播审核回调配置

• 视频审核回调

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

  • 视频审核回调参数

    参数	类型	描述
    DomainName	String	播流域名。
    AppName	String	应用名称。
    StreamName	String	流名称。
    OssEndpoint	String	存储对象Endpoint。
    OssBucket	String	存储对象的Bucket。
    OssObject	String	存储对象的文件名。
    Result	JSONArray	检测结果。请参见Result。

    表 1. Result

    参数	类型	描述
    BizType	String	业务类型。可用于选择模型，默认值为域名。
    Scene	String	检测场景 porn：鉴黄。 terrorism：暴恐涉政。 ad：图文违规。 live：不良场景。 logo：图片logo。
    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：车内直播。 图片logo（logo）结果分类： normal：正常。 TV：含受管控的logo。 trademark：含商标。
    Rate	Float	置信度分数。取值范围：0（表示置信度最低）~100（表示置信度最高）。 说明 该值仅作为参考，强烈建议您不要在业务中使用。建议您参考Label结果用于内容违规判定。
    Extent	String	预留字段。

    说明 默认新用户将使用此版本，老用户维持不变，如需使用此版本，请您 提交工单。关于如何提交工单，请参见联系我们。。
  • 视频审核回调参数示例

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

• 语音审核回调设置方式
  • 控制台

    您可以在视频直播控制台的域名管理页面需要选择配置的播流域名，单击域名配置，进入直播管理 > 回调事件 > 回调设置页面，开启语音审核回调开关，添加或修改回调地址。具体操作请参见语音审核回调。

  • API

    接口	描述	参考文档
    AddLiveAudioAuditNotifyConfig	添加直播语音审核回调配置。 重要 直播语音审核回调返回为JSON字符串。	添加直播语音审核回调配置
    DeleteLiveAudioAuditNotifyConfig	删除直播语音审核回调配置。	删除直播语音审核回调配置
    UpdateLiveAudioAuditNotifyConfig	更新直播语音审核回调配置。	更新直播语音审核回调配置
    DescribeLiveAudioAuditNotifyConfig	查询直播语音审核回调配置。	查询直播语音审核回调配置

• 语音审核回调

  只会对于有问题的音频内容进行回调通知，通知内容包含问题语音的文本信息以及最近一分钟内的上下文信息。

  • 语音审核回调参数

    参数	类型	描述
    domain	String	播流域名。
    app	String	应用名称。
    stream	String	流名称。
    timestamp	Int	回调时间戳。单位：秒。
    result	JSONArray	检测结果。请参见Result。

    表 2. Result

    参数	类型	描述
    scene	String	检测场景。
    label	String	检测结果的分类。取值： normal：正常文本 spam：含垃圾信息 ad：广告 politics：涉政 terrorism：暴恐 abuse：辱骂 porn：色情 flood：灌水 contraband：违禁 meaningless：无意义 customized：自定义（例如命中自定义关键词）
    suggestion	String	处理建议。取值： pass：结果正常，无需进行其余操作。 review：结果不确定，需要进行人工审核。 block：结果违规，建议直接删除或者限制公开。
    rate	Float	置信度分数。取值范围：0（表示置信度最低）~100（表示置信度最高）。 说明 该值仅作为参考，强烈建议您不要在业务中使用。建议您参考Label结果用于内容违规判定。
    details	JSONArray	语音对应的文本详情，每一句文本对应一个元素，可以包含一个或者多个元素。关于每个元素的结构描述，请参见Detail。

    表 3. Detail

    参数	类型	描述
    startTime	Int	句子开始的时间戳，单位：秒。
    endTime	Int	句子结束的时间戳，单位：秒。
    text	String	问题语音转换成文本的结果。
    label	String	检测结果的分类。取值： normal：正常文本 spam：含垃圾信息 ad：广告 politics：涉政 terrorism：暴恐 abuse：辱骂 porn：色情 flood：灌水 contraband：违禁 meaningless：无意义 customized：自定义（例如命中自定义关键词）

  • 语音审核回调参数示例

    {
        "domain": "example.aliyundoc.com",
        "app": "liveApp****",
        "stream": "5d9747eba39b44769852d276f9ff****",
        "timestamp": 1572248095,
        "result": [
            {
                "scene": "antispam",
                "label": "ad",
                "suggestion": "block",
                "rate": 99.91,
                "details": [
                    {
                        "startTime": 1572248023,
                        "endTime": 1572248040,
                        "text": "丽江陇川等酒店免费居住权120天居住权可与亲友共享来云栖社国际烧酒店接待中心地址芒市团结大街96号邓朝ktv旁咨询热线2285699",
                        "label": "ad"
                    },
                    {
                        "startTime": 1572248040,
                        "endTime": 1572248070,
                        "text": "典藏经典别墅尊享隆多温泉、梁河金塔、温泉旅游小镇二期滨江苑地区11月2号盛大开盘天然龙窝、温泉水入户户型多样，设计经典价位超值，值得您拥有开盘当天还有超值优惠，欢迎您前来品鉴，凭借地址，然和县遮岛镇先锋路229号分享热线0692695577769***
    ",
                        "label": "normal"
                    },
                    {
                        "startTime": 1572248072,
                        "endTime": 1572248077,
                        "text": "快乐的时光，有你相伴惬意的日子，格外轻松。",
                        "label": "normal"
                    },
                    {
                        "startTime": 1572248078,
                        "endTime": 1572248086,
                        "text": "fme043忙里偷闲音乐时光有歌曲温暖，有你想念影院。",
                        "label": "normal"
                    }
                ]
            }
        ]
    }