跳到主要内容

API概述

概述

科达视讯平台API,主要为希望对视频会议进行二次开发的开发者提供一套完整的接口。

整体风格

URI风格

URI采用RESTful 的设计风格:

http://{domain|ip}/api/{version}/{app}/{resources}/{rc_id}

其中当前版本versionv1

app分类为:

模块app
统一登陆system
会议管理mc
会议控制vc
账号管理amc
录播系统vrs
统一出席upu

时间格式

采用ISO8601:2000标准

2016-11-11T15:30:00+08:00

请求方法

  • GET(SELECT):从服务器取出资源(一项或多项)
  • POST(CREATE):在服务器新建一个资源
  • PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
  • DELETE(DELETE):从服务器删除资源

使用说明

APP鉴权

科达视讯平台API采用统一登陆方式对软件权限及用户账户进行验证,使用者仅需登陆一次,便可调用各子系统的API。 使用者需先申请API License,并导入到科达视频会议系统中。 通过AppKeyAppSecret向平台注册获取account_token

请求格式:

POST /api/v1/system/token HTTP/1.1
Accept-Encoding: identity
Content-Length: 58
Host: 127.0.0.1
User-Agent: Python-urllib/3.5
Content-Type: application/x-www-form-urlencoded
Connection: close
API-Level: 1

oauth_consumer_key=key&oauth_consumer_secret=12345678

回复格式:

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Jun 2016 07:39:49 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 67
Connection: close

{"success": 1, "account_token": "6567e24b425db665a3044db69f0c6fe4"}

用户登陆

使用用户的帐号、密码登录和上一步获取的account_token进行登陆

请求格式:

POST /api/v1/system/login HTTP/1.1
Accept-Encoding: identity
Content-Length: 85
Host: 172.16.185.146
User-Agent: Python-urllib/3.5
Content-Type: application/x-www-form-urlencoded
Connection: close
API-Level: 1

password=888888&username=name&account_token=6567e24b425db665a3044db69f0c6fe4

回复格式:

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Jun 2016 07:39:49 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 43
Connection: close
Set-Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793;
Expires=Mon, 11-Jul-2016 07:39:49 GMT;

{"success": 1, "username": "0512110001003"}

平台使用Cookie来保存用户的登录信息。 调用后续接口时,需要在每次请求的时候携带account_token及用户Cookie。 每次请求会刷新account_tokencookie的有效期,若长时间无操作,开发者需要自行调用接口刷新tokenCookie的有效期。

获取类请求

参数平铺跟在URI后面,以&区分多参数 范例(获取会议列表为例)

GET /api/v1/vc/confs?account_token=6567e24b425db665a3044db69f0c6fe4 HTTP/1.1
Accept-Encoding: identity
User-Agent: Python-urllib/3.5
Host: 127.0.0.1
Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793
Connection: close

修改类请求(POST/PUT)

参数以表单形式x-www-form-urlencoded提交,字符编码为utf-8

Content-Type: application/x-www-form-urlencoded;charset=utf-8;

json类参数,以params作为key,json内容urlencoder后作为value进行传递。 范例 (添加终端为例)

POST /api/v1/vc/confs/1118986/mts HTTP/1.1
Accept-Encoding: identity
User-Agent: Python-urllib/3.5
Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793
Content-Length: 305
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded
Connection: close
API-Level: 1

params=%7B%22mts%22%3A+%5B%7B%22account_type%22%3A+5%2C+%22account
%22%3A+%222322231%22%2C+%22bitrate%22%3A+2048%2C+%22protocol%22%3A
+0%7D%2C+%7B%22account_type%22%3A+5%2C+%22account%22%3A+%222322232
%22%2C+%22bitrate%22%3A+2048%2C+%22protocol%22%3A+0%7D%5D%7D&
account_token=6567e24b425db665a3044db69f0c6fe4

回复格式

数据形式为json,字符编码utf-8

Content-Type: application/json;charset=utf-8;

任何操作都有success标识请求成功失败 失败是会有error_code字段标识错误码

范例(添加终端回复为例)

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Jun 2016 07:52:28 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 31
Connection: close

{"success": 1, "error_code": 0}

兼容性策略

由于我司会议平台主要应用场景为私有云部署,不同的客户或同一客户的不同地区可能使用不同的版本,且较难升级为同一版本。

因此调用方可能需要考虑兼容不同版本的平台,包括向前兼容和向后兼容。

为了方便区分平台的版本,采用API-Level字段来描述API版本。

版本说明

API说明文档中每个App模块的API-Level与文档对应的平台版本号,可以在右上角查询到:

API-Level:1;
V6.0.0.3.0.20190826;

每个API接口,也会标注其所需的最低API-Level,若环境的API-Level低于接口描述终端最低需求版本,则该环境不支持该API接口。

如下例代表该接口最低支持的API-Level为3,若平台的API-Level版本为2,则说明平台不支持该接口。

名称          获取个人模板列表
URI /api/v1/mc/personal_templates
方法 GET
说明 获取个人模板列表
最低支持版本 3
...

查询API-Level

为了便于调用方查询当前环境的API版本,每个模块都提供了API-Level查询接口:

格式为:

GET /api/{app}/version;

如:

GET /api/system/version;
GET /api/vc/version;
GET /api/mc/version;
...

向后兼容

由于平台功能的演进,API接口及参数可能会不断变化,一般情况下,我们会尽量避免做出影响兼容性的改动,但极少数情况下,API接口还是可能存在不兼容的问题,包括但不限于:

  1. API参数字段变化
  2. API路径变化
  3. API参数值含义变化
  4. 返回数据中字段的增删

私有云环境下,有可能存在视频会议平台升级了版本,但第三方基于API开发的业务没有计划升级的情况。

为了能最大限度保证这种情况下的兼容性,减少二次开发的工作量,建议调用方在调用API时,告知平台其所用的API-Level

当调用方携带的API-Level小于平台的API-Level时,平台会进行兼容性处理,按照给定的API-Level版本的格式解析参数、返回数据。

当调用方携带的API-Level大于平台版本时,平台则会按其所支持的最高API-Level版本的格式解析参数、返回数据

API-Level需要携带在HTTP头中,如下例:

GET /api/v1/mc/personal_templates?account_token=6567e24b425db665a3044db69f0c6fe4 HTTP/1.1
Accept-Encoding: identity
User-Agent: Python-urllib/3.5
Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793
Content-Length: 305
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded
Connection: close
API-Level: 1

调试模式

由于部分接口参数众多,当调用方调用出错时,可以使用调试模式来校验填写的参数是否合法。

使用方法为在请求的URI中携带参数debug=1,如:

POST /api/v1/vc/confs/1118986/mts?debug=1 HTTP/1.1
Accept-Encoding: identity
User-Agent: Python-urllib/3.5
Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793
Content-Length: 305
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded
Connection: close

params=%7b%22mts%22%3a+%5b%7b%22account_type%22%3a+5%2c+%22account
%22%3a+%222322231%22%2c+%22bitrate%22%3a+2048%2c+%22protocol%22%3a
0%7d%2c+%7b%22account_type%22%3a+5%2c+%22account%22%3a+%222322232%
22%2c++%22protocol%22%3a+0%7d%5d%7d&account_token=6567e24b425db665
a3044db69f0c6fe4

开启调试模式后,平台仅会对接口进行参数校验,并返回校验结果,并不会实际执行。

平台会在返回数据的debug_list字段中给出错误提示,数据格式如下:

"debuglist":{
"第一层key":{
"第二层key":"错误说明"
},
"第一层key":[
{"第二层key":"错误说明"}
]
}

下述返回表示参数mts列表中缺少必填参数bitrate

{
"success":1,
"dubug_list":{
"mts":[
{"bitrate":"下参中缺少该必填参数"}
]
}
}