人脸门禁服务API

更新时间:2020-07-02 18:19:03

人脸门禁服务解决方案

人脸门禁边缘解决方案>>
边缘模式 / 设备直连云 API

人脸门禁服务概述

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

接口分为三部分:

人脸图片管理

接口名称 接口路径 当前版本
保存人脸图片 /face/paas/image/save 1.1.1 - 项目级
1.0.3 - 租户级
删除人脸图片 /face/paas/image/delete 1.1.1 - 项目级
1.0.0 - 租户级
获取人脸图片 /face/paas/image/get 1.0.2 - 项目级
1.0.1 - 租户级

人脸权限管理

接口名称 接口路径 当前版本
增加人脸权限 /face/paas/permission/add 1.0.0
删除人脸权限 /face/paas/permission/delete 1.0.0
查询用户的权限状态 /face/paas/permission/querybyuser 1.0.1
查询设备的权限状态 /face/paas/permission/querybydevice 1.0.1
查询空间的权限状态 /face/paas/permission/querybyspace 1.0.1

订阅关系管理

接口名称 接口路径 当前版本
增加设备消息推送订阅 /entrance/paas/device/subscription/modify 1.0.0
查询订阅消息推送设备列表 /entrance/paas/device/subscription/query 1.0.0
删除设备消息推送订阅 /entrance/paas/device/subscription/delete 1.0.0

接口定义

人脸图片管理

保存人脸图片

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

path 版本 是否需要登录
/face/paas/image/save 1.1.1 - 项目级
1.0.3 - 租户级
入参
参数 类型 是否必填 备注
userType String 用户类型,与userId共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为userId
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"
}

删除人脸图片

删除单个用户的人脸图片,支持不同用户体系(详见入参)。

path 版本 是否需要登录
/face/paas/image/delete 1.1.1 - 项目级
1.0.0 - 租户级
入参
参数 类型 是否必填 备注
userType String 用户类型,与userId共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为userId
userId String 用户ID
出参

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

示例

入参示例

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

出参示例

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

获取人脸图片

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

path 版本 是否需要登录
/face/paas/image/get 1.0.2 - 项目级
1.0.1 - 租户级
入参
参数 类型 是否必填 备注
userType String 用户类型,与userId共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为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共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为userId
userIdList JSONArray 用户ID列表
scopeType String 人脸信息下发的目标范围类型:
SPACE_ID:将人脸信息下发到空间下绑定的所有人脸识别设备
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共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为userId
userIdList JSONArray 用户ID列表
scopeType String 人脸信息下发的目标范围类型:
SPACE_ID:将人脸信息下发到空间下绑定的所有人脸识别设备
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.1
入参
参数 类型 是否必填 备注
userType String 用户类型,与userId共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为userId
userId String 用户ID
deviceListPageNo Integer 分页查询的请求页码
deviceListPageSize Integer 分页查询的请求页大小
出参

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

参数 类型 备注
userType String 用户类型,与userId共同作为人脸图片的唯一标识,目前支持的取值有
IDENTITY:用identityId作为userId
OPEN:OA三方账号体系
YUNDUN:云盾自定义用户体系
PHONE:用手机号作为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"
}

出参示例

{
    "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.1
入参
参数 类型 是否必填 备注
iotId String 设备ID
pageNo Integer 分页查询的请求页码
pageSize Integer 分页查询的请求页大小
出参

返回结果使用通用结果类型,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"
}

查询空间的权限状态

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

path 版本 是否需要登录
/face/paas/permission/querybyspace 1.0.1
入参
参数 类型 是否必填 备注
spaceId String 空间ID
pageNo Integer 分页查询的请求页码
pageSize Integer 分页查询的请求页大小
出参

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

参数 类型 备注
total Integer 下发到该空间的用户人脸图片总数
pageNo Integer 请求页码
pageSize Integer 请求页大小
userList JSONArray 用户人脸列表,包含userId、userType、userName、expiredTime、extInfo、下发的设备数、下发成功的设备数
示例

入参示例

{
  "spaceId":"aaa"
}

出参示例

{
    "code": 200,
    "data": {
    "total":1,
    "pageNo":1,
    "pageSize":20,
    "userList":
    [
      {
            "userType":"OPEN",
            "userId":"xxx",
        "deviceCount":1,
        "successCount:"1
      }
    ]
    },
    "message": "success"
}

人脸门禁通行事件

人脸门禁通行数据模型

订阅关系管理(推荐使用数据模型定义)

增加设备消息推送订阅

当存在跨租户给设备授权的时候,被授权租户想接收设备上报的事件,需要调用这个接口来做授权

path 版本 是否需要登录
/entrance/paas/device/subscription/modify 1.0.0
入参
字段 类型 是否必传 备注
iotIds JASONArray 待订阅的设备iotId列表,上限50
subscribed Integer 1 订阅,0取消订阅;默认是1
出参
字段 类型 备注
code Integer 返回码
message String 返回信息
data JSONArray 订阅设置失败的设备iotId

ModifyResultDTO定义

字段 类型 备注
iotId String 门禁设备的iotId

示例

入参示例

{
    "iotIds":[
        "p2OsgId2N2kXMWThRCQP000101"
    ],
   "subscribed": 1
}

出参示例

{
    "code": 200,
    "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
    "message": null,
    "localizedMsg": null
}

查询订阅消息推送设备列表

查询已经订阅消息的设备列表,包括已经取消了订阅的设备

path 版本 是否需要登录
/entrance/paas/device/subscription/query 1.0.0

入参

pageSize Integer 分页查询一页内的记录数,上限100
pageNo Integer 分页数,从1开始

出参

字段 类型 备注
code Integer 返回码
message String 返回信息
data JSONObject 返回的分页数据对象

分页数据对象PageDTO

pageSize Integer 传入的pageSize
pageNo Integer 传入的pageNo
total Long 总记录数
data JSONArray 订阅数据列表

UserDTO对象

字段 类型 备注
iotId String 设备iotId
deviceName String 设备dn
productKey String 设备pk
categoryKey String 设备品类
tenantId String 租户Id
subscribed Integer 是否订阅消息
gmtCreate Date 订阅创建时间
gmtModified Date 订阅更新时间

示例

入参示例

{
  "pageSize":10,
  "pageNo":1
}

出参示例

{
    "code": 200,
    "data": {
        "total": 1,
        "data": [{
            "bizCode": "bizTypeTest",
            "categoryKey": "categoryKeyTest",
            "deviceName": "deviceNameTest",
            "gmtCreate": 1556517249000,
            "gmtModified": 1556517249000,
            "iotId": "iotTest",
            "productKey": "productKeyTest",
            "subscribed": 1,
            "tenantId": "tenantTest"
        }]
    },
    "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
    "message": null,
    "localizedMsg": null
}

删除设备消息推送订阅

删除订阅关系

path 版本 是否需要登录
/entrance/paas/device/subscription/delete 1.0.0

入参

字段 类型 是否必传 备注
iotIds JASONArray 待订阅的设备iotId列表,上限50

出参

字段 类型 备注
code Integer 返回码
message String 返回信息

示例

入参示例

{
    "iotIds":[
        "p2OsgId2N2kXMWThRCQP000101"
    ]
}

出参示例

{
    "code": 200,
    "id": "4a70179d-47d8-4fdf-9067-8a5eedf63483",
    "message": null,
    "localizedMsg": null
}

results matching ""

    No results matching ""