1.概述
1.1.用途
略
1.2.適用版本
略
1.3.通信協議
本規範中,流媒體服務器是通信的服務器端(簡稱“服務器”),調用接口的其他系統是通信客戶端(簡稱“客戶端”)。客戶端和服務器通過HTTP協議通信,客戶端使用HTTP Get 或 HTTP Post向服務器發送請求,服務器返回json格式的業務數據或操作結果給客戶端。用GET還是POST方式發送請求,要根據具體情況,例如簡單的情況可以GET,大量數據的提交可以POST。
1.4.接口請求
1.5.接口響應
服務器返回json格式的文本內容給客戶端。
返回給客戶端的json文本描述了服務器對請求的處理結果和響應數據。
1.6.接口安全
1.7.URL編碼
當URL請求參數值中包含URL地址保留字符時,應對參數值進行URL編碼。
具體參見“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
當請求參數包含中文字符時,應對中文字符采用UTF-8編碼。
1.8.描述約定
1.9.返回消息結構
返回的json消息數據結構具有嚴格的一致性,客戶端可以采用一致的接收和解析方式處理返回消息。
簡單消息
簡單的返回消息包含對請求的處理結果,結構如下:
{
"code":0,
"err_desc":""
}
其中:
code 為0表示處理成功,其它值表示處理失敗。
err_desc是對錯誤的描述,在code為0時err_desc會被省略。
帶業務數據的消息
有的返回消息除了包含處理結果信息,還包含業務數據記錄集,結構如下:
{
"code":0,
"data":{
"count":1,
"items":[{
"server":"g3",
}]
}
}
其中:
data 業務數據的根節點:
count 業務數據的條數,可能的值為0 ~ n
本文檔後續章節中,在描述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.10.通用屬性
返回的業務數據,大部分包含如下三個屬性:
add_time 數據添加的時間,格式“ yyyy-mm-dd hh:mm:ss”
update_time 最後更新的時間
status 狀態,1正常 2禁用 -1刪除。
這三個屬性,除非有特殊意義,在後面的描述中不再進一步說明。
1.概述