人臉權限服務
概述
人臉門禁服務是一套為企業提供的支持人臉圖片管理與人臉權限管理的服務。人臉門禁服務的云端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
}
}