人脸门禁图片权限管理-人脸权限服务-物联网应用服务（文档停止维护）-阿里云

概述

人脸门禁服务是一套为企业提供的支持人脸图片管理与人脸权限管理的服务。人脸门禁服务的云端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
  }
}