G3CMS 數(shù)據(jù)查詢接口協(xié)議

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

1.概述

1.1.用途

向集成客戶端提供查詢數(shù)據(jù)和登錄服務(wù)。
如果資源需要授權(quán)才能查看和使用，請(qǐng)首先閱讀“5.登錄驗(yàn)證”小節(jié)。

1.2.通信協(xié)議

客戶端和服務(wù)器通過(guò)HTTP協(xié)議通信，客戶端使用HTTP Get向服務(wù)器發(fā)送請(qǐng)求，服務(wù)器返回json格式的業(yè)務(wù)數(shù)據(jù)或操作結(jié)果給客戶端。

1.3.接口請(qǐng)求

接口地址是一個(gè)HTTP協(xié)議的url地址，具體格式是：
http://ip/mserver/cms/interface2/catalog/?parent=1&token=abcdefg
ip替換成實(shí)際服務(wù)器的ip或域名，如果端口不是默認(rèn)端口，需要把端口加上。
token是認(rèn)證字符串，在登錄接口中獲取，如果沒有登錄則省略。
其他內(nèi)容參見接口的定義。
當(dāng)URL請(qǐng)求參數(shù)值中包含URL地址保留字符時(shí)，應(yīng)對(duì)參數(shù)值進(jìn)行URL編碼。
具體參見“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
當(dāng)請(qǐng)求參數(shù)包含中文字符時(shí)，應(yīng)對(duì)中文字符采用UTF-8編碼。

1.4.返回消息結(jié)構(gòu)

返回的json消息數(shù)據(jù)結(jié)構(gòu)具有嚴(yán)格的一致性，客戶端可以采用一致的接收和解析方式處理返回消息。
簡(jiǎn)單消息
簡(jiǎn)單的返回消息包含對(duì)請(qǐng)求的處理結(jié)果，結(jié)構(gòu)如下：

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

其中：
code 為0表示處理成功，其它值表示處理失敗。
err_desc是對(duì)錯(cuò)誤的描述，在code為0時(shí)err_desc會(huì)被省略。
特殊情況，在用戶認(rèn)證的login1和login2接口中，err_desc具有特殊用途用法，具體參見接口描述。除這兩個(gè)接口之外，err_desc都表示錯(cuò)誤描述。
帶業(yè)務(wù)數(shù)據(jù)的消息
有的返回消息除了包含處理結(jié)果信息，還包含業(yè)務(wù)數(shù)據(jù)記錄集，結(jié)構(gòu)如下：

 {
        "code":0,
        "data":{
            "count":1,
            "items":[...]
        }
    }

其中：
data 業(yè)務(wù)數(shù)據(jù)的根節(jié)點(diǎn)：
count 業(yè)務(wù)數(shù)據(jù)的條數(shù)，可能的值為0 ~ n
items 業(yè)務(wù)數(shù)據(jù)，是一個(gè)數(shù)組，數(shù)據(jù)條數(shù)由count屬性定義。當(dāng)count為0時(shí)，items屬性可能為null或者不存在。
本文檔后續(xù)章節(jié)中，在描述items元素的屬性時(shí)，會(huì)省略一些屬性的描述，即實(shí)際調(diào)用接口返回的屬性在本文檔中可能會(huì)沒有描述，這種情況下請(qǐng)直接忽略被忽略描述的屬性值。本文檔中描述的屬性是實(shí)際返回內(nèi)容的一個(gè)子集，沒有描述到的內(nèi)容對(duì)集成本系統(tǒng)沒有影響。
帶分頁(yè)數(shù)據(jù)的消息
如果返回?cái)?shù)據(jù)較多，服務(wù)器會(huì)對(duì)返回的數(shù)據(jù)進(jìn)行分頁(yè)，客戶端可以按照頁(yè)碼請(qǐng)求指定范圍的數(shù)據(jù)。帶分頁(yè)信息的返回?cái)?shù)據(jù)結(jié)構(gòu)如下：

    {
    "code":0,
    "data":{
        "page":1,
        "page_size":"20",
        "pages":"1",
        "total":"2",
        "count":2,
        "items":[...]
                }
}

分頁(yè)數(shù)據(jù)信息在data元素下，意義如下：
page 當(dāng)前頁(yè)碼
page_size 每頁(yè)數(shù)據(jù)記錄條數(shù)
pages 總共的頁(yè)數(shù)
total 總數(shù)據(jù)條數(shù)
count 當(dāng)前返回頁(yè)的數(shù)據(jù)條數(shù)
如果返回的數(shù)據(jù)帶有分頁(yè)信息，則可以在調(diào)用接口時(shí)使用page參數(shù)來(lái)請(qǐng)求指定頁(yè)碼的數(shù)據(jù)。

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上的分類信息。
  請(qǐng)求
  http://ip/mserver/cms/interface2/catalog/?parent=1
  parent 上級(jí)分類編號(hào)。如果忽略，會(huì)返回一級(jí)分類列表。
  如果要查詢一級(jí)分類，請(qǐng)去掉parent參數(shù)。

• 響應(yīng)

{
    "code": 0,
    "data": {
        "count": 2,
        "items": [
            {
                "id": 1,
                "name": "公共欄目",
                "comment": "",
                "upper_catalog_id": 0
            },
            {
                "id": 2,
                "name": "私有欄目",
                "comment": "",
                "upper_catalog_id": 0
            }
        ]
    }
}

id 編號(hào)
name 名稱
comment 備注
"upper_catalog_id 上級(jí)分類編號(hào)， 0 表示當(dāng)前分類是一級(jí)分類。

2.2.查詢分類樹

• 用途
  查詢所有分類及其下級(jí)分類。
  請(qǐng)求
  http://ip/mserver/cms/interface2/catalog/?request=all

• 響應(yīng)

{
    "code": 0,
    "data": {
        "count": 2,
        "items": [
            {
                "id": 1,
                "name": "公共欄目",
                "comment": "",
                "upper_catalog_id": 0,
                "sub_items": [
                                {
                                    "id": 5,
                                    "name": "二級(jí)分類1",
                                    "comment": "",
                                    "upper_catalog_id": 1
                                },
                                ...
                    ]
            },
            ...
        ]
    }
}

id 編號(hào)
name 名稱
comment 備注
"upper_catalog_id 上級(jí)分類編號(hào)， 0 表示當(dāng)前分類是一級(jí)分類。
sub_items 下級(jí)分類數(shù)組，包含 0 或多個(gè)下級(jí)分類。

3.查詢媒體資源

3.1.查詢媒體資源

• 用途
  查詢媒體資源。
  可以查詢某個(gè)編號(hào)的資源的信息，也可以查詢某個(gè)分類下的所有資源信息。
  請(qǐng)求
  http://ip/mserver/cms/interface2/media/?parent=2
  parent 分類編號(hào)，如果要查詢某個(gè)分類下的所有資源，請(qǐng)忽略下一個(gè)參數(shù)。
  media_id 資源編號(hào)，如果給出該參數(shù)，則只查詢編號(hào)為media_id的一個(gè)資源的信息，并忽略parent參數(shù)。

• 響應(yīng)

{
    "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個(gè)或多個(gè)資源信息。
id 資源編號(hào)
catalog_id 所屬分類編號(hào)
title 標(biāo)題
sub_title 小標(biāo)題
abstract 摘要描述
text 描述
resource_type vod或live
cover 封面地址
duration 播放時(shí)長(zhǎng)
add_time 添加時(shí)間
view_times 觀看次數(shù)
open_status 開放狀態(tài)

3.2.查詢輪播資源

• 用途
  查詢輪播列表的資源，用于CMS站點(diǎn)中展示輪播內(nèi)容。接口默認(rèn)返回第一個(gè)輪播列表的資源。
  請(qǐng)求
  http://ip/mserver/cms/interface2/media/?request=slider
• 響應(yīng)
  響應(yīng)與上一接口“查詢媒體資源”相同，沒有分頁(yè)信息，最多返回8個(gè)資源。

4.查詢播放地址

4.1.查詢播放地址

• 用途
  查詢某個(gè)媒體資源的播放地址。
  請(qǐng)求
  http://ip/mserver/cms/interface2/url/?media_id=39&protocol=http-mp4
  media_id 資源編號(hào)。
  protocol 播出協(xié)議，點(diǎn)播資源可以是hls，http-flv或http-mp4；直播資源可以是 rtmp或hls。如果省略，返回所有協(xié)議的地址。
  客戶端請(qǐng)根據(jù)終端類型選用合適的播出協(xié)議：
  android、ios或其他支持H5的瀏覽器，可以選用：hls, http-mp4協(xié)議
  PC選用http-flv或rtmp協(xié)議

• 響應(yīng)

{
    "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個(gè)或多個(gè)播放地址，一個(gè)資源可能有多個(gè)不同協(xié)議的播放地址。
resource_id 資源編號(hào)
web_url 播出地址
"web_io_protocol 播出協(xié)議

5.登錄驗(yàn)證

概述

• 1）登錄的要求和意義
  客戶端應(yīng)當(dāng)首選判斷服務(wù)器是否要求必須登錄。如果要求，則應(yīng)首先調(diào)用登錄接口登錄，然后再請(qǐng)求其他接口。
  是否需要強(qiáng)制登錄，跟運(yùn)營(yíng)需求有關(guān)，網(wǎng)站運(yùn)營(yíng)者可以通過(guò)管理平臺(tái)設(shè)置這個(gè)選項(xiàng)。
  如果沒有強(qiáng)制要求，客戶端可以登錄，也可以不登陸。
  用戶正確登錄后，會(huì)獲得一個(gè)token值，在后續(xù)的接口中，應(yīng)當(dāng)將該token值帶入。例如：
  http://ip/mserver/cms/interface2/media/?parent=2&token=abcdefg

• 2）登錄的流程
  服務(wù)器和客戶端通過(guò)“挑戰(zhàn)->應(yīng)答”方式（challenge-response）進(jìn)行身份認(rèn)證交互，在這個(gè)過(guò)程中，客戶端需要調(diào)用兩次接口向服務(wù)器證明身份。認(rèn)證過(guò)程中不需要傳遞密碼，密碼用于簽名驗(yàn)證。
  身份認(rèn)證的過(guò)如下：
  1）客戶端使用“用戶名”作為參數(shù)調(diào)用“l(fā)ogin1”接口，向服務(wù)器發(fā)出身份認(rèn)證請(qǐng)求
  1.1）服務(wù)器確認(rèn)用戶是否是有效的用戶：
  1.2）若不是，則不做進(jìn)一步處理，返回錯(cuò)誤信息
  1.3）若是，服務(wù)器產(chǎn)生一個(gè)“隨機(jī)數(shù)（挑戰(zhàn)字符串）”發(fā)送給客戶端
  2）客戶端使用“用戶密碼”和“隨機(jī)數(shù)（挑戰(zhàn)字符串）”作為輸入，按約定的算法生成一個(gè)hash值，用該hash值作為 調(diào)用“l(fā)ogin2”接口的參數(shù)，請(qǐng)求login2接口。
  2.1）服務(wù)器用收到的hash值與自己的計(jì)算結(jié)果比較，若二者相同，則通過(guò)認(rèn)證；否則，認(rèn)證失敗
  2.2）若認(rèn)證通過(guò)，服務(wù)器返回“token”給客戶端，否者返回錯(cuò)誤信息。

5.1.判斷是否必須登錄

• 用途
  判斷是否要求必須登錄。
  如果要求必須登錄，則需要先登錄，否者查詢數(shù)據(jù)的接口會(huì)返回沒有權(quán)限的錯(cuò)誤。

請(qǐng)求
http://ip/mserver/cms/interface2/user/?request=needslogin

• 響應(yīng)

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

err_desc 屬性描述了對(duì)登錄的要求。no 表示不強(qiáng)制要求， yes 表示必須要求登錄。

5.2.login1

• 用途
  提交認(rèn)證申請(qǐng)，接口返回挑戰(zhàn)字符串。
  請(qǐng)求
  http://ip/mserver/cms/interface2/user/?request=login1&username=mrwang
  username 登錄用戶名。

• 響應(yīng)

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

id session識(shí)別號(hào)，用于login2接口，原樣傳遞給login2即可。
chcode 挑戰(zhàn)字符串，客戶端按約定規(guī)則使用該字符串生成一個(gè)hash值，然后調(diào)用login2接口。

5.3.login2

• 用途
  使用login1返回的chcode計(jì)算出一個(gè)hash值，提交給本接口申請(qǐng)到一個(gè)token。該token值用于其他接口的認(rèn)證。
  請(qǐng)求
  http://ip/mserver/cms/interface2/user/?request=login2&id=34&hash=7ecc1447c24c1722c3d9bce09fe6cf18
  id login1接口返回的id值，原樣帶入。
  hash 根據(jù)約定計(jì)算出的hash值。算法：
  hash=md5(md5(password)+chcode)
  描述：首先計(jì)算出密碼的hash值，然后在生成的密碼hash值尾部拼接上挑戰(zhàn)字符串形成新的字符串，最后計(jì)算這個(gè)新字符串的hash值。
  hash算法采用md5算法，生成的摘要采用16進(jìn)制編碼，編碼生成的字符采用小寫字母。
  例如，字符串111111的hash值是 96e79218965eb72c92a549dd5a330112

• 響應(yīng)

{
    "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 認(rèn)證令牌，在無(wú)法保持session的情況下，在請(qǐng)求其他接口中應(yīng)當(dāng)將token參數(shù)帶入
group_id 用戶所屬的用戶組

5.4.logout

• 用途
  退出登錄，退出應(yīng)用前請(qǐng)盡量調(diào)用該接口。
  請(qǐng)求
  http://ip/mserver/cms/interface2/user/?request=logout&token =abcdefg
  token 登錄接口中獲得的token

• 響應(yīng)

{
    "code": 0,
}