“警备通”警用装备管理系统接口集成文档

产品资讯 | 2020-08-27

1.接口说明

本技术方案针对“警备通”与其它外部系统业务协作接口的技术实现进行设计。

1.1接口方式

外部系统与“警备通”之间的接口采用Http Web API接口形式来进行业务数据的交互。接口数据传输采用JSON数据交换格式，数据采用utf-8编码。

考虑到“警备通”的可集成性，要求“警备通”对各个外部系统所提供的接口API及其参数信息、格式均是统一的。“警备通”与外部系统属于一对多的关系。

1.2接口安全

虽然接口双方都是存在于内部网络中，但是，仍不能排除接口服务被攻击、恶意调用以及非法调用等。所以，从接口调用上，必须考虑调用的认证安全问题。

本方案中，在客户端调用服务端的时候，必须经过调用身份认证。本方案采用客户端安全身份认证的方式，即在访问接口所在的服务的时候，都必须进行身份校验（基于Token的令牌验证）。

基于Token的令牌验证方式具有服务端无状态化、可扩展性好、安全、支持跨程序调用等特点，这种方式要求客户端先向服务端请求访问令牌（使用用户名和密码），客户端每次向服务端请求资源时均须携带服务端签发的 Token，服务端收到请求，验证客户端Token的合法性，如果验证成功，就向客户端返回请求的数据。

基于 token 的用户认证是一种服务端无状态的认证方式，服务端不用存放 token 数据。用解析 token 的计算时间换取 session 的存储空间，从而减轻服务器的压力，减少频繁的查询数据库。

1.3数据格式、约定

客户端和服务端互相之间通讯的请求报文和结果报文遵循JSON格式。客户端发送请求报文，服务器解析调用报文，执行报文中所在接口对应的服务功能。生成结果报文，以JSON格式返回给请求者。请求者拿到结果报文，进行解析，然后再进行相应的处理。

为便于调用双方对数据报文进行统一的解析处理，需对报文的数据格式和规则进行如下约定：

l 报文中所有的字典信息（比如性别1-男，2-女），都以代码的值（1或者2）来传递；

l 报文中的其他数据类型，比如货币、日期、时间、文件对象等，根据需要转换成文本、数值或二进制（最终转换成Base64字符）的数据类型；

l 报文中的日期信息，转换成YYYYMMDD HHmmss文本格式（24小时制）。如果是空日期，则转换成空文本；

l 报文中的true和false数据类型，转换成 0(表示false)、1（表示true）；

l 报文中的二进制数据（如文件对象），转换成Base64字符方式发送；

l 如果返回结果数据集非常多，在性能考虑和数据量冲突的情况下，可以使用分页返回数据集的方式分批返回数据（每次返回最多100条记录）。服务端提供分批结果返回的功能。

1.4容错处理

客户端向服务端发送数据，服务端解析数据，反馈信息给客户端，这中间的环节只要某一个环节出现问题，都会造成接口的失败。按照失败产生的环节分类，我们可以从三个方面来处理接口的失败。

l 网络连接失败：在调用接口的时候，由于网络不通，造成数据不能正常传输。这样，客户端应该能够记录发送的日志，按照一定的时间间隔重试发送。本方案定为重试发送20次，每次时间间隔2小时。如果一直发生网络不通的情况，该发送日志被保存下来，待后手工发送。所以，客户端系统应该实现手工发送数据的功能。

l 反馈错误信息：服务端在解析数据包，执行数据包业务的时候，可能会发生异常。所以，服务端应当能够捕捉异常信息，比如“非法XML格式”等，然后反馈给客户端。客户端在接受到这类的错误信息之后，应当进行日志记录，能够自动或手工分析异常的信息。

l 网络连接正常，但是无信息反馈：这种情况下，一般是服务端出现了异常，但是又没有捕捉到的情况下发生。这种情况下，客户端把这种错误当作“网络连接失败”来处理。服务端应能够实现相同数据包重新发送过来的处理机制。

1.5通用错误返回码

返回码	表示	说明
200	请求正常
401	Token鉴权失败	获取Token令牌时，验证用户名密码失败
403	Token验证失败	执行接口请求时，Token不存在或失效
405	参数校验失败	执行接口请求时，出现参数缺失、格式错误

2.接口定义

2.1Access Token鉴权接口

2.1.1接口定义

Token是服务端的全局唯一接口调用凭据，客户端调用服务端各接口时都需使用，Token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的Token失效。

URL	http://*****/webapi/token?username={username}&password={password}
协议	http
请求方式	GET/POST

2.1.1.1参数说明

参数名称	是否必须	类型	描述
username	必选	String	第三方用户唯一凭证
password	必选	String	第三方用户唯一凭证密钥

2.1.1.2返回结果

正常情况下，服务端会返回下述JSON数据包给客户端：

{"access_token":"ACCESS_TOKEN","expires_in":7200}

参数说明：

参数名称	描述
access_token	获取到的令牌凭证
expires_in	凭证有效时间，单位：秒

2.2装备库存明细查询接口

2.2.1接口定义

该接口由“警备通”提供，用于外部系统调取设备数据。

URL	http://*****/webapi/equitment/inventory
协议	http
请求方式	GET

2.2.2参数说明

参数名称	是否必须	类型	描述
token	必选	String	通过获取鉴权Token接口返回
warehouseId	必选	String	所属装备室
offset	必选	int	分页起始位置
size	选填	int	每页查询数量，大于100时按100条返回

2.2.3返回结果

响应参数说明：

参数名称	描述
code	错误码,200代表成功
message	错误信息
equitments	数组类型，装备列表
equitmentName	装备名称
warehouseName	装备室名称
equitmentNo	装备编号
equitmentType	装备分类
brand	装备品牌
specification	装备规格型号
prescribedQuan	装备规定数量
totalStorage	装备总入库量
totalOut	装备总出库量
remaining	装备剩余库存
maintenance	装备保养周期
check	装备点验周期
position	装备存储位置
price	装备价格
totalScrap	总处置数

2.3个人持有明细接口查询

2.3.1接口定义