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,
}