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

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

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

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

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

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

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

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

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

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

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

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

接口方式注册设备

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

人员注册

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

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

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

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

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

消息类型定义如下图

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

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

消息类型定义如下图

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

1、手动触发：

2、自动触发：

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

1、权限组约束

2、权限下发注意

3、接口调用注意

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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