1.概述

Posted 2020-11-19

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

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

其中：
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.10.通用属性

返回的业务数据，大部分包含如下三个属性：
add_time 数据添加的时间，格式“ yyyy-mm-dd hh:mm:ss”
update_time 最后更新的时间
status 状态，1正常 2禁用 -1删除。

这三个属性，除非有特殊意义，在后面的描述中不再进一步说明。