文档

人脸权限服务

更新时间:
一键部署

概述

人脸门禁服务是一套为企业提供的支持人脸图片管理与人脸权限管理的服务。人脸门禁服务的云端API同时兼容边缘方案与端侧方案。

人脸图片管理

接口名称

接口路径

当前版本

保存人脸图片

/face/paas/image/save

1.1.1

删除人脸图片

/face/paas/image/delete

1.1.1

获取人脸图片

/face/paas/image/get

1.0.2

人脸权限管理

接口名称

接口路径

当前版本

增加人脸权限

/face/paas/permission/add

1.0.0

删除人脸权限

/face/paas/permission/delete

1.0.0

查询用户的权限状态

/face/paas/permission/querybyuser

1.0.4

查询设备的权限状态

/face/paas/permission/querybydevice

1.0.4

测温配置

接口名称

接口路径

当前版本

设置测温配置

/entrance/paas/face/temperature/config/set

1.0.0

获取测温配置

/entrance/paas/face/temperature/config/get

1.0.0

保存人脸图片

保存单个用户的人脸图片,支持不同用户账号体系,图片以URL或base64编码的格式传入,宽、高不超过800像素,文件大小不超过1MB。

path

版本

/face/paas/image/save

1.1.1

参数

类型

是否必填

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识,目前支持的取值有

IDENTITY:用identityId作为userId

OPEN:OA三方账号体系

userId

String

用户ID

imageUrl

String

图片URL(图片URL和图片base64数据,两者必填其一,优先使用imageUrl)

imageBase64

String

图片base64数据(图片URL和图片base64数据,两者必填其一,优先使用imageUrl)

faceExtInfo

String

设备端业务扩展字段,用于同步到设备端实现业务扩展逻辑,建议使用JSON对象格式,利于标准化扩展;不超过1024字符

userName

String

(标准化扩展字段)用户姓名,当faceExtInfo为JSON对象格式时,以userName为key填充到faceExtInfo中;不超过64字符

expiredTime

String

(标准化扩展字段)过期时间,当faceExtInfo为JSON对象格式时,以expire为key填充到faceExtInfo中,时间格式yyyy-MM-dd HH:mm:ss

userExtInfo

String

云端业务扩展字段,用于设备上报数据时推送给ISV,实现云端业务扩展逻辑;不超过1024字符

policy

String

人脸匹配后人员通行策略。PERMISSION(默认) - 允许; DENY - 禁止通行

返回结果使用通用结果类型,不使用data域。

入参示例

{
  "userType":"OPEN",
  "userId":"xxx",
  "imageUrl":"http://yyy/1.jpg"
}

出参示例

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

常见错误码

code

message

说明

2006

图片文件大小或分辨率不符合要求

宽、高不超过800像素,文件大小不超过1MB

2007

获取图片数据失败

URL下载失败或者BASE64数据解析失败

2012

用户信息未知

identityId或openId不正确

2017

图片内容有误,请确认图片中包含人脸

图片中未检测到人脸

2018

请确认图片中仅包含一个人

图片中检测到多张人脸

2019

照片中人脸区域太小,请对照片进行适度缩放与裁剪

人脸区域在整张图片中占比需要超过总面积的10%

2027

请确保使用正面人脸图片

图片中的人脸偏角过大,可能有以下几种情况:(1)抬头或低头的角度过大;(2)侧脸角度过大;(3)左右歪头的角度过大

2460

request parameter error.

缺少必要参数

删除人脸图片

删除单个用户的人脸图片,支持不同用户账号体系。

path

版本

/face/paas/image/delete

1.1.1

参数

类型

是否必填

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识

userId

String

用户ID

返回结果使用通用结果类型,不使用data域。

入参示例

{
  "userType":"OPEN",
  "userId":"xxx"
}

出参示例

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

获取人脸图片

根据用户ID和用户类型查询人脸图片,返回的图片格式支持URL和base64编码。

path

版本

/face/paas/image/get

1.0.2

参数

类型

是否必填

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识

userId

String

用户ID

imageFormat

String

图片数据的返回格式,目前支持URL和BASE64,默认为URL

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

字段

类型

备注

imageUrl

String

人脸图片URL,当入参imageFormat为空或URL时有值

imageBase64

String

人脸图片base64数据,当入参imageFormat为BASE64时有值

入参示例

{
  "userType":"OPEN",
  "userId":"xxx",
  "imageFormat":"URL"
}

出参示例

{
    "code": 200,
    "data": {
    "imageUrl":"http://yyy/1.jpg"
    },
    "message": "success"
}

增加人脸权限

将已保存的用户人脸图片下发到设备端,使设备权限识别对应的人脸用户。

path

版本

/face/paas/permission/add

1.0.0

参数

类型

是否必填

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识

userIdList

JSONArray

用户ID列表

scopeType

String

人脸信息下发的目标范围类型:

IOT_ID:将人脸信息下发到指定的设备

scopeIdList

JSONArray

人脸信息下发的目标范围列表

返回结果使用通用结果类型,不使用data域。

入参示例

{
  "userType":"OPEN",
  "userIdList":
  [
    "xxx"
  ],
  "scopeType":"IOT_ID",
  "scopeIdList":
  [
    "zzz"
  ]
}

出参示例

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

删除人脸权限

将已保存的用户人脸图片从设备端删除,使设备权限识别对应的人脸用户。

path

版本

/face/paas/permission/delete

1.0.0

参数

类型

是否必填

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识

userIdList

JSONArray

用户ID列表

scopeType

String

人脸信息下发的目标范围类型:

IOT_ID:将人脸信息下发到指定的设备

scopeIdList

JSONArray

人脸信息下发的目标范围列表

返回结果使用通用结果类型,不使用data域。

入参示例

{
  "userType":"OPEN",
  "userIdList":
  [
    "xxx"
  ],
  "scopeType":"IOT_ID",
  "scopeIdList":
  [
    "zzz"
  ]
}

出参示例

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

查询用户的权限状态

根据用户ID和用户类型查询人脸图片信息及其下发的设备列表(含下发状态)。

path

版本

/face/paas/permission/querybyuser

1.0.4

参数

类型

是否必填

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识

userId

String

用户ID

deviceListPageNo

Integer

分页查询的请求页码

deviceListPageSize

Integer

分页查询的请求页大小

statusList

List

目标状态列表

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数

类型

备注

userType

String

用户类型,与userId共同作为人脸图片的唯一标识

userId

String

用户ID

userName

String

用户姓名,不超过64字符

expiredTime

String

人脸图片有效期,时间格式yyyy-MM-dd HH:mm:ss

extInfo

String

业务扩展字段,不超过1024字符

deviceListTotal

Integer

该用户人脸图片执行过下发操作的设备总数

deviceListPageNo

Integer

请求页码

deviceListPageSize

Integer

请求页大小

deviceList

JSONArray

设备列表,包含设备iotId、下发时间、下发状态

入参示例

{
  "userType": "OPEN",
  "userId": "xxx",
  "statusList": [
    "transferred",
    "transferDeleted"
  ]
}

出参示例

{
    "code": 200,
    "data": {
    "userType":"OPEN",
    "userId":"xxx",
    deviceListTotal:1,
    deviceListPageNo:1,
    deviceListPageSize:20,
    deviceList:
    [
      "iotId":"zzz",
      "syncTime":"2019-02-28 19:00:00",
      "syncStatus":"transferred"
    ]
    },
    "message": "success"
}

查询设备的下发状态

查询下发到某个设备的人脸图片列表(含下发状态)。

path

版本

/face/paas/permission/querybydevice

1.0.4

参数

类型

是否必填

备注

iotId

String

设备ID

pageNo

Integer

分页查询的请求页码

pageSize

Integer

分页查询的请求页大小

statusList

List

目标状态列表

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数

类型

备注

total

Integer

下发到该设备的用户人脸图片总数

pageNo

Integer

请求页码

pageSize

Integer

请求页大小

userList

JSONArray

用户人脸列表,包含userId、userType、userName、expiredTime、extInfo、下发时间、下发状态

入参示例

{
  "iotId":"zzz"
}

出参示例

{
  "code": 200,
  "data": {
    "total": 1,
    "pageNo": 1,
    "pageSize": 20,
    "userList": [
      {
        "userType": "OPEN",
        "userId": "xxx",
        "syncTime": "2019-02-28 19:00:00",
        "syncStatus": "transferred"
      }
    ]
  },
  "message": "success"
}

权限状态说明

状态

说明

toBeTransferred

待下发,根据is_delete区分新增下发和删除下发

transferring

下发中,根据is_delete区分新增下发中和删除下发中

deviceOffline

设备离线

transferred

下发成功

faceCheckError

下发失败,提取特征值失败或其他未知原因

faceCheckTimeout

下发失败,提取特征值超时,当前仅用于边缘

faceDlError

下发失败,下载人脸图片失败,当前仅用于边缘

facePushError

下发失败,推送到终端设备出错,当前仅用于边缘

unknownError

下发失败,设备端未返回结果,原因未知

transferDeleted

删除下发成功

deleteFailed

删除下发失败

transferTimeout

下发超时,云端会自动重试

deleteTimeout

删除下发超时,云端会自动重试

needManual

经过多次重试后仍然下发失败,需要人工处理

设置测温配置

设置设备的测温配置,包括是否开启测温以及正常的测温范围。该接口需要与门禁边缘驱动(2.8.0版本及以上)配合使用。

path

版本

/entrance/paas/face/temperature/config/set

1.0.0

参数

类型

是否必填

备注

iotId

String

设备ID,若传入iotId,则忽略productKey和deviceName,否则productKey和deviceName必填

productKey

String

产品标识,若不填iotId,则该字段必填

deviceName

String

设备名称,若不填iotId,则该字段必填

checkTemperature

Boolean

是否开启测温功能

maxThreshold

Float

正常温度范围上限,单位:摄氏度,取值范围0~100,开启测温功能时必填

minThreshold

Float

正常温度范围下限,单位:摄氏度,取值范围0~100,开启测温功能时必填

返回结果使用通用结果类型,不使用data域。

入参示例

{
  "iotId": "1WJ0io2kvh3e5wtSCTuV000000",
  "checkTemperature": true,
  "maxThreshold": 37.5,
  "minThreshold": 0
}

出参示例

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

获取测温配置

获取设备的测温配置,包括是否开启测温以及正常的测温范围。该接口需要与门禁边缘驱动(2.8.0版本及以上)配合使用。

path

版本

/entrance/paas/face/temperature/config/get

1.0.0

参数

类型

是否必填

备注

iotId

String

设备ID,若传入iotId,则忽略productKey和deviceName,否则productKey和deviceName必填

productKey

String

产品标识,若不填iotId,则该字段必填

deviceName

String

设备名称,若不填iotId,则该字段必填

返回结果使用通用结果类型,data域是对象,见下表的详细说明:

参数

类型

备注

checkTemperature

Boolean

是否开启测温功能

maxThreshold

Float

正常温度范围上限,单位:摄氏度,取值范围0~100

minThreshold

Float

正常温度范围下限,单位:摄氏度,取值范围0~100

入参示例

{
  "iotId": "1WJ0io2kvh3e5wtSCTuV000000"
}

出参示例

{
  "code": 200,
  "message": "success",
  "data": {
    "checkTemperature": true,
    "maxThreshold": 37.5,
    "minThreshold": 0
  }
}