人脸门禁服务

更新时间：2019-02-15 12:13:21

概述

人脸通行开放平台是一套为企业提供的支持人脸图片管理与人脸通行记录查询的产品。企业可以基于人脸通行开放平台，结合阿里云IoT平台的空间管理功能，快速实现自己的SaaS平台。
本文档是人脸通行开放平台提供的API的手册，说明每个API的参数、结果、使用场景和示例。

下图是人脸通行开放平台（下文简称平台）的核心业务架构：

名词解释

使用须知

1. 服务在使用前，需联系商务同学对appKey授权
2. 最新api版本1.0.0
3. 使用appKey和appSecret
4. 接口支持协议类型https
5. 支持访问形式post

业务概念

用户

平台的用户（或人脸用户）是指可以被人脸识别设备识别的自然人，在平台上使用userId标识，另有userType表示用户类型，用以区分不同企业平台的用户，在同一个用户类型的范围下，userId是唯一的。

设备

平台的设备专指人脸识别设备，每个设备在阿里云IoT平台上有一个唯一标识iotId。

设备需要关联到空间下，用于平台对设备进行管理。

空间

空间是设备在现实世界中位置的抽象，例如小区、房屋、房间、停车场等是属于不同类型的空间，当一个设备与空间绑定后，代表设备“存在”于这个空间中。

注意

目前人脸通行开放平台支持将人脸信息下发到设备或空间，支持的设备是接入物联网平台的人脸识别设备，若下发到空间，需要依赖于空间管理能力，但平台尚未开放空间管理的相关接口，企业需要基于阿里云IoT开放的其他平台能力（例如智能人居开放平台、园区SI管理平台等）实现设备与空间的关联，然后基于人脸通行开放平台实现人脸图片和通行记录的管理。

错误码

统一错误码

业务错误码

通用定义

通用返回结果

通用返回结果是所有接口的返回类型，用来封装错误码或返回数据。所有接口的结果都是下面的结构。

分页参数

分页参数会出现在请求参数和返回结果中

• 在请求参数中代表请求分页的页数（pageNo）和每页的记录数（pageSize）；

• 在响应结果中的页数（pageNo）和每页的记录数（pageSize）与请求参数一致，同时还有total字段代表数据总数。

所有的分页接口除特殊说明外，都遵循下面的约束

数据结构

userFaceInput 人脸输入信息

用于保存人脸信息接口，作为入参的一部分

userFaceOutput 人脸输出信息

用于查询人脸信息接口，作为出参的一部分

userFaceOperationResult 人脸信息处理结果

faceRecord 人脸识别记录数据

ID参数

标识类参数，不做特殊说明的情况下，类型均为字符串，最大长度为64。

接口文档

保存人脸信息

保存用户人脸数据，并将人脸数据下发到指定空间下的所有设备或指定设备。

/face/paas/face/batchsave

• 当前版本 1.0.0

  入参

出参

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

示例

保存空间（rootSpaceId：7032a7c5828a43c78357b8c3ab83ecb1）下用户A002的人脸图片，用户类型为YUNDUN，图片数据用URL表示。保存完成后，用户A可以被空间下的人脸识别设备成功识别。

请求示例

{
  "scopeIdList": [
    "7032a7c5828a43c78357b8c3ab83ecb1"
  ],
  "scopeType": "SPACE_ID",
  "userFaceList": [
    {
      "imageBase64": "",
      "userInfo": "",
      "imageUrl": "https://1.jpg",
      "userId": "A002"
    }
  ],
  "userType": "YUNDUN"
}

返回示例

{
  "code": 200,
  "data": {
    "scopeType": "SPACE_ID",
    "successCount": 1,
    "userType": "YUNDUN",
    "batchResultList": [
      {
        "result": {
          "code": 200,
          "message": "success"
        },
        "scopeId": "7032a7c5828a43c78357b8c3ab83ecb1",
        "userId": "A002"
      }
    ]
  },
  "message": "success"
}

删除人脸信息

删除用户人脸数据，并从指定空间下的所有设备或指定设备中删除相应人脸数据。

/face/paas/face/batchdelete

• 当前版本 1.0.0

  入参

出参

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

示例

删除空间（rootSpaceId：7032a7c5828a43c78357b8c3ab83ecb1）下用户A002的人脸图片，用户类型为YUNDUN。删除完成后，空间下的人脸识别设备将无法识别用户A的人脸。

请求示例

{
  "scopeIdList": [
    "7032a7c5828a43c78357b8c3ab83ecb1"
  ],
  "scopeType": "SPACE_ID",
  "userIdList": [
    "A002"
  ],
  "userType": "YUNDUN"
}

返回示例

{
  "code": 200,
  "data": {
    "scopeType": "SPACE_ID",
    "successCount": 1,
    "userType": "YUNDUN",
    "batchResultList": [
      {
        "result": {
          "code": 200,
          "message": "success"
        },
        "scopeId": "7032a7c5828a43c78357b8c3ab83ecb1",
        "userId": "A002"
      }
    ]
  },
  "message": "success"
}

查询人脸列表

在指定空间或指定设备范围内，分页查询用户人脸数据列表。

/face/paas/face/query

• 当前版本 1.0.0

  入参

出参

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

示例

查询空间（rootSpaceId：7032a7c5828a43c78357b8c3ab83ecb1）下，用户类型为YUNDUN的人脸用户列表。查询第1页数据，每页包含20条记录。

请求示例

{
  "scopeId": "7032a7c5828a43c78357b8c3ab83ecb1",
  "scopeType": "SPACE_ID",
  "userType": "YUNDUN",
  "pageNo": 1,
  "pageSize": 20
}

返回示例

{
  "code": 200,
  "data": {
    "total": 3,
    "data": [
      {
        "gmtModify": "2019-01-26 18:14:57",
        "imageUrl": "http://3.jpg",
        "userType": "YUNDUN",
        "gmtCreate": "2019-01-26 18:14:57",
        "userId": "A003"
      },
      {
        "gmtModify": "2019-01-26 17:43:38",
        "imageUrl": "http://2.jpg",
        "userType": "YUNDUN",
        "gmtCreate": "2019-01-26 17:43:38",
        "userId": "A002"
      },
      {
        "gmtModify": "2019-01-26 17:10:57",
        "imageUrl": "http://1.jpg",
        "userType": "YUNDUN",
        "gmtCreate": "2019-01-26 17:10:57",
        "userId": "A001"
      }
    ],
    "pageNo": 1,
    "pageSize": 20
  },
  "message": "success"
}

查询人脸通行记录列表

分页查询用户人脸通行记录数据列表。

/face/paas/face/record/query

• 当前版本 1.0.0

  入参

出参

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

示例

查询空间（rootSpaceId：7032a7c5828a43c78357b8c3ab83ecb1）下，设备X（iotId：ODFL8xIUDLrtsnfNw90v001020ae10）在2019年1月1日的通行记录。查询第1页数据，每页包含20条记录。

请求示例

{
  "rootSpaceId": "7032a7c5828a43c78357b8c3ab83ecb1",
  "iotId": "ODFL8xIUDLrtsnfNw90v001020ae10",
  "fromTime": "2019-01-01 00:00:00",
  "toTime": "2019-01-01 23:59:59",
  "pageNo": 1,
  "pageSize": 20
}

返回示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "identityId": "xx",
        "userId": "A",//用户ID
        "userType": "YUNDUN",//用户类型
        "iotId": "ODFL8xIUDLrtsnfNw90v001020ae10",//设备ID
        "eventType": "FACE_PASS",//人行类型
        "eventTime": "2019-01-01 01:00:00",//人行时间
        "similarity": "20"//图片对比相似度
      }
    ],
    "total": 1,
    "pageNo": 1,
    "pageSize": 20
  }
}