业务目标

1.1. 功能

1.2. 适用场景

2. 基本信息

2.1. 文档中用到的名词

2.2. 调用约定

3. 接口说明

3.1. 实时验证

3.2. 拉取权限

业务目标

本文描述了门禁控制器与第三方系统间的转发软件的功能及实现细节,供第三方系统开发及测试人员参考。

1.1. 功能

主要涉及到控制器在刷卡时实时鉴权和控制器定时从服务器拉取权限。

1.2. 适用场景

软件接收到控制器的实时消息后,转发至第3方服务器实现权限验证,并根据验证结果对控制器远程开门。

由于控制器本身支持直接向服务器发起验证,因此只有因为某些原因控制器不能直接发送请求给服务器实现鉴权时,才需要使用软件来转发。通常有这些情况:

l 服务器需要接收其它控制器不能提供的附加信息,如刷卡时抓拍的图片。

l 服务器是已经开发好的,不可按照控制器的交互方式修改,需要由软件转发并按服务器协议转换请求格式。或者服务器需要使用HTTP返回码(如301)指示控制器跳转到新地址(控制器暂时不支持此功能)。

l 控制器与服务器网络隔断,需要将软件运行在双网卡的电脑上来转发请求。

2. 基本信息

2.1. 文档中用到的名词

本系统:指当前负责转发的软件系统

外部系统:实际负责鉴权和授权的第三方(非我司提供)系统

2.2. 调用约定

控制器主动发起请求,本系统收到后向外部系统转发,收到外部系统返回数据后再向控制器返回数据。

本系统与第三方系统间使用HTTP协议交互,由本系统发起请求第三方系统响应。请求数据在URL或者POST消息体中,如果有POST消息体,则其内容是data为key,json字符串为value的名值对,请求数据以UTF8编码并urlencode,返回数据为UTF8编码,不限格式。

3. 接口说明

3.1. 实时验证

3.1.1. 接口描述

实时验证指控制器在有人刷卡后,立即发送卡信息到软件系统鉴权。软件系统接收到控制器的请求消息后,主动向外部系统发起http请求,并根据外部系统的鉴权结果进行处理。

3.1.2. 数据格式

3.1.2.1. 请求消息

l 本系统收到的同步验证请求格式

控制器在刷卡时发送同步请求(鉴权)到本系统时,其参数数据为

/dr/?d=0011631262|1|24884|7|2013-05-20 18:44:31|6|1|2|24884

请求方式是GET,其中/dr/为请求的地址,参数d即是上报数据内容,以|分隔的各字段值为

卡号或者条码内容|类型标志1|控制器序号|控制器验证结果0表示控制器已经直接开门其它表示错误|刷卡时间|读头号|门号|方向12|设备名称

 

l 在转发消息中添加系统标志

本系统会在参数中添加agent=xxxx,其中xxxx是软件系统的标志,可配置。

假设agent配置为1234,外部系统的服务URL配置为http://test.com/abc.aspx,则转发请求的URL将是

http://test.com/abc.aspx?d=0011631262|1|24884|7|2013-05-20 18:44:31|6|1|2|24884&agent=1234

转发请求会以POST方式发出

 

l 在转发消息中添加其它数据

如果系统配置了抓拍图片,则其它图片类数据将放在POST的消息内容中。消息内容为

data=xxxx

其中xxxxjson格式的字符串。数据以utf8编码并urlencode

对于图片数据,以capture标记,如{capture:” JXU1NkZFJXU3MjQ3…”}

3.1.2.2. 请求消息

通过配置,软件可以接收外部系统返回以下两种方式的数据

l 外部系统鉴权成功后,可以返回约定的内容表示验证通过开门。如success=1,表示成功的标志可以配置,没有检测到成功标志则判断为鉴权失败,软件不会自动开门。

l 将外部系统返回的数据原样转发到控制器。

转发给控制器的数据中可以包含如下标志来指示控制器动作:

ü 网页服务器可以通过返回指定内容来指示控制器开门。

open1=1000表示开启1号继电器1000毫秒

open1=0表示开启1号继电器,时长由控制器继电器的默认配置决定

open4=500 表示开启4号继电器500毫秒

open2=100;open3=100; 表示同时开启23号继电器100毫秒

控制器会搜索网页服务器返回的内容,寻找形如open?=n的内容(其中?1-4n30-60000)作为开门指令进行处理,为了减少控制器处理压力,尽量减少不必要的返回数据。

 

在有openN参数的情况下,可以使用timeN=X表示连续开继电器NX次,多次开关间的时间间隔可以用stopn=Y来控制(Y的单位为毫秒,没有stopn时默认使用200毫秒)。如

open1=1000;time1=5;stopn=500;

表示连续开继电器5次,每次开1秒,间隔时间500毫秒),从而实现刷一次卡或者条码连续进多人的团体票(此功能需要闸机设备支持计数,即控制器开N次继电器后,闸机能够自动放行N人)。

 

ü 如果控制板上外接了迪文DGUS显示屏,则可以将网页服务器返回的数据显示到屏幕上,通过如下方式指定显示内容

prompt=^分隔多行并以$结尾的文本

默认同时在进出显示屏上显示指定内容,如果要指定显示内容的屏,可以通过

prompt-dir=?

其中1表示进入的屏显示指定内容,2表示离开的屏显示指定内容,3表示进出都显示指定内容,未指定则默认为3。另外,以

prompt-page=?

指定显示的页面号(页面号是迪文屏开发时设计的界面的编号,不指定则默认为1表示显示刷身份证信息的页面,注意显示身份证信息的页面中的姓名需要填UNICODE字符。0表示默认页面,2表示刷IC/条码结果显示的页面)。以

restore-page=?

指定显示超时后恢复到哪个显示页面号,通常是默认页面0,。以

restore-seconds=?

指定显示超时时间。

restore-seconds=5& restore-page=0& prompt-page=2&prompt-dir=3&prompt=姓名1^性别2^卡号3^测试4^结果5^时间6^预留7^预留8$

表示在进和出两个屏上以页面2为背景显示数据并持续5秒,5秒后切换到页面0

 

ü 如果控制板是语音板(JL-IDD-Z4S)则可以指定播放板载语音,通过

sound=?

指定要播放的语音的索引号(1开始),可以通过

loop=?

指定要播放的次数,如果不指定则默认为1

sound=1&loop=2 表示播放“刷卡成功”2次。(默认序号1是刷卡成功)

 

ü 如果板上外接了TTS的语音芯片,则可以通过

tts=$结束的文本

来指定TTS内容,指定的内容将被发送给语音芯片朗读播放

tts=您好,欢迎光临,今天是2016325$

 

ü 如果开门后应用想要知道是否有人过闸,可以通过判断过闸超时通知来实现。通过控制板的信号配置指定当前通道人员通过后的反馈信号,控制器在开门后指定时间内没有检测到人员通过信号,就会触发“过闸超时”通知。此通知将被模拟为特殊卡号7777777的刷卡实时通知上报给HTTP服务器。

 

ü 网页服务器返回控制文本给控制器后,默认情况下控制器执行完成操作后不会再给网页服务器发送结果,如果需要控制器发送执行结果,可以要返回内容是加入

cmdseq=xxxx

3.1.3. 补充说明

3.2. 拉取权限

3.2.1. 接口描述

控制器打开了拉取权限开关时,会定时向本系统发起拉取权限请求,本系统会将请求转发至外部系统。此功能仅在本系统配置为“直接转发外部系统的返回数据到控制器”时才生效。

3.2.2. 数据格式

本系统收到的权限拉取请求为

/dr/?d=.getright.设备全局标志|设备标志|设备名称|操作批次号

 

与验证接口一样,系统会添加agent参数后转发到外部系统。外部系统如果有新的权限操作,则生成权限同步数据返回给本系统,本系统将其转发给控制器。权限同步数据格式如下:

权限同步信息为文本数据,分为多条记录。每条记录可以表示添加、删除、修改、清空中的一种类型。每条数据记录格式为(注意格式需要严格匹配):

 

【序号=1;卡号=1234567890;生效时间=2015-02-03 00:00:00;失效时间=2030-01-01 23:59:58;时段=0;读头=255;次数余额=65535;位置=未知;类型=1;反潜回=0;包裹=0;欠费=0;用户标志1=0;用户标志2=0;用户标志3=0;

 

字段说明:

1. 序号取值为1,2,3,4,分别表示添加、删除、修改、清空。非此范围的值默认当成1处理。

2. 卡号为10IC卡号或者18位身份证号码

3. 生效失效时间为YYYY-MM-DD HH:MI:SS格式的时间,其中小时为24小时制

4. 时段0-2558位,每位表示一个时段,0表示所有时段都可开门

5. 读头0-2558位,每位表示一个读头(1-4位表示COM1-COM4串口读头上使用,5-8位表示韦根1-韦根4),如255表示当前授权卡可在控制器的任意读头上使用

6. 次数余额为可刷卡次数,65535表示无限次。

7. 位置值为外部/内部/机密区/未知四种取值,其它取值都认为是未知。权限下发时建议使用未知。

8. 类型为人员类型,取值1-15

9. 反潜回、包裹、欠费、用户标志1、用户标志2、用户标志3都是标志位,取值为0或者1,建议使用默认值0

 

添加操作时,各字段都有意义。

删除操作时,仅卡号有意义。

修改操作时,各字段都有意义。根据卡号找到原记录并更新。

清空操作时,各字段都无意义。直接清除控制器全部权限。

 

注意,无论序号取值为1,2,3,4(即添加、删除、修改、清空)中哪一种,每一行的格式需要保持统一,各字段可以留空或者填充合理的默认值。

 

参考“综合门禁控制器工具”的“权限配置”界面,同步文件格式即是此界面中“下载权限”下载生成的文件格式。上述相关字段取值也可以参考此界面。

 

返回的权限数据以UTF8编码,本系统会将其转换成GBK并返回给控制器。控制器收到数据后会开始处理,处理完成后,将向本系统发送处理结果通知,通知格式如下:

/dr/?d=.ackright.设备全局标志|设备标志|设备名称|结果码0表示成功|操作批次号

同样的,本系统将此消息加上agent参数后转发给外部系统。外部系统接收到此消息后,在自己系统中对上次同步处理的数据标记为“成功”。在外部系统中,已经返回给本系统的权限数据,但还没有收到成功的处理结果通知时,其结果是未知的,可能已经成功,也可能未成功,对于这种数据,建议作为未成功对待,在下次收到同步请求时继续处理。

3.2.3. 补充说明