门禁对接指南

概述

门禁组件的设计初衷，是通过屏蔽人员权限下发至设备的复杂逻辑和流程，来帮助第三方开发者更加快速便捷的完成与海康人脸门禁设备的能力对接，让第三方开发者更加专注于业务的实现。
通过门禁组件，第三方仅需关注设备和人员本身、以及门禁设备与人员的权限关系，而人员权限下发至门禁设备的过程由组件内部的逻辑进行处理，第三方接收组件抛出的下发结果即可。

使用场景

只要涉及到门禁通行相关的业务场景，基本上都可以通过门禁组件实现。包括：

出入口的门禁权限管控，例如大楼、校园、宿舍、工地、景区等出入管控

刷脸/打卡考勤，例如企业员工考勤、工地实名制等

访客管控，例如社区访客预约、企业访客预约等

概念说明

1、人员：指某个自然人，一般需包含姓名、编号、卡号、人脸等必要的关联信息；需提前通过接口写到基础服务能力的人员管理相关接口中

2、设备：指海康门禁一体机硬件产品；需提前通过基础服务能力的设备管理相关接口添加至开发者账号下

3、权限组：是门禁组件内部定义的，表达人员在设备端的通行权限的关系；当人员和设备在同一个权限组时，该权限组内的人员将拥有该权限组内设备的通行权限；第三方可按照业务需要进行权限的隔离管理

注：最终实际的通行权限，还受到人员权限和计划模板的控制

4、权限下发：指根据权限组，将组内人员信息下发至组内设备的动作和过程。海康的门禁通行权限在设备端进行鉴权判断，因此需要提前将人员权限下发至设备。权限下发支持手动触发或自动触发的方式，权限下发一般是异步方式进行的，单台设备是采用串行下发方式

5、权限下发结果：指权限下发至设备的最终结果，包括成功/失败两种情况；第三方可开通权限下发结果消息类型，在权限下发完成之后，平台会以消息的方式告知用户下发结果；当遇到下发失败时，需要第三方根据业务实际需要进行重试处理

接入流程

步骤1：确保门禁设备通电、配网。

步骤2：获取授权凭证。接口需要授权凭证才能访问，因此需要先行获取。详细获取及使用方式见授权凭证获取。

步骤3：注册门禁设备。设备注册有两种方式，一种是开发者服务门户调试模式下添加设备；另一种是通过接口的方式注册设备。接口方式注册设备请参考基础服务能力 >> 设备管理。

开发者服务门户中注册设备

接口方式注册设备

步骤4：注册人员。人员注册包含基本信息和人脸信息，详细使用说明请参考基础服务能力 >> 人员管理。如需要给人员添加卡号信息，请参考门禁服务能力 >> 新增卡片。如需要给人员添加门禁权限信息，请参考门禁服务能力 >> 权限组绑定人员

人员注册

卡片添加

步骤5：更新人员权限信息。对于绑定权限组时指定权限信息的人员权限进行更新，该接口使用全量更新逻辑,不传的权限参数部分会使用默认值下发，目前仅支持单个人员权限信息的更新，详细使用说明请参考权限下发 >> 人员权限信息更新

步骤6：创建权限组。通过门禁服务下发人员权限到设备上时，需要将人员和设备绑定到权限组。权限组创建请参考门禁服务能力 >> 权限分组#权限组新增。

步骤7：权限组绑定设备。将设备添加到某个有意义的权限组中，后续以权限组为维度进行权限的操作。详细使用说明见门禁服务能力 >> 权限分组#权限组绑定设备。

步骤8：权限组绑定人员。将人员添加到某个有意义的权限组中，后续以权限组为维度进行权限的操作。详细使用说明见门禁服务能力 >> 权限分组#权限组绑定人员。该过程执行后，人员会自动下发到设备上，开发者可至设备后台查看人员是否下发成功。

步骤9：接收权限下发结果消息，详见消息类型定义 >> 门禁权限下发结果消息。要接收该消息，需先至开发者服务开启该消息类型权限，如下图所示：

消息类型定义如下图

如果接收到的消息的syncStatus为1，即同步失败，则需要调用下发失败记录查询接口查看失败原因，详见门禁服务能力 >> 权限下发#查询下发失败记录，如下图所示

步骤10：刷脸或刷卡开门。在设备上刷脸之后，设备会提示开门成功或失败。开门成功时，会上报开门事件消息，开发者通过消息通道获取即可。该消息对应的消息类型为消息类型定义 >> 门禁事件消息，要接收该消息，需先至开发者服务开启该消息类型权限，如下图所示：

消息类型定义如下图

详细使用说明

下发说明

条件：有效人员和设备关联到权限组。

1、手动触发：

按权限组下发：该操作会扫描当前权限组中未下发到其关联的有效设备的人员，以及下发到设备失败的人员权限。

下发所有失败人员：该操作扫描该用户所有权限组下发失败的人员，将对应有效人员（最新人员信息）补偿下发到对应设备中。

2、自动触发：

权限组添加人员：该操作会自动下发当前权限组指定的有效人员到该权限组关联的所有设备中；如果人员绑定权限组时未指定门禁权限信息，则默认使用人员信息中的门禁权限信息；如果人员绑定权限组时指定了门禁权限信息，优先使用权限组门禁权限信息进行下发；

更新人员权限信息：该操作会自动下发修改的人员权限信息到该权限组关联的所有设备中；

权限组移除人员：该操作会自动下发移除指令，从当前权限组关联的所有设备中移除指定的有效人员；如果人员绑定权限组时指定了门禁权限信息，会删除该人员和和权限组对应门禁权限信息；

权限组添加设备：该操作会自动下发当前权限组关联的有效人员到指定的设备中；

权限组移除设备：该操作会自动下发移除指令，从当前权限组指定的设备中移除其关联的所有有效人员；

删除权限组：该操作会将当前权限组中关联的所有人员从其关联设备中移除，并自动下发移除指令；

更新（删除）人员/人脸/卡：该操作会扫描当前人员所关联的权限组，并将更新下发到权限组中所有的设备中；

设备上线：设备上线后，扫描其对应的下发失败的人员记录，进行重新下发。

消息：以上权限下发完成之后，会以消息的方式通知，用户需要订阅并开通消息类型”门禁权限下发结果消息”。

下发过程

约束/注意说明

1、权限组约束

权限组数量上限默认为500，不够需要联系相关人员扩展。

一次只能向权限组添加/移除最多1000个人员。

人员和设备同时支持添加到多个权限组，权限的处理以设备和人员的对应关系为准。

当人员和设备有多个关系时，仅会维护一个人员和设备的关系对；

当人员和设备所有关系都解除后，人员和设备的关系对删除；

权限组关联人员时，会过滤无效人员（不在云眸平台的人员）。

权限组关联设备时，会过滤无效设备（不在云眸平台中的设备）。

2、权限下发注意

在下发过程中，会获取人员信息和设备能力集，对于不是有效人员和没有能力集的设备会跳过下发，并不会抛异常。因此在下发前，需要确认人员是有效的，设备有能力集并且在线。

在进行大量数据同步的时候（比如万人下发到几十台设备），该过程会由于设备本身能力导致时间比较久，需要等待下发结果消息，不可随意删除权限组或清空权限组或移除设备等操作，否则会触发权限移除的下发，造成数据的堆积，增加任务处理的时间。

权限结果查询目前仅支持查询失败的下发记录，没有查询到结果可能的原因是全部成功或正在下发中，但是不表示任务完成，任务是否完成需要以下发结果消息为准。
备注：由于放开了一个人员只能在一个权限组的限制，因此查询结果中的权限组ID并不完全。

3、接口调用注意

涉及到权限下发的接口有锁的限制，不允许并发调用。

对于“下发所有失败人员”这类接口，请勿频繁调用，否则可能会引起数据异常，同时增加任务处理的时间。

如果是删除人员，就不需要调用权限组解绑人员接口，会自动触发权限删除指令。

常见权限操作

备注：
1、权限操作相关接口参考门禁服务能力 >> 权限分组和门禁服务能力 >> 权限下发。
2、以下图示中，序列线上的“开发者”表示开发者主动调用云眸外部独立应用开发接口，“云眸”表示操作由云眸开发者服务发起。
3、以下图示中，“反馈下发结果”表示权限处理完成后，会向开发者的消息通道中发送消息类型定义 >> 门禁权限下发结果消息，开发者需要根据消息通道的说明进行获取。以下过程中不再进行说明。

权限下发到设备

如上图所示，对开发者而言，只需简单的三步即可完成权限的下发和结果查询。图示中的序号即为开发者调用接口的顺序，接下来对每个过程进行简单的说明：

1、权限组绑定设备：该接口表示将设备添加到某个有意义的权限组中，后续以权限组为维度进行权限的操作。在完成绑定后，开发者可以通过对应的查询接口（权限组获取设备序列号列表）查看到已绑定到权限组的设备，以及设备是否具有能力集（没有有效能力集会跳过往该设备上下发权限）。

关于能力集无效说明：如果查询结果中hasCapability为false，说明能力集不可用，请参考设备能力集说明中的指导进行原因排查以及重新获取能力集。

关于权限自动下发说明：在能力集有效情况下，如果权限组中有人员，会自动将该权限组中的有效人员下发到设备中。

2、权限组绑定人员：该接口表示将人员添加到某个有意义的权限组中，后续以权限组为维度进行权限的操作。在完成绑定后，开发者可以通过对应的查询接口（权限组获取人员编号列表）查看到已绑定到权限组的人员。

关于权限自动下发说明：如果权限组中有设备，会自动将有效人员下发到该权限组具有有效能力集的设备中。

3、查询下发失败记录：该接口用来查询下发到设备失败的权限记录。可以通过权限组、设备序列号、人员编号多个维度查询。

从设备移除权限

如上图所示，从设备移除权限仅需要两步即可完成权限的移除和结果查询。图示中的序号即为开发者调用接口的顺序，接下来对每个过程进行简单的说明：

1、权限组解绑人员：该接口表示从某个有意义的权限组中移除人员，同时从该权限组绑定的所有设备中删除人员权限。

关于权限自动下发说明：如果人员和设备同时在其他权限组中，则仅解除该权限组和人员的绑定，不删除设备上的权限。

2、查询下发失败记录：该接口用来查询下发到设备失败的权限记录。可以通过权限组、设备序列号、人员编号多个维度查询。

关于“人员从权限组解绑成功了（前置条件：人员仅在一个权限组），但是设备上没有删除成功”的说明：请调用该查询接口，根据设备序列号和人员编号查询是否有下发失败记录，如果有下发失败记录请关注失败原因，并合理使用门禁服务能力 >> 权限下发#下发所有失败人员接口进行重试。如果查询不到失败记录，请到开放社区根据关键字搜索相关问题或进行提问。

人员相关操作

说明：
1、此处的操作包括：人员编辑、人员删除、人脸添加、人脸更新、人脸删除、卡号添加、卡号删除。相关接口见基础服务能力 >> 人员管理和门禁服务能力 >> 卡片操作。
2、开发者调用了以上接口时，门禁服务会自动触发相关权限的操作（前置条件：人员绑定了权限组），无需再调用权限分组和权限下发相关的接口进行权限操作。

如上图所示，开发者调用上述说明1中的接口后，门禁服务会将相关的信息下发到设备，进行权限的操作。开发者可以在接收到消息时，调用“查询下发失败记录”接口确认权限操作成功与否。

设备上线

设备掉线重新上线后，会扫描下发到该设备失败的权限记录，门禁服务会将有效信息下发到设备，重新进行相关权限的操作。

设备上线的几点说明：
1、为避免设备下线造成权限下发异常，建议开发者关注设备上下线消息（消息类型定义 >> 设备上下线消息），及时知晓设备状态。
2、设备出现频繁上下线时，仅支持每隔30分钟进行一次权限下发。
3、由于设备上线时，设备内部会进行一些初始化操作，如果立马进行权限下发，设备可能会响应超时。因此，会等待2分钟后再执行。

概述#

使用场景#

概念说明#

接入流程#

详细使用说明#

下发说明#

下发过程#

约束/注意说明#

常见权限操作#

权限下发到设备#

从设备移除权限#

人员相关操作#

设备上线#

概述