人行边缘接入API(边缘人脸识别)

更新时间：2020-02-28 11:36:10

人脸门禁边缘解决方案>>

1、方案架构及功能

本方案用于将人脸门禁机（可同时带二维码、刷卡和蓝牙功能）接入阿里云IoT边缘服务器。

• 人脸的权限管理与验证在边缘服务器上完成。

• 二维码的权限管理与验证在边缘服务器上完成。

• 刷卡的权限及验证在门禁机上完成。

• 蓝牙的权限及验证在门禁机上完成。

2、通信协议

2.1 要求及说明

• 通信协议基于HTTP，边缘服务器做为HTTP Server时，默认使用10000端口，门禁机支持配置连接服务器的IP地址和端口号。

• 门禁机如果使用蓝牙或者刷卡门禁时，由于边缘服务器需要同步信息给设备，设备应当作为HTTP Server，和边缘服务器建立双向连接，设备的IP地址和服务端口在设备配置信息中提供。

• 所有HTTP报文的首部信息中不能带有Connection: Keep-Alive字段。

• 边缘服务器识别人脸，门禁设备发送给边缘服务器的人脸照片要求：

  • 剪切的图片中包含人脸，比人脸要稍微大一些。
  • 门禁设备最好可以完成人脸抠图，给边缘服务器发送抠图后的人脸图片，可以加速识别速度。如果门禁设备无法完成人脸抠图，可由边缘服务器完成。设备可根据自身情况在识别API中指定选项，默认边缘服务器会执行人脸抠图。
  • 图片尺寸(宽、高)最好保证一致，图片分辨率不低于120 * 120。
  • 人脸图片文件大小不超过1M。

2.2 接口说明

2.2.1 设备连接

2.2.1.1 连接

• 相对url: /connect

• method: POST

• Content-Type：application/json

• 描述： 门禁机向边缘服务器建立连接，建立和边缘服务器的连接。如果门禁机需要支持刷卡门禁及远程开门功能，则前面的连接建立成功后，由边缘服务器向门禁机发起同样的连接请求，门禁机验证后颁发对应通信token，建立起边边缘服务器和门禁机间的双向连接。

• 发起方：门禁机（必须），边缘服务器（可选）

• 请求：

• 返回值：

示例
响应：

成功：

{
    "code": 0,
    "message": "success",
    "data": {
        "token": "xxxx"
    }
}

请求中的json参数无效：

{
    "code": 5,
    "message": "Content-Type is invalid, must be application/json"
}

请求缺少必要的字段：

{
    "code": 5,
    "message": "Missed required field"
}

IP地址无效：

{
    "code": 5,
    "message": "ip format is invalid"
}

keepalive值无效：

{
    "code": 5,
    "message": "keep alive value is invalid"
}

不合法的设备（设备在边缘侧配置的IP地址信息与发起请求的设备实际地址不匹配）：

{
    "code": 5,
    "message": "device is illegal"
}

签名无效：

{
    "code": 6,
    "message": "verify sign error"
}

2.2.1.2 心跳保活

• 相对ulr: /keepalive

• method: POST

• Content-Type：application/json

• 描述：如果一段时间没有业务请求，按照连接建立时连接发起方设定的keepalive保活时间间隔，向服务端发送心跳。

• 发起方：和连接过程对应，由发起连接的客户端发送心跳保活。门禁机（必须），边缘服务器（双向连接时发送）。

• 请求：

• 返回值：

示例
请求：

{
    "token": "1234567890"
}

响应：

心跳接收成功返回值：

{
    "code": 0,
    "message": "success"
}

token无效：

{
   "code": 4,
   "message": "token is invalid"
}

请求参数错误：
请求中的json参数无效

{
   "code": 5,
   "message": "Content-Type is invalid, must be application/json"
}

请求中token不存在

{
   "code": 5,
   "message": "token not exist"
}

2.2.2 人脸识别（边缘）

2.2.2.1 人脸识别请求

• 相对url: /recognize

• method: POST

• Content-Type：multipart/form-data

• 描述： 门禁机获得人脸照片，向边缘服务器发起人脸识别请求，请求携带包含人像的照片

• 发起方：门禁机

• 参数:

• 返回值：

示例
响应：

成功：

{
    "code": 0,
    "message": "success",
    "data":{
        "faceId": "xxxx",
        "name": "xxx",
        "photoId": "xxx"
    }
}

无效的Token：

{
    "code": 4,
    "message": "token is invalid"
}

请求参数非法：

{
    "code": 5,
    "message": "missed required field"
}

设备正忙：

{
    "code": 2,
    "message": "device is busy, try again later"
}

人脸信息不存在：

{
    "code": 1,
    "message": "no face group"
}

人脸照片特征值提取失败：

{
    "code": 1,
    "message": "fail to get face feature"
}

未知错误：

{
    "code": 99,
    "message": "np operate error"
}

没有符合相似度要求的人脸信息：

{
    "code":1,
    "message": "low similarity"
}

禁止该用户通行：

{
    "code":1,
    "message": "policy deny"
}

底库人脸信息已过期：

{
    "code":1,
    "message": "face expired"
}

超出人脸权限时间段：

{
    "code":1,
    "message": "not in the permission time"
}

人脸对比失败：

{
    "code":1,
    "message": "Failed to match face"
}

2.2.2.2 获取底库照片

• 相对url: /staticPhoto

• method: GET

• Content-Type：

• 描述：获取底库照片，可用于比对成功时在门禁机上显示底库照片，photoId在设备收到比对成功响应后3s内有效。

• 发起方：门禁机

• 参数

• 返回值
  • 成功时，返回HTTP code 200 (OK)，并返回底库照片。
  • 缺少入参，返回HTTP code 400(Bad Request)。
  • Token失效，返回HTTP code 401 (Unauthorized)。
  • 找不到底库图片，返回HTTP code 404 (Not Found)。

2.2.4 二维码门禁

2.2.4.1 二维码识别请求

• 相对url: /qrcode

• method: POST

• Content-Type：application/json

• 描述： 门禁机完成扫码，将读取到的二维码发送给边缘服务器，发起二维码验证请求

• 发起方：门禁机

• 参数:

• 返回值：

参数说明

示例
请求：

{
    "token": "1234567890",
    "qrCode": "ALI1234567890azxswdfghggfgsgERTG"
}

响应：

识别成功：

{
    "code": 0,
    "message": "success",
}

二维码未生效：

{
    "code": 1,
    "message": "qrCode not take effect"
}

二维码过期：

{
    "code": 1,
    "message": "qrCode overdue"
}

二维码不存在：

{
    "code": 1,
    "message": "qrCode is not existed"
}

二维码刷码次数用尽：

{
    "code": 1,
    "message": "qrCode use up"
}

无效的Token：

{
    "code": 4,
    "message": "token is invalid"
}

{
    "code": 4,
    "message": "device is offline"
}

请求缺少必要的字段：

{
    "code": 5,
    "message": "Missed required field"
}

二维码设备在边缘服务器上未配置：

{
    "code": 7,
    "message": "device is invalid"
}

2.2.5 刷卡门禁

2.2.5.1 同步刷卡门禁的权限

• 相对url: /cardAC/syncPermissions

• method: POST

• Content-Type：application/json

• 描述： 由Edge端发起权限下发操作。

• 发起方：边缘服务器

• 参数

• 返回值

示例

请求：

{
    "token": "1234567890",
    "permissions": [
        {
            "type": 1,
            "cardId": "1122334455667788",
            "effectiveTime": "1568270392000", 
            "expiryTime": "1599892792000"
        },
        {
            "type": 2,
            "cardId": "00112233445566",
            "effectiveTime": "1568270392000",
            "expiryTime": "1599892792000"
        },
        {
            "type": 3,
            "cardId": "223344556677",
            "effectiveTime": "1568270392000",
            "expiryTime": "1599892792000"
        },
        ...
   ]
}

说明：

• type：操作类型 类型：整型；取值 ：1-增加，2-删除， 3-修改

• cardId：卡号
  类型：字符串

• effectiveTime：卡生效时间
  类型：UTC string 单位精确到毫秒

• expiryTime：卡过期时间
  类型：UTC string 单位精确到毫秒

响应：

成功：

{
    "code": 0,
    "message": "success"
}

同步失败

{
    "code": 8,
    "message": "<失败原因的描述>"
}

2.2.5.2 刷卡通行事件

• 相对url: /cardAC/passEvent

• method: POST

• Content-Type：application/json

• 描述： 当用户在门禁机上刷卡成功时，由门禁机上报刷卡通行事件。

• 发起方：门禁机

• 参数

• 返回值

示例
请求：

{
    "token" : "1234567890",
    "cardId": "门禁卡ID"
}

响应：

通行成功：

{
    "code": 0,
    "message": "success"
}

卡不存在：

{
    "code": 1,
    "message": "card is not existed"
}

无效的Token：

{
    "code": 4,
    "message": "token is invalid"
}

{
    "code": 4,
    "message": "device is offline"
}

请求缺少必要的字段：

{
    "code": 5,
    "message": "missed required field"
}

刷卡设备未在边缘服务器上配置：

{
    "code": 7,
    "message": "device is invalid"
}

2.2.6 蓝牙门禁

2.2.6.1 同步蓝牙门禁的权限

• 相对url: /bleAC/syncPermissions

• method: POST

• Content-Type：application/json

• 描述： 由Edge端发起权限下发操作。

• 发起方：边缘服务器

• 参数

• 返回值

示例

请求：

{
    "token": "1234567890",
    "permissions": [
        {
            "type": 1,
            "cardId": "1122334455667788",
            "effectiveTime": "1568270392000", 
            "expiryTime": "1599892792000"
        },
        {
            "type": 2,
            "cardId": "00112233445566",
            "effectiveTime": "1568270392000",
            "expiryTime": "1599892792000"
        },
        {
            "type": 3,
            "cardId": "223344556677",
            "effectiveTime": "1568270392000",
            "expiryTime": "1599892792000"
        },
        ...
   ]
}

说明：

• type：操作类型 类型：整型；取值 ：1-增加，2-删除， 3-修改

• cardId：蓝牙卡号
  类型：字符串

• effectiveTime：卡生效时间
  类型：UTC string 单位精确到毫秒

• expiryTime：卡过期时间
  类型：UTC string 单位精确到毫秒

响应：

成功：

{
    "code": 0,
    "message": "success"
}

同步失败

{
    "code": 8,
    "message": "<失败原因的描述>"
}

2.2.6.2 蓝牙门禁通行事件

• 相对url: /bleAC/passEvent

• method: POST

• Content-Type：application/json

• 描述： 当用户在门禁机上用蓝牙开门成功时，由门禁机上报蓝牙门禁通行事件。

• 发起方：门禁机

• 参数

• 返回值

示例
请求：

{
    "token" : "1234567890",
    "cardId": "蓝牙卡号"
}

响应：

通行成功：

{
    "code": 0,
    "message": "success"
}

卡不存在：

{
    "code": 1,
    "message": "card is not existed"
}

无效的Token：

{
    "code": 4,
    "message": "token is invalid"
}

{
    "code": 4,
    "message": "device is offline"
}

请求缺少必要的字段：

{
    "code": 5,
    "message": "missed required field"
}

无效的蓝牙门禁设备：

{
    "code": 7,
    "message": "device is invalid"
}

2.2.7 门禁通用功能

2.2.7.1 远程开门

• 相对url: /remoteOpen

• method: POST

• Content-Type：application/json

• 描述： 由Edge端发起开门操作。

• 发起方：边缘服务器

• 参数

• 返回值

示例
请求：

{
    "token": "1234567890"
}

响应：
成功：

{
    "code": 0,
    "message": "success",
}

无效的Token：

{
    "code": 4,
    "message": "token is invalid"
}

请求缺少必要的字段：

{
    "code": 5,
    "message": "missed required field"
}

刷卡设备未在边缘服务器上配置：

{
    "code": 7,
    "message": "device is invalid"
}

2.2.7.2 门禁机报警事件

• 相对url: /alarmEvent

• method: POST

• Content-Type：application/json

• 描述： 门禁机向边缘服务器上报设备的报警事件。

• 发起方：门禁机

• 参数

• 返回值

示例
请求：

防拆报警：

{
    "token" : "1234567890",
    "alarmType": 0
}

无效卡：

{
    "token" : "1234567890",
    "alarmType": 2,
    "cardId": "xxxxxxxx"
}

响应：
成功

{
    "code": 0,
    "message": "success"
}

无效的Token：

{
    "code": 4,
    "message": "token is invalid"
}

请求缺少必要的字段：

{
    "code": 5,
    "message": "missed required field"
}

刷卡设备未在边缘服务器上配置：

{
    "code": 7,
    "message": "device is invalid"
}

3、错误码表

4. 文档发布历史

v2.1.0 2020-03-01

• 【变更】原人脸门禁对接API变更为人行边缘接入API文档，除了边缘人脸识别，还包含二维码门禁、刷卡门禁和蓝牙门禁。

• 【新增】蓝牙门禁对接API。

• 【删除】原有的门禁机运行状态上报API。

v2.0.1 2019-12-30

• 【新增】连接HTTP请求KEEP ALIVE设置说明。

• 【更新】人脸识别请求示例。

• 【更新】刷卡通行事件响应报文示例去掉卡未生效和卡过期。

v2.0.0 2019-12-05

• 【新增】人脸识别请求接口，支持抠脸和非抠脸选项。

• 【更新】同步刷卡门禁的权限接口中，修改请求报文的permissions参数格式。

• 【更新】补全各个接口的响应示例。

• 【新增】刷卡门禁接口，刷卡权限同步错误返回值。

• 【新增】边缘服务器和门禁机间的单向连接调整为双向连接。

• 【更新】获取静态照片错误返回码，增加错误的请求和未认证错误返回code.

v1.0.0 2019-08-30

• 人脸门禁机接入边缘服务器API第一个版本，支持人脸和二维码接口。

• 门禁机到边缘服务器建立单向连接，连接和所有请求均由门禁机发起。