CDN加速

文档中心 直播分发 API文档 直播流状态查询及反馈

直播流状态查询及反馈

更新时间:2021-09-07 16:56:13

一.功能简介

  现如今,游戏直播、美女秀场等互动直播类业务发展势头迅猛,各大专业直播平台备受追捧,此类业务的特点是主播直接将流推送至CDN节点,由CDN进行分发至全国各地。当客户无法获取主播推流信息时,将会无法实时的将直播流放至业务供终端用户观看,也无法计算主播推流时长等信息。
  基于以上场景,网宿提供主播实时或推流状态查询以及主播在推流或断流的流状态实时反馈功能。客户通过调用API的方式,能够获取指定推流域名的流状态实时信息。同时,网宿还提供流状态实时反馈功能,该功能对于在网宿流媒体加速系统上的互动直播业务,实时将主播推流信息及断流信息实时的反馈给客户指定平台。

二.使用说明

2.1 直播流状态查询功能

  直播流状态查询功能包括流状态实时信息,所查询的信息包括主播ip、推流cdn节点ip、推流开始时间、域名、发布点、流名等。其中实时信息接口支持查询实时状态下的流状态信息,主播推流结束后则查询不到信息。

2.1.1 流状态实时查询接口

  API接口
  网宿提供相应流状态实时查询API给客户。具体API 举例如下:
  http://livect.chinanetcenter.com/api/streamStatusRealTime.jsp?domain=xxx&n=xxx&r=xxx&k=xxx&channel=xxx&type=xxx
  入参参数说明

参数名称 必填 描述
n 默认设置为Protal平台帐号名
r 唯一随机字符串,限制最大为25位,推荐使用时间戳
k K值为md5(r+key),即 r 字符串加上key字符串,得到一个新的字符串,再对该字符串做MD5 计算出新值为k 的值。注:key 可向对应客服获取。例:(1) 申请获取到key=012f37a3f2952(2) 随机生成字符串r=1409284800(3) 合并生成字符串new=1409284800012f37a3f2952(4) 使用MD5 计算new 得到 k值b9fed80be752551834eec3e52fa94115
domain 推流域名;支持多域名查询,多域名间用逗号(,)分隔
channel 频道地址。当指定频道,则返回指定频道的查询信息;当参数为空时,默认返回域名下所有频道信息。例:www.wstest.com/live/streamname
type 数据返回格式类型。默认type=0,可选参数type=1,下面给出具体返回格式。

  数据返回
  数据返回可支持以下两种格式,通过入参的type来设定。
  当type=0时,返回格式如下:

{
"retcode": XXX,
    "rettime": "XXX",
    "dataValue": [
        {
            "id": "XXX",
            "time": XXX,
            "ip": "XXX",
            "node": "XXX",
            "app": " XXX",
            "appname": "XXX"
        }
    ]   
}

  当type=1时,返回格式

{
    "retcode": XXX,
    "rettime": "XXX",
    "app/appname/id": 
        {
            "id": "XXX",
            "time": XXX,
            "ip": "XXX",
            "node": "XXX",
            "app": " XXX",
            "appname": "XXX"
        }  
}

  出参参数说明
  客户以上述格式发送HTTP 请求调用该接口时,接口会返回以下信息:

出参 说明
id 流名
time 推流开始时间
ip 主播ip
node 推流cdn节点ip
app 域名
appname 发布点
retcode 数据条数,即查询域名下直播流数
rettime 返回数据的时间

  返回响应码说明

HTTP状态码 语义
200 请求成功
400 请求参数错误
403 无权限

2.2 推断流状态实时反馈

  流状态实时反馈功能通过HTTP接口向客户服务器发送GET请求,将视频流推流成功、断流成功的状态实时反馈给客户,客户服务器响应200状态码则认为反馈成功,若超时无响应,可重新发起请求。
  通知接口定义
  推流成功通知:
  http://xxx/api/cdn/livestart?ip=推流端IP&id=流名&node=节点IP&app=推流域名&appname=发布点&time=XXX&sign=XXX
  断流成功通知:
  http://xxx/api/cdn/liveend?ip=推流端IP&id=流名&node=节点IP&app=推流域名&appname=发布点&time=XXX&sign=XXX
  通知接口说明

相关字段 描述
接收URL 通知接收地址URL(http://xxx/api/cdn/livestart)由客户提供
相关参数格式 以下参数的参数名、含义、数量均可配置,因此,在开通时以客服所提供的格式为准。其中:Ip: 推流端IP,Id: 流名,Node: 节点IP,App: 推流域名,Appname: 发布点
time 为系统当前时间,时间格式为unix时间;时间单位支持秒和毫秒两种,默认精确到秒,可配置。具体值以客服所提供的时间单位为准。
sign 参数sign=MD5(流名_IP_私钥_时间戳)的加密串,其中IP为推流端IP,私钥为客户与网宿约定的口令,可配置。

  客户服务器响应规则
  (1)客户服务器成功接收通知信息,返回200 响应;
  (2)当发起端在规定时间内(可配置,默认10s)未收到返回响应信息,发起端将重新发送一次通知消息(超时重试次数可配置,默认3 次)。
  确认事项
  若需使用推断流反馈功能,需与客服确认如下事项:
  1) 确认通知接口定义,即发送地址、URI相关参数的格式及反馈信息。
  2) 确认发起端未收到响应信息重发判断时长、重发次数。默认10s未收到响应则重发一次。

三.应用场景

  所有直播业务,直播平台需要查询或监控主播的推流状态。

四.注意事项

4.1 流状态查询接口

  1) API 接口中两个参数之间用与号(&)隔开;
  2) 不要在问号(?)后面带空格等不符合HTTP 协议的字符,如果在URL 或目录名中使用这些字符,请务必使用转义符(比如,空格的转义符为%20);
  3) 由于与号(&)是参数的分隔符,分号(;)是不同URL/目录名的分隔符,带这2 个字符的URL 将不能正常推送。
  4) 该调用方式对大小写敏感,在发送HTTP 请求方式调用该接口时,请注意相应的大小写要严格符合要求。

4.2 推断流状态实时反馈

  1) 在约定的重发次数内没有收到客户服务器的响应信息,发送端不再发送流状态;
  2) 为避免不必要的经济权责,该功能不建议作为客户计算主播在线时长的依据,仅作为客户运营的辅助信息。
  3) 接口调用限制5分钟100次;