NTV Media Server CMS Data Query Specification
Version 2.0
NovelTV Inc.
J. Wang
Jan. 8, 2018
向集成客户端提供查询数据和登录服务。
如果资源需要授权才能查看和使用,请首先阅读“5.登录验证”小节。
客户端和服务器通过HTTP协议通信,客户端使用HTTP Get向服务器发送请求,服务器返回json格式的业务数据或操作结果给客户端。
接口地址是一个HTTP协议的url地址,具体格式是:
http://ip/mserver/cms/interface2/catalog/?parent=1&token=abcdefg
ip替换成实际服务器的ip或域名,如果端口不是默认端口,需要把端口加上。
token是认证字符串,在登录接口中获取,如果没有登录则省略。
其他内容参见接口的定义。
当URL请求参数值中包含URL地址保留字符时,应对参数值进行URL编码。
具体参见“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
当请求参数包含中文字符时,应对中文字符采用UTF-8编码。
返回的json消息数据结构具有严格的一致性,客户端可以采用一致的接收和解析方式处理返回消息。
简单消息
简单的返回消息包含对请求的处理结果,结构如下:
{
"code":0,
"err_desc":""
}
其中:
code 为0表示处理成功,其它值表示处理失败。
err_desc是对错误的描述,在code为0时err_desc会被省略。
特殊情况,在用户认证的login1和login2接口中,err_desc具有特殊用途用法,具体参见接口描述。除这两个接口之外,err_desc都表示错误描述。
带业务数据的消息
有的返回消息除了包含处理结果信息,还包含业务数据记录集,结构如下:
{
"code":0,
"data":{
"count":1,
"items":[...]
}
}
其中:
data 业务数据的根节点:
count 业务数据的条数,可能的值为0 ~ n
items 业务数据,是一个数组,数据条数由count属性定义。当count为0时,items属性可能为null或者不存在。
本文档后续章节中,在描述items元素的属性时,会省略一些属性的描述,即实际调用接口返回的属性在本文档中可能会没有描述,这种情况下请直接忽略被忽略描述的属性值。本文档中描述的属性是实际返回内容的一个子集,没有描述到的内容对集成本系统没有影响。
带分页数据的消息
如果返回数据较多,服务器会对返回的数据进行分页,客户端可以按照页码请求指定范围的数据。带分页信息的返回数据结构如下:
{
"code":0,
"data":{
"page":1,
"page_size":"20",
"pages":"1",
"total":"2",
"count":2,
"items":[...]
}
}
分页数据信息在data元素下,意义如下:
page当前页码
page_size每页数据记录条数
pages总共的页数
total总数据条数
count当前返回页的数据条数
如果返回的数据带有分页信息,则可以在调用接口时使用page参数来请求指定页码的数据。
[1] RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1[S].
[2] RFC 3986, Uniform Resource Identifier (URI): Generic Syntax[S].
[3] http://www.json.org/ Introducing JSON
用途
查询CMS上的分类信息。
请求
http://ip/mserver/cms/interface2/catalog/?parent=1
parent上级分类编号。如果忽略,会返回一级分类列表。
如果要查询一级分类,请去掉parent参数。
{
"code": 0,
"data": {
"count": 2,
"items": [
{
"id": 1,
"name": "公共栏目",
"comment": "",
"upper_catalog_id": 0
},
{
"id": 2,
"name": "私有栏目",
"comment": "",
"upper_catalog_id": 0
}
]
}
}
id编号
name名称
comment备注
"upper_catalog_id上级分类编号, 0 表示当前分类是一级分类。
用途
查询所有分类及其下级分类。
请求
http://ip/mserver/cms/interface2/catalog/?request=all
{
"code": 0,
"data": {
"count": 2,
"items": [
{
"id": 1,
"name": "公共栏目",
"comment": "",
"upper_catalog_id": 0,
"sub_items": [
{
"id": 5,
"name": "二级分类1",
"comment": "",
"upper_catalog_id": 1
},
...
]
},
...
]
}
}
id编号
name名称
comment备注
"upper_catalog_id上级分类编号, 0 表示当前分类是一级分类。
sub_items下级分类数组,包含 0 或多个下级分类。
用途
查询媒体资源。
可以查询某个编号的资源的信息,也可以查询某个分类下的所有资源信息。
请求
http://ip/mserver/cms/interface2/media/?parent=2
parent分类编号,如果要查询某个分类下的所有资源,请忽略下一个参数。
media_id资源编号,如果给出该参数,则只查询编号为media_id的一个资源的信息,并忽略parent参数。
{
"code": 0,
"data": {
"page": 1,
"page_size": "20",
"pages": 9,
"total": "18",
"count": 2,
"items": [
{
"id": 79,
"catalog_id": 2,
"title": "vod - 8898",
"sub_title": "G3视频",
"abstract": null,
"text": null,
"resource_type": "vod",
"cover": "/mserver/cms/covers/res_cover_79.jpg?1515729601",
"duration": 98,
"add_time": "2018-01-08 19:19:26",
"view_times": 0,
"open_status": 0
},
...
]
}
}
返回0个或多个资源信息。
id资源编号
catalog_id所属分类编号
title标题
sub_title小标题
abstract摘要描述
text描述
resource_typevod或live
cover封面地址
duration播放时长
add_time添加时间
view_times观看次数
open_status开放状态
用途
查询某个媒体资源的播放地址。
请求
http://ip/mserver/cms/interface2/url/?media_id=39&protocol=http-mp4
media_id资源编号。
protocol播出协议,点播资源可以是hls,http-flv或http-mp4;直播资源可以是 rtmp或hls。如果省略,返回所有协议的地址。
客户端请根据终端类型选用合适的播出协议:
android、ios或其他支持H5的浏览器,可以选用:hls, http-mp4协议
PC选用http-flv或rtmp协议
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"id": 104,
"resource_id": 39,
"web_url": "/mp4/vod/yellowstone/yellowstone.mp4",
"web_io_protocol": "http-mp4",
"add_time": "2017-08-25 16:35:16"
}
]
}
}
返回0个或多个播放地址,一个资源可能有多个不同协议的播放地址。
resource_id资源编号
web_url播出地址
"web_io_protocol播出协议
1)登录的要求和意义
客户端应当选判断服务器是否要求必须登录。如果要求,则应首先调用登录接口登录,然后再请求其他接口。
是否需要强制登录,跟运营需求有关,网站运营者可以通过管理平台设置这个选项。
如果没有强制要求,客户端可以登录,也可以不登陆。
用户正确登录后,会获得一个token值,在后续的接口中,应当将该token值带入。例如:
http://ip/mserver/cms/interface2/media/?parent=2&token=abcdefg
请求
http://ip/mserver/cms/interface2/user/?request=needslogin
{
"code": 0,
"err_desc": "no"
}
err_desc属性描述了对登录的要求。no 表示不强制要求, yes 表示必须要求登录。
用途
提交认证申请,接口返回挑战字符串。
请求
http://ip/mserver/cms/interface2/user/?request=login1&username=mrwang
username登录用户名。
{
"code": 0,
"data": {
"count": 1,
"items": [
{
"id": 37,
"chcode": "9luqgrnj5vvszmjw"
}
]
}
}
idsession识别号,用于login2接口,原样传递给login2即可。
chcode挑战字符串,客户端按约定规则使用该字符串生成一个hash值,然后调用login2接口。
用途
使用login1返回的chcode计算出一个hash值,提交给本接口申请到一个token。该token值用于其他接口的认证。
请求
http://ip/mserver/cms/interface2/user/?request=login2&id=34&hash=7ecc1447c24c1722c3d9bce09fe6cf18
idlogin1接口返回的id值,原样带入。
hash根据约定计算出的hash值。算法:
hash=md5(md5(password)+chcode)
描述:首先计算出密码的hash值,然后在生成的密码hash值尾部拼接上挑战字符串形成新的字符串,最后计算这个新字符串的hash值。
hash算法采用md5算法,生成的摘要采用16进制编码,编码生成的字符采用小写字母。
例如,字符串111111的hash值是 96e79218965eb72c92a549dd5a330112
{
"code": 0,
"data": {
"count": 6,
"items": [{
"id": 2,
"name": "王工",
"sex": 1,
"logo": null,
"token": "c9xpghlmgxn58kdq",
"group_id": 1
}]
}
}
name用户名
sex性别,1男 0女
logo用户头像,null或者头像url
token认证令牌,在无法保持session的情况下,在请求其他接口中应当将token参数带入
group_id用户所属的用户组
用途
退出登录,退出应用前请尽量调用该接口。
请求
http://ip/mserver/cms/interface2/user/?request=logout&token =abcdefg
token登录接口中获得的token
{
"code": 0,
}
创新互联www.cdcxhl.cn,专业提供香港、美国云服务器,动态BGP最优骨干路由自动选择,持续稳定高效的网络助力业务部署。公司持有工信部办法的idc、isp许可证, 机房独有T级流量清洗系统配攻击溯源,准确进行流量调度,确保服务器高可用性。佳节活动现已开启,新人活动云服务器买多久送多久。