一、 场景描述
iSC 平台的门禁产品及功能在项目应用广泛，第三方对接门禁权限功能的需求也越来也
多，由于门禁权限下发需要涉及到往设备上下发，第三方接口调用一旦不正确，不合理的接
口调用很容易给我们平台造成额外的性能消耗，甚至导致我们平台挂掉，特此梳理下门禁权
限调用流程供大家参考。
二、 流程简介
以 1.3.0 的 api 接口为例，我们提供了四种应用场景的 api 接口：
1 、 给单个人员下发单个门禁权限的应用场景；
2 、 指定人员集和门禁设备集异步下发权限的场景；
3 、 根据权限配置指定门禁设备集异步快捷下发的场景；
4 、 根据权限配置，通过创建下载任务的方式异步下发大批量的场景。
三、 接口调用流程
1. 单个人员下发单个门禁
简单同步权限下载 _ 根据人员与设备通道指定下载：
这种是最简单的一种权限下发场景，一次只下发一个人员到一个门禁设备的场景，该接
口为同步下发接口，接口直接返回下发结果，大批量权限下发的时候不建议用频繁调用该接
口的方式下发。接口说明如下：
入参中 resourceInfo( 资源设备对象信息 ) 需要传入的是门禁设备信息：
resourceIndexCode( 资源的唯一标识 ) 对应的是门禁设备编号；
resourceType( 资源类型 ) 传 acsDevice( 对应门禁设备的资源类型 ) ；
channelNos( 资源通道号 ) 是门禁点对应的门禁设备的通道号
这三个信息可以通过 查询门禁点列表接口 获取到，对应关系如下：
资源设备对象信息
门禁点信息
资源设备对象信息 | 门禁点信息 |
resourceIndexCode( 资源的唯一标识 ) | acsDevIndexCode( 所属门禁设备唯一标识 ) |
channelNos( 资源通道号 ) | channelNo( 通道号 ) |
注意：当人员是系统内人员 ( 即平台上的人员 ) 的时候，人员信息中的卡片信息和人脸信息不需要传入，默认
从人员基础信息中获取并下发；当人员是系统外人员时，卡片信息和人脸信息需要手动传入 ( 针对该部分人
员的，门禁事件上报到平台的是匹配不到人员基础信息 ) 。
2. 指定人员集和门禁设备集异步下发
这种场景是通过创建下载任务 ( 类似事务的模式 ) ，在下载任务中指定人员集的门禁设备
集权限，然后开始执行下载任务，我们服务端异步执行异动下发的场景，接口调用流程如下：
2.1 创建下载任务_根据人员与设备通道指定下载
该接口用来创建要下载的任务类型，接口说明如下：
入参中的 taskType 用来指定创建的下载任务类型， taskType 的枚举值为
2.2 下载任务中添加数据_根据人员与设备通道指定下载
任务创建成功后，在任务中通过指定人员集和门禁设备集，来实现人员的门禁权限的配
置，接口说明如下：
其中的 resourceInfos( 资源对象 ) 和 personInfos( 人员信息 ) ，使用方式及数据来源和“简单同步权限下载
_ 根据人员与设备通道指定下载”接口相同。
2.3 开始下载任务
开始下载任务，将上一步任务中添加的人员对应门禁权限配置开始往门禁设备上下发，
接口说明如下
入参中的 taskId 同前两步中的下载任务唯一标识。
该接口调用后，就把下载任务提交给我们平台，接口返回结果 ( 表示我们平台已经收到
下载任务 ) ，我们平台开始异步下发权限，下发进度及下发详情等信息需要再异步调用后续
接口查询。
2.4 查询下载任务进度
通过下载任务唯一标识(taskId)查询权限异步下载进度，接口说明如下：
2.5 查询设备通道的人员权限下载详情
通过 “ 记录唯一 ID” 或者 “ 下载任务标识 + 设备通道对象 ” 查询权限下载详情，查看具体每
条下载记录的结果，接口说明如下
3. 根据权限配置指定门禁设备集异步快捷下发
这种场景是通过先配置人员门禁权限，然后指定门禁设备异步快捷下发的场景，适用于
少量权限（ 100 设备通道 *1000 人）的下载，接口调用流程如下：
3.1 添加权限配置
通过指定人员数据列表和设备通道对象列表分配人员的门禁权限，对应平台上的权限配
置，接口说明如下
3.2 根据出入权限配置快捷下载
针对上一步配置的人员门禁权限，通过指定门禁设备集实现对应门禁设备上的权限异动
下发，对应平台上的指定设备异动下发权限，接口说明如下：
3.3 查询下载任务进度及权限下载详情
接口调用流程及说明同 2.4 、 2.5 ，不再赘述。
4. 根据权限配置指定门禁设备集异步快捷下发
这种场景是通过先配置人员门禁权限，然后通过创建下载任务，在任务中添加需要下载 权限的设备集合，开始异步下载权限的场景，适用综合大楼、学校、医院等批量权限的下载，
接口调用流程如下：
4.1 添加权限配置
通过指定人员数据列表和设备通道对象列表分配人员的门禁权限，对应平台上的权限配
置，接口说明如下
4.2 创建下载任务_根据出入权限配置下载
该接口用来创建根据设备通道下载的任务类型，接口说明如下：
4.3 添加待下载的设备通道_根据出入权限配置下载
把需要异步下发权限的门禁设备通道添加到下载任务中，接口说明如下：
4.4 开始下载任务、查询下载进度及权限下载详情
接口调用流程及说明同 2.3 、 2.4 、 2.5 ，不再赘述。
四、 常见问题
以下列出几种常见问题：
1. 接口添加的权限配置在平台上看不到，在平台上添加的权限接口里查不到
这个是因为接口中调用的是 acps 组件，平台上用的是 acs 组件，截止 1.3.0 版本， acps
和 acs 还没有做通，所以，两者之间相互查不到对应的权限配置及下载记录等。
2. 通过接口下发人脸，返回下载数量为 0
常见原因包括以下几种：
a) 对应的人员没有下发卡权限，目前设备上还是以卡为中心的默认，下发人脸需要先下发
卡权限 (taskType=1) ，通常 taskType 传 5 就是卡权限和人脸一起下发；
b) 接口在往非人脸设备上下发，人脸只支持下发到人脸设备，经常会有第三方不对设备类
型进行区分，把人脸往门禁控制器上下发。
3. 人脸下发失败
常见原因包括以下几种： a) 平台上录入的人脸照片质量不符合要求，这种情况接口中返回人脸下发失败的原因；
b) Ehome 协议接入的门禁人脸设备，下发人脸的时候， dac 是把人脸照片的图片 url 下发
给设备，由设备主动从 asw 下载图片，如果门禁设备在外网， asw 的多线路没有配置，
或者端口没有映射，会导致门禁设备下载人脸失败；
c) Ehome 协议接入的门禁人脸设备，下发人脸还需要在 pstor 中配置 kms 资源池和 pss 资
源池。
4. 添加权限配置接口返回的 taskId 查询进度无数据返回
添加权限配置接口是异步接口，也就是调用接口后，接口直接返回一个 taskId ，平台内
部在异步增加权限配置，接口返回的 taskId 是用来查询权限配置进度，查询权限配置进度的
接口基线还没有对外开放，需要安装资源包。
