调用方式（必读）

所有接口(以下简称API)以HTTP/REST方式接入，使用URI 唯一标识，各类接口的URI参照API概览

请求结构

对视图库API调用是通过向视图库服务端地址发送请求，并按照接口说明在请求中加入相应的请求参数来完成的。视图库接口的请求结构由以下几个部分组成：

1.服务地址

HTTP URL格式的形式为：

<Protocol>://<Hostname>:<Port><URI>(?P1=v1&p2=v2…&pn=vn)。

其中：Protocol为HTTP；Hostname指视图库服务设备的主机名称、IP地址或域名；Port指端口号；URI指资源URI；(?P1=v1&p2=v2…&pn=vn)指查询字符串，每个资源都会定义需要的或可选的查询字符串参数，查询字符串参数以名字/值对形式出现。

2.请求方法

视图库API的HTTP请求方法包括GET、PUT、POST、DELETE。

方法的选取参照对应接口说明。

注意：

1、如果接口的请求方法是POST， PUT则需要对请求内容进行指定编码处理，且内容均从消息体中取得。

2、如果接口的请求方法是GET，则对所有请求参数值均需要做URL编码。

3.请求参数

视图库API每个请求都需要指定请求头参数，参数列表如下

表1 请求参数列表

序号	参数名称	参数说明	必填	备注
1	Content-Type	消息体对象的媒体类型	是/否	带有消息体的POST,PUT请求必填，支持 application/json或xml;charset=utf-8
2	Accept	请求方能接收的媒体类型	否	支持application/json或xml;charset=utf-8，默认 返回application/json;charset=utf-8
3	User-Identify	请求方系统编码	是/否	用于校验访问者身份，参考注册、保活、注销
备注：参数命名和取值，大小写敏感

返回结果

REST HTTP请求响应保留HTTP协议相关内容，其中返回结果（响应消息体）由视图库API维护。

视图库API的返回结果由请求方法决定，总结如下表：

表2 各类请求返回结果

序号	请求方法	说明	返回结果
1	GET	查询单个目标对象属性	单个目标结果
2	GET	查询符合条件的多个对象	多个目标集合
3	GET	查询异常	ResponseStatus
4	POST	提交单个目标对象	ResponseStatus
5	POST	提交多个目标对象集合	List<ResponseStatus>
6	PUT	修改单个目标对象	ResponseStatus
7	PUT	修改多个目标对象集合	List<ResponseStatus>
8	DELETE	修改单个目标对象	ResponseStatus
9	DELETE	修改多个目标对象集合	List<ResponseStatus>

ResponseStatus（应答状态对象）特征属性参照A.26 应答状态对象

其他的对象特征参见 附录A

字符编码

视图库API的请求及返回结果均使用UTF-8字符集进行编码。

通用说明

1、所有时间格式字段，若无特殊说明，均采用如下时间格式：yyyyMMddHHmmss如 20170101021020

2、所有URI中的 <ID> 在请求时需替换为具体对象的标识ID。例如：

HTTP PUT请求访问取消订阅接口 /VIID/Subscribes/<ID> 时，需要把URI中的<ID>替换成目标对象的订阅标识，如 /VIID/Subscribes/330101020001032017113010580006371

3、下文接口示例中的消息体和响应体都是基于如下请求头参数

请求头名称	取值
Content-Type	application/json;charset=utf-8
Accept	application/json;charset=utf-8