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接口定义
该接口由“警备通”提供,用于外部系统调取设备数据。
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 |
最后维护时间 |