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

 产品资讯    |      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格式返回给请求者。请求者拿到结果报文,进行解析,然后再进行相应的处理。

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

报文中所有的字典信息(比如性别1-男,2-女),都以代码的值(1或者2)来传递;

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

报文中的日期信息,转换成YYYYMMDD HHmmss文本格式(24小时制)。如果是空日期,则转换成空文本;

报文中的true和false数据类型,转换成 0(表示false)、1(表示true);

报文中的二进制数据(如文件对象),转换成Base64字符方式发送;

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

1.4容错处理

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

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

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

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

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接口定义

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

URL

http://*****/webapi/equitment/personal

协议

http

请求方式

GET

2.3.2参数说明

参数名称

是否必须

类型

描述

token

必选

String

通过获取鉴权Token接口返回

warehouseId

 

必选

String

所属装备室

userId

选填

String

所属警员

offset

必选

int

分页起始位置

size

选填

int

每页查询数量,大于100时按100条返回

2.3.3返回结果

响应参数说明:

参数名称

描述

code

错误码,200代表成功

message

错误信息

equitments

数组类型,装备列表

equitmentName

装备名称

equitmentNo

装备编号

userId

装备持有人

holdingTime

持有时间

purchaseTime

购置时间

price

购置价格

expiration

过期时间

equipmentStatus

装备状态

lastmaintenanceTime

最后维护时间

2.4装备入库明细接口查询

2.4.1