接口规范 概述

Posted 2020-10-21

1.概述

• 1.1.用途
  远程管理API提供一组接口，其他系统（如企业的业务管理系统、媒资管理系统、用户管理系统等）可以通过调用接口来查询流媒体服务器的数据和更改流媒体服务器的配置，实现与流媒体服务器的集成。

• 1.2.适用版本
  本文档定义的接口规范，对版本号大于等于3.6.500的流媒体服务器系统有效。较低版本服务器，继续使用对应版本的接口规范。

• 1.3.通信协议
  本规范中，流媒体服务器是通信的服务器端（简称“服务器”），调用接口的其他系统是通信客户端（简称“客户端”）。客户端和服务器通过HTTP协议通信，客户端使用HTTP Get向服务器发送请求，服务器返回json格式的业务数据或操作结果给客户端。

• 1.4.接口请求
  接口的请求地址是个URL地址，每个接口URL地址都包括分组位置和请求参数，例如：
  http://ip/mserver/interface/appMgr/?request=get&token=123456
  其中：
  http://ip/mserver/interface/appMgr/ 是接口请求的URL位置，“ip”在实际请求中要替换成服务器的ip地址或域名。
  http://ip/mserver/interface/ 代表流媒体服务器接口服务在Web上的部署的位置，要保持不变。
  appMgr是接口的分组位置，流媒体服务器接口包括了多个分组位置，具体参见接口定义部分。
  符号?后面是参数列表，以name=value的形式体现。其中request参数是在所有接口中都要有的，该参数表明了请求业务的类型。还有一个token参数，提供一个安全认证符号给服务器，服务器用token来验证客户端的合法性，除了登录验证接口之外，其他接口都需要token参数。
  有关URL地址的编码规范，请参考HTTP 1.1规范。

• 1.5.接口响应
  服务器在收到接口请求后，首先判断token的正确性，如果token错误，则返回认证错误的消息给客户端。如果token正确，服务器返回json格式的文本内容给客户端。返回给客户端的json文本描述了服务器对请求的处理结果和响应数据。

• 1.6.接口安全
  客户端必须首先通过身份认证才能继续调用接口，在一个“挑战—>应答”模式的身份认证过程中完成身份认证，认证通过后，服务器为客户端分配一个临时令牌token，在后续的请求中，token作为一项必选参数提供，服务器通过token识别用户身份和验证请求的合法性。
  在没有接口调用时，token的有效期为30分钟，之后客户端再调用接口时必须重新进行身份认证，获取新的token。
  为了确保一定的安全性，客户端应妥善保存token值。

• 1.7.URL编码
  当URL请求参数值中包含URL地址保留字符时，应对参数值进行URL编码。
  具体参见“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。
  当请求参数包含中文字符时，应对中文字符采用UTF-8编码。

• 1.8.描述约定
  本文档在描述分组位置时，会省略掉所有接口URL前面的相同部分，从接口的分组位置开始描述。例如，http://ip/mserver/interface/appMgr/?request=get 简化为 appMgr/?request=get。
  在描述参数时，省略token参数的描述，在示例中也会省略。在实际调用中必须把token参数加上。
  在对参数进行描述时，用【必选】表示该参数必须提供，用【可选】表示该参数可以省略，用【URL编码】表示该参数需要进行URL编码，【保留】表示该参数可以接受但尚未被使用。

• 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",
          "host":"127.0.0.1",
          "protocol":"rtmp",
          "app":"liveshow",
          "stream":"jgdy"
          }]
      }            
  }

  其中：
  data 业务数据的根节点：
  count 业务数据的条数，可能的值为0 ~ n
  items 业务数据，是一个数组，数据条数由count属性定义。当count为0时，items属性可能为null或者不存在。

• 1.10.参考
  [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