G3CMS 数据查询接口协议(3c,api,cms,开发技术)

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会被省略。
特殊情况，在用户认证的login1和login2接口中，err_desc具有特殊用途用法，具体参见接口描述。除这两个接口之外，err_desc都表示错误描述。
带业务数据的消息
有的返回消息除了包含处理结果信息，还包含业务数据记录集，结构如下：

其中：
data 业务数据的根节点：
count 业务数据的条数，可能的值为0 ~ n
items 业务数据，是一个数组，数据条数由count属性定义。当count为0时，items属性可能为null或者不存在。
本文档后续章节中，在描述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

id 编号
name 名称
comment 备注
"upper_catalog_id 上级分类编号， 0 表示当前分类是一级分类。

id 编号
name 名称
comment 备注
"upper_catalog_id 上级分类编号， 0 表示当前分类是一级分类。
sub_items 下级分类数组，包含 0 或多个下级分类。

返回0个或多个资源信息。
id 资源编号
catalog_id 所属分类编号
title 标题
sub_title 小标题
abstract 摘要描述
text 描述
resource_type vod或live
cover 封面地址
duration 播放时长
add_time 添加时间
view_times 观看次数
open_status 开放状态

返回0个或多个播放地址，一个资源可能有多个不同协议的播放地址。
resource_id 资源编号
web_url 播出地址
"web_io_protocol 播出协议

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

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

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

name 用户名
sex 性别，1男 0女
logo 用户头像，null或者头像url
token 认证令牌，在无法保持session的情况下，在请求其他接口中应当将token参数带入
group_id 用户所属的用户组