G3CMS 数据查询接口协议

NTV Media Server CMS Data Query Specification
Version 2.0
NovelTV Inc.
J. Wang
Jan. 8, 2018

1.概述

1.1.用途

向集成客户端提供查询数据和登录服务。
如果资源需要授权才能查看和使用，请首先阅读“5.登录验证”小节。

1.2.通信协议

客户端和服务器通过HTTP协议通信，客户端使用HTTP Get向服务器发送请求，服务器返回json格式的业务数据或操作结果给客户端。

1.3.接口请求

接口地址是一个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编码。

1.4.返回消息结构

返回的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.5.参考

[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

2.查询分类

2.1.查询分类

• 用途
  查询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 表示当前分类是一级分类。

2.2.查询分类树

• 用途
  查询所有分类及其下级分类。
  请求
  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 或多个下级分类。

3.查询媒体资源

3.1.查询媒体资源

• 用途
  查询媒体资源。
  可以查询某个编号的资源的信息，也可以查询某个分类下的所有资源信息。
  请求
  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_type vod或live
cover 封面地址
duration 播放时长
add_time 添加时间
view_times 观看次数
open_status 开放状态

3.2.查询轮播资源

• 用途
  查询轮播列表的资源，用于CMS站点中展示轮播内容。接口默认返回第一个轮播列表的资源。
  请求
  http://ip/mserver/cms/interface2/media/?request=slider
• 响应
  响应与上一接口“查询媒体资源”相同，没有分页信息，最多返回8个资源。

4.查询播放地址

4.1.查询播放地址

• 用途
  查询某个媒体资源的播放地址。
  请求
  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 播出协议

5.登录验证

概述

• 1）登录的要求和意义
  客户端应当首选判断服务器是否要求必须登录。如果要求，则应首先调用登录接口登录，然后再请求其他接口。
  是否需要强制登录，跟运营需求有关，网站运营者可以通过管理平台设置这个选项。
  如果没有强制要求，客户端可以登录，也可以不登陆。
  用户正确登录后，会获得一个token值，在后续的接口中，应当将该token值带入。例如：
  http://ip/mserver/cms/interface2/media/?parent=2&token=abcdefg

• 2）登录的流程
  服务器和客户端通过“挑战->应答”方式（challenge-response）进行身份认证交互，在这个过程中，客户端需要调用两次接口向服务器证明身份。认证过程中不需要传递密码，密码用于签名验证。
  身份认证的过如下：
  1）客户端使用“用户名”作为参数调用“login1”接口，向服务器发出身份认证请求
  1.1）服务器确认用户是否是有效的用户：
  1.2）若不是，则不做进一步处理，返回错误信息
  1.3）若是，服务器产生一个“随机数（挑战字符串）”发送给客户端
  2）客户端使用“用户密码”和“随机数（挑战字符串）”作为输入，按约定的算法生成一个hash值，用该hash值作为 调用“login2”接口的参数，请求login2接口。
  2.1）服务器用收到的hash值与自己的计算结果比较，若二者相同，则通过认证；否则，认证失败
  2.2）若认证通过，服务器返回“token”给客户端，否者返回错误信息。

5.1.判断是否必须登录

• 用途
  判断是否要求必须登录。
  如果要求必须登录，则需要先登录，否者查询数据的接口会返回没有权限的错误。

请求
http://ip/mserver/cms/interface2/user/?request=needslogin

• 响应

{
    "code": 0,
    "err_desc": "no"
}

err_desc 属性描述了对登录的要求。no 表示不强制要求， yes 表示必须要求登录。

5.2.login1

• 用途
  提交认证申请，接口返回挑战字符串。
  请求
  http://ip/mserver/cms/interface2/user/?request=login1&username=mrwang
  username 登录用户名。

• 响应

{
    "code": 0,
    "data": {
        "count": 1,
        "items": [
            {
                "id": 37,
                "chcode": "9luqgrnj5vvszmjw"
            }
        ]
    }
}

id session识别号，用于login2接口，原样传递给login2即可。
chcode 挑战字符串，客户端按约定规则使用该字符串生成一个hash值，然后调用login2接口。

5.3.login2

• 用途
  使用login1返回的chcode计算出一个hash值，提交给本接口申请到一个token。该token值用于其他接口的认证。
  请求
  http://ip/mserver/cms/interface2/user/?request=login2&id=34&hash=7ecc1447c24c1722c3d9bce09fe6cf18
  id login1接口返回的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 用户所属的用户组

5.4.logout

• 用途
  退出登录，退出应用前请尽量调用该接口。
  请求
  http://ip/mserver/cms/interface2/user/?request=logout&token =abcdefg
  token 登录接口中获得的token

• 响应

{
    "code": 0,
}