产品解决方案文档与社区权益中心定价云市场合作伙伴支持与服务了解阿里云
备案控制台登录/注册
首页 视频直播 开发参考 开发指南 直播管理 回调管理

回调管理

更新时间: 2023-11-23 18:13:16

视频直播提供直播推流状态、直播录制、按需录制、直播截图和智能审核的事件回调，本文介绍这些回调的设置方式、回调参数和示例。

回调简介

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

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

回调方式

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

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

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

注意事项

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

直播推流状态回调

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

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

  • 直播推流状态回调

    推断流状态回调会将参数封装在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进行配置。

  • 录制状态回调：在文件开始录制与结束录制时发出，主要表示文件已经开始和结束录制。

  • 文件生成回调：在文件生成时发出，主要包括文件名称，开始结束时间与时长信息。

  • 直播录制回调设置方式

    • 控制台

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

    • 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个参数），来询问用户是否需要录制这路流。

  • 请求参数

    参数类型描述
    domainString主播流域名。
    appString播流所属应用名称。
    streamString播流名称。
    codecString编码方式。取值：
    • h264
    • h265
    vbitrateString视频码率。单位：kbps。

  • 返回参数

    参数类型是否必选描述
    ApiVersionString否

    API版本。默认为1.0版本。

    NeedRecordBool是是否需要录制。
    IntervalJSONObject否具体格式的录制周期变化。取值范围：5~21600。单位：秒。
    FormatJSONArray否录制格式。支持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配置回调地址。

  • 视频审核回调设置方式

  • 视频审核回调

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

    • 视频审核回调参数

      参数

      类型

      描述

      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": {}}
         ]
     }
 ]
}

  • 语音审核回调设置方式

  • 语音审核回调

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

    • 语音审核回调参数

      参数

      类型

      描述

      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：无意义

      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：无意义

    • 语音审核回调参数示例

      {
    "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"
                }
            ]
        }
    ]
}
阿里云首页 视频直播 相关技术圈
为什么选择阿里云什么是云计算全球基础设施技术领先稳定可靠安全合规分析师报告
产品和定价全部产品免费试用产品动态产品定价价格计算器云上成本管理
解决方案技术解决方案行业解决方案
文档与社区文档开发者社区天池大赛培训与认证
权益中心免费试用高校计划企业扶持计划推荐返现计划
支持与服务基础服务企业增值服务迁云服务官网公告系统状态信任中心
关注阿里云
关注阿里云公众号或下载阿里云APP，关注云资讯，随时随地运维管控云服务
阿里云APP阿里云微信
售前咨询：95187-1
售后服务：400-80-13260
法律声明及隐私权政策Cookies政策廉正举报安全举报联系我们加入我们
阿里巴巴集团淘宝网天猫全球速卖通阿里巴巴国际交易市场1688阿里妈妈飞猪阿里云计算AliOS万网高德UC友盟优酷钉钉支付宝达摩院淘宝海外阿里云盘饿了么
© 2009-2023 Aliyun.com 版权所有 增值电信业务经营许可证： 浙B2-20080101 域名注册服务机构许可： 浙D3-20210002 京D3-20220015
浙公网安备 33010602009975号浙B2-20080101-4
关注我们：
新浪微博
联系我们
© 2009-2023 Aliyun.com 版权所有<br/>增值电信业务经营许可证： <a href="http://beian.miit.gov.cn/" target="_blank">浙B2-20080101</a> <br/>域名注册服务机构许可： <a href="https://domain.miit.gov.cn/域名注册服务机构/互联网域名/阿里云计算有限公司 " target="_blank">浙D3-20210002</a> <a href="https://domain.miit.gov.cn/域名注册服务机构/互联网域名/阿里巴巴云计算北京有限公司 " target="_blank">京D3-20220015</a>