1. 概述

人脸门禁服务是一套为企业提供的支持人脸图片管理与人脸权限管理的服务。企业可以基于人脸门禁服务，结合阿里云IoT平台的空间管理功能，快速实现自己的SaaS平台。人脸门禁服务的云端API同时兼容边缘方案与端侧方案。

2. 接口定义

2.1 人脸图片管理

2.1.1 保存人脸图片

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

路径	/face/paas/image/save
版本号	1.2.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
userType	String	是	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：用identityId作为userId：用手机号作为userId
userId	String	是	用户ID（identityId或手机号）
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字符
userRole	整型	否	用户扩展字段：用户角色
mobile	字符串	否	用户扩展字段：用户手机号
policy	String	否	人脸匹配后人员通行策略 PERMISSION（默认） - 允许 DENY - 禁止通行

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.2.0");
// 设置参数
request.putParam("userType","value1");
request.putParam("userId","value2");
request.putParam("imageUrl","value3");
request.putParam("imageBase64","value4");
request.putParam("faceExtInfo","value5");
request.putParam("userName","value6");
request.putParam("expiredTime","value7");
request.putParam("userExtInfo","value8");
request.putParam("userRole","value9");
request.putParam("mobile","value10");
request.putParam("policy","value11");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/paas/image/save", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.1.2 删除人脸图片

删除单个用户的人脸图片，支持不同用户体系（详见入参）。

路径	/face/paas/image/delete
版本号	1.2.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
userType	String	是	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：【IDENTITY】用identityId作为userId；【OPEN】OA三方账号体系；【YUNDUN】云盾自定义用户体系；【PHONE】用手机号作为userId
userId	String	是	用户ID

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.2.0");
// 设置参数
request.putParam("userType","value1");
request.putParam("userId","value2");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/paas/image/delete", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.1.3 获取人脸图片

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

路径	/face/paas/image/get
版本号	1.2.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称	类型	是否必选	描述
userType	String	是	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：【IDENTITY】用identityId作为userId；【OPEN】OA三方账号体系；【YUNDUN】云盾自定义用户体系；【PHONE】用手机号作为userId
userId	String	是	用户ID
imageFormat	String	否	图片数据的返回格式，目前支持URL和BASE64，默认为URL

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSON	响应结果

响应结果 data：

名称	类型	描述
imageUrl	String	人脸图片URL，当入参imageFormat为空或URL时有值
imageBase64	String	人脸图片base64数据，当入参imageFormat为BASE64时有值
faceId	String	人脸ID
userId	String	用户ID
userType	String	用户类型
userName	String	用户名称
expireTime	String	超时时间
policy	String	通行策略

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.2.0");
// 设置参数
request.putParam("userType","value1");
request.putParam("userId","value2");
request.putParam("imageFormat","value3");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/paas/image/get", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null,
    "data": {
        "imageUrl":"http://yyy/1.jpg",
        "faceId":"xxx",
        "userId":"xxx",
        "userType":"PHONE",
        "userName":"xxx",
        "expireTime":"yyyy-MM-dd HH:mm:ss",
        "policy":"PERMISSION"
    }
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.2 人脸权限管理

2.2.1 增加人脸权限

将已保存的用户人脸图片下发到设备端，使设备有权限识别对应的人脸用户。支持从设备维度和空间维度进行下发。

路径	/face/paas/permission/add
版本号	1.2.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	25000

请求参数

名称	类型	是否必选	描述
userType	String	是	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：【IDENTITY】用identityId作为userId；【OPEN】OA三方账号体系；【YUNDUN】云盾自定义用户体系；【PHONE】用手机号作为userId
userIdList	JSONArray	是	用户ID列表【单次下发：最多支持10个用户】
scopeType	String	是	人脸信息下发的目标范围类型：：将人脸信息下发到空间下绑定的所有人脸识别设备：将人脸信息下发到指定的设备
scopeIdList	JSONArray	是	人脸信息下发的目标范围列表

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.2.0");
// 设置参数
request.putParam("userType","value1");
request.putParam("scopeType","value2");
request.putParam("scopeIdList","value3");
request.putParam("userIdList","value4");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/paas/permission/add", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": "success"
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.2.2 删除人脸权限

将已保存的用户人脸图片从设备端删除，使设备无权限识别对应的人脸用户。支持从设备维度和空间维度进行删除。

路径	/face/paas/permission/delete
版本号	1.2.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	25000

请求参数

名称	类型	是否必选	描述
userType	String	是	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：【IDENTITY】用identityId作为userId；【OPEN】OA三方账号体系；【YUNDUN】云盾自定义用户体系；【PHONE】用手机号作为userId
userIdList	JSONArray	是	用户ID列表
scopeType	String	是	人脸信息下发的目标范围类型：：将人脸信息下发到空间下绑定的所有人脸识别设备：将人脸信息下发到指定的设备
scopeIdList	JSONArray	是	人脸信息下发的目标范围列表

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.2.0");
// 设置参数
request.putParam("userType","value1");
request.putParam("userIdList","value2");
request.putParam("scopeType","value3");
request.putParam("scopeIdList","value4");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/paas/permission/delete", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": null,
    "localizedMsg": null
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.2.3 查询用户的权限状态

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

路径	/face/paas/permission/querybyuser
版本号	1.0.4
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	3000

请求参数

名称	类型	是否必选	描述
userType	String	是	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：【IDENTITY】用identityId作为userId；【OPEN】OA三方账号体系；【YUNDUN】云盾自定义用户体系；【PHONE】用手机号作为userId
userId	String	是	用户ID
deviceListPageNo	Integer	否	分页查询的请求页码
deviceListPageSize	Integer	否	分页查询的请求页大小
statusList	JSON	否	权限状态

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSON	响应结果

响应结果 data：

名称	类型	描述
userType	String	用户类型，与userId共同作为人脸图片的唯一标识，目前支持的取值有：用identityId作为userId ：用手机号作为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、下发时间、下发状态

设备列表 deviceList：

名称	类型	描述
iotId	字符串	设备ID
syncTime	字符串	下发时间
status	字符串	下发状态： toBeTransferred-等待传输；transferring-传输中； transferred-传输完成； deviceOffline-设备离线或者设备异常；faceCheckError-人脸落库失败（可能照片不符合要求）； transferDeleted-人脸照片在底库中被删除； deleteFailed-删除照片失败
deviceNickName	字符串	设备昵称
cron	字符串	有效期表达式

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.4");
// 设置参数
request.putParam("userType","value1");
request.putParam("userId","value2");
request.putParam("deviceListPageNo","value3");
request.putParam("deviceListPageSize","value4");
request.putParam("statusList","value5");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/paas/permission/querybyuser", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
    "id": "4de2c367-c1db-417c-aa15-8c585e595d92",
    "code": 200,
    "message": "success",
    "localizedMsg": "success",
    "data": {
    "userType":"OPEN",
    "userId":"xxx",
    "deviceListTotal":1,
    "deviceListPageNo":1,
    "deviceListPageSize":20,
    "deviceList":
    [
        {
      "iotId":"zzz",
      "syncTime":"2019-02-28 19:00:00",
      "syncStatus":"transferred"
        }
    ]
  }
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

2.3 人脸质量评估

2.3.1 人脸质量评估接口

路径	/face/quality/query
版本号	1.0.0
协议	HTTPS
请求方法	POST
授权类型	app签名
超时时间	10000

请求参数

名称

类型

是否必选

描述

faceUrl

String

是

⼈脸图⽚地址，Http

provider

String

是

算法提供商，枚举值：

Alipay，IoT，Damo

返回数据

名称	类型	描述
code	Int	接口返回码。200表示成功。
message	String	调用失败时，返回的出错信息。
localizedMsg	String	本地语言的错误消息。
data	JSON	响应结果

响应结果 data：

名称	类型	描述
requestId	string	request_id
faceNum	int	检测出来的⼈脸个数
faceRect	int数组	返回⼈脸矩形框，分别是[left, top, width, height], 如有多个⼈脸，则依次顺延，返回矩形框_。如有两个⼈脸则返回[left1, top1, width1, height1, left2, top2, width2, height2]
faceProb	float数组	返回⼈脸概率, 0-1之间，如有多个⼈脸，则依次顺延_。如有两个⼈脸则返回[face_prob1, face_prob2]
pose	float数组	返回⼈脸姿态[yaw, pitch, roll]， yaw为左右⻆度，取值[-90, 90]，pitch为上下⻆度，取值[-90, 90]， roll为平⾯旋转⻆度，取值[-180, 180]，如有多个⼈脸，则依次顺延
landmarkNum	int	特征点数⽬，⽬前固定为5点（顺序：左眼，右眼，⿐⼦6点，左嘴⻆，右嘴⻆）
landmark	float数组	特征点定位结果，每个⼈脸返回⼀组特征点位置，表示⽅式为（x0, y0, x1, y1, ……）；如有多个⼈脸，则依次顺延，返回定位浮点数
gender	int数组	0：⼥性，1：男性，如有多个⼈脸，则依次返回性别
age	int数组	年龄0-100，如有多个⼈脸，依次返回年龄
expression	int数组	2种表情，0：中性， 1：微笑
glass	int数组	是否佩戴眼镜，0：⽆眼镜，1：有眼镜

示例

请求示例：

// https://github.com/aliyun/iotx-api-gateway-client
IoTApiClientBuilderParams ioTApiClientBuilderParams = new IoTApiClientBuilderParams();

ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");

SyncApiClient syncApiClient = new SyncApiClient(ioTApiClientBuilderParams);

IoTApiRequest request = new IoTApiRequest();

// 设置请求ID
String uuid = UUID.randomUUID().toString();
String id = uuid.replace("-", "");
request.setId(id);
// 设置API版本号
request.setApiVer("1.0.0");
// 如果需要登录，设置当前的会话的token，token通过登录api获取
request.setIotToken("你的<IoTToken>");
// 设置参数
request.putParam("provider","value1");
request.putParam("faceUrl","value2");
// 如果需要，设置headers
Map<String, String> headers = new HashMap<String, String>(8);
// headers.put("你的<header", "你的<value>");

// 设置请求参数域名、path、request , isHttps, headers
ApiResponse response = syncApiClient.postBody("api.link.aliyun.com", "/face/quality/query", request, true, headers);

System.out.println(
    "response code = " + response.getCode()
        + " response = " + new String(response.getBody(), "UTF-8")
        + " headers = " + response.getHeaders().toString()
);

正常返回示例：

{
  "code": 200,
  "data": {
    "iris": null,
    "glass": [
      0
    ],
    "expression": [
      0
    ],
    "gender": [
      1
    ],
    "pose": [
      -1,
      -2,
      1
    ],
    "faceNum": 1,
    "faceProb": [
      1
    ],
    "requestId": "02393494-897F-478A-BF93-72A66340A0FC",
    "faceRect": [
      170,
      138,
      245,
      328
    ],
    "landmarkNum": 105,
    "landmark": [
      189.2341766357422,
      244.83270263671875,
      263.9117431640625,
      235.50816345214844,
      223.74264526367188,
      213.3116912841797,
      225.18899536132812,
      231.9640350341797,
      195.27978515625,
      229.09661865234375,
      207.72967529296875,
      217.909423828125,
      240.44154357910156,
      214.62469482421875,
      256.0074462890625,
      220.8974151611328,
      200.65699768066406,
      238.69119262695312,
      212.3941650390625,
      233.17869567871094,
      238.10061645507812,
      233.05096435546875,
      250.9724884033203,
      234.63412475585938,
      314.1351318359375,
      238.15829467773438,
      389.20306396484375,
      246.52294921875,
      355.11920166015625,
      216.89163208007812,
      353.19873046875,
      234.36343383789062,
      322.86474609375,
      224.12869262695312,
      338.559326171875,
      218.57135009765625,
      371.3887023925781,
      220.08120727539062,
      384.1372375488281,
      230.62918090820312,
      327.1981506347656,
      237.35391235351562,
      340.1736755371094,
      235.63998413085938,
      366.2593994140625,
      234.1768341064453,
      378.302001953125,
      239.27926635742188,
      211.5428466796875,
      266.6617126464844,
      254.77716064453125,
      268.15924072265625,
      216.42266845703125,
      262.96588134765625,
      221.82733154296875,
      260.094482421875,
      227.68597412109375,
      258.33538818359375,
      233.78591918945312,
      257.9173583984375,
      239.88876342773438,
      258.3575744628906,
      245.7425994873047,
      260.1201171875,
      250.83941650390625,
      263.48358154296875,
      216.4285430908203,
      269.462646484375,
      221.8634033203125,
      270.9305725097656,
      227.40357971191406,
      271.9388732910156,
      233.01028442382812,
      272.46429443359375,
      238.6412811279297,
      272.4317321777344,
      244.25062561035156,
      271.9342041015625,
      249.73974609375,
      270.6767272949219,
      323.91925048828125,
      269.5917663574219,
      367.63409423828125,
      268.4336853027344,
      328.056640625,
      264.9695739746094,
      333.44500732421875,
      261.895263671875,
      339.3934631347656,
      260.11883544921875,
      345.53680419921875,
      259.2233581542969,
      351.7408142089844,
      259.4993896484375,
      357.7361755371094,
      261.11572265625,
      363.1594543457031,
      264.13311767578125,
      328.9476623535156,
      272.4422607421875,
      334.52117919921875,
      273.97210693359375,
      340.22454833984375,
      274.9097595214844,
      345.99761962890625,
      275.195556640625,
      351.76171875,
      274.76519775390625,
      357.43511962890625,
      273.6596984863281,
      362.8805847167969,
      271.72186279296875,
      288.5384826660156,
      271.520751953125,
      286.1998291015625,
      331.32574462890625,
      287.2810974121094,
      301.2675476074219,
      286.2149658203125,
      347.75140380859375,
      255.48033142089844,
      344.3111572265625,
      318.2540588378906,
      347.0624084472656,
      245.88827514648438,
      392.71600341796875,
      328.6979064941406,
      392.91510009765625,
      253.7222137451172,
      392.2544250488281,
      320.916259765625,
      392.8489685058594,
      287.09417724609375,
      379.467529296875,
      276.6300048828125,
      376.14068603515625,
      298.02484130859375,
      376.5364685058594,
      260.374755859375,
      382.62030029296875,
      314.23968505859375,
      382.96148681640625,
      252.67446899414062,
      387.02081298828125,
      267.9718017578125,
      378.063720703125,
      306.6196594238281,
      378.546630859375,
      321.9701843261719,
      387.22088623046875,
      286.06634521484375,
      415.8150634765625,
      264.0054931640625,
      408.02960205078125,
      309.4367980957031,
      408.4892883300781,
      254.72647094726562,
      400.63348388671875,
      274.3739013671875,
      413.792724609375,
      298.3180847167969,
      413.9489440917969,
      319.3194580078125,
      401.0159912109375,
      286.95135498046875,
      392.3644714355469,
      287.06842041015625,
      394.86602783203125,
      270.33563232421875,
      389.91778564453125,
      270.4597473144531,
      392.7579345703125,
      303.978271484375,
      390.0447082519531,
      303.95709228515625,
      393.2314453125,
      261.9865417480469,
      390.7685241699219,
      262.09649658203125,
      392.370849609375,
      278.65557861328125,
      391.0590515136719,
      278.7314147949219,
      394.0658874511719,
      295.47149658203125,
      391.2536315917969,
      295.53363037109375,
      394.26373291015625,
      312.50531005859375,
      391.0933837890625,
      312.430419921875,
      392.76031494140625,
      167.90496826171875,
      258.4239501953125,
      414.7978515625,
      266.3011779785156,
      282.4410095214844,
      469.7729797363281,
      182.39126586914062,
      380.735107421875,
      392.3157653808594,
      389.7607116699219,
      170.78298950195312,
      319.3047790527344,
      407.664306640625,
      328.16729736328125,
      223.0463104248047,
      438.533203125,
      345.96502685546875,
      445.37750244140625
    ],
    "class": "com.alibaba.iot.tgc.base.dto.PicQualityDTO",
    "age": [
      28
    ]
  },
  "message": "damo face quality success",
  "localizedMsg": null,
  "class": "com.aliyun.iotx.common.base.service.IoTxResult"
}

异常返回示例：

{
    "id": "37f7e5fa-d6a5-4efe-8abf-5bf23dca6284",
    "code": 403,
    "message": "request forbidden.",
    "localizedMsg": "请求被禁止",
    "data": null
}

3. 数据模型定义

3.1 刷脸记录

模型ID：iotx_face_record_model

模型版本：1.4

属性列表：

属性名称	属性标识符	数据类型	数据描述
记录标示	eventId	String	记录标示
创建时间	gmtCreate	Date	创建时间
上报时间	eventTime	Date	上报时间
用户Id	userId	String	用户Id，和人脸图片的userId对应
用户类型	userType	String	用户类型，支持IDENTITY_ID、OPEN_ID
设备扩展信息	deviceExtInfo	String	设备扩展信息，（边缘端上报的事件包含设备PK/DN。示例：{"productKey":"a11q0MdjQ6d", "deviceName":"iot_face_dev"}）
通行方式	mediaType	String	开门方式，例如face
设备id	iotId	String	设备ID
空间id	spaceId	String	如果设备绑到空间下，表示设备所在空间Id
用户信息扩展信息	userExtInfo	String	用户扩展信息
数据来源行业	source	String	数据来源行业（人居、园区等）
人脸抓拍图片	pictureUrl	String	人脸抓拍图片URL
根空间ID	rootSpaceId	String	设备所在根空间ID，用于实现业务隔离
通行策略	policy	String	通行策略
通行事件信息	eventExtInfo	String	事件扩展信息 { "code": 0, //0为通行成功 "message": "xxx" //通行失败原因 }

3.2 通行失败事件码说明

通行结果（code）	结果说明（message）
0	成功	success
501	人脸信息未生效	Face auth does not take effect
502	人脸信息已过期	Face information has expired
503	人脸库为空	Face library is empty
504	人脸照片特征值提取失败	Face feature extraction failed
505	人脸匹配的相似度低于阈值	Face matching similarity is less than the threshold
506	黑名单用户	The user is in blacklist
507	人脸识别超时	Face recognition timeout
10000	未知错误	Unknown error

3.3 门禁服务业务数据推送

说明：门禁服务在处理具体业务时，一些过程信息对上层应用来说也是必要的，如人脸门禁的下发过程，涉及人脸状态的变更，从初始状态到完成，或异常，需要推送给业务平台，做后续的补发、重发处理。一些设备无响应状态，也透出给上层应用，判断是否重启设备。

模型ID: BizDataPushModel

模型版本：1.1

属性列表：

属性名称	属性标识符	类型	长度	非空	数据描述
记录标示	eventId	String	256	是	记录标示
事件时间	eventTime	Date		是	事件时间
业务类型	bizType	String	64	是	当前消息的类型人脸同步状态 FACE_SYNC_STATUS 设备同步异常 DEVICE_SYNC_ERROR 人脸设备上报权限数据 FACE_DEVICE_PERMS
业务标识	bizId	String	64	是	一般来说bizId是ISV可以索引的业务实体标识。由bizIdType标识这个字段要描述的信息。
业务标识类型	bizIdType	String	128	是	描述bizId表示的内容 IOT_ID 设备 FACE_ID 人脸
业务数据	data	String	2048		数据部，可空
业务数据URL	dataUrl	String	1024		如果数据较大，可以通用URL下发数据，
数据URL的有效期	dataUrlExpire	Date			数据URL的有效期
消息级别	eventLevel	String	64	是	消息的级别 INFO WARN ERROR
消息描述信息	eventText	String	2048		推送文本，如当前消息的处理建议

下面分别说明业务类型bizType为FACE_SYNC_STATUS，DEVICE_SYNC_ERROR，FACE_DEVICE_PERMS时的data域或dataUrl的定义

3.3.1. 人脸同步状态

bizType = FACE_SYNC_STATUS
当人脸开始下发时，推送toBeTransferred状态
当完成下发时，推送transferred或transferDeleted
当下发异常时，推送needManual
preStatus是变更前的状态，可能值有

toBeTransferred
deviceOffline
faceCheckTimeout
faceCheckError
facePushError
unknownError
transferTimeout
deleteTimeout
needManual

data域

属性名称	属性标识符	类型	非空
人员ID	identityId	String	是
人脸ID	faceId	String	是
状态	status	String	是
前置状态	preStatus	String

3.3.2. 设备同步异常

bizType = DEVICE_SYNC_ERROR
当同步设备出现错误时，推送相关错误信息。

data域

属性名称	属性标识符	类型	非空
设备ID	iotId	String	是
错误结果	result	String	是
错误码	code	Integer
错误信息	message	String

3.3.3. 设备上报数据

bizType = FACE_DEVICE_PERMS
当查询设备全量数据时，同步推送数据。

dataUrl域，设备上报数据

属性名称	属性标识符	类型	非空
成功列表	addFaceInfos	Array	是
	faceId
失败列表	failedFaceInfos	Array	是
	faceId