海康iSC 平台第三方对接实时事件分享

一、 功能描述

      项目上第三方经常会有对接我们的实时事件的需求，例如获取门禁实时事件、停车场过

车记录、视频实时事件、 GPS 信息等等。我们现有实时事件对接方式是通过事件订阅的方式

来实现的，第三方向我们订阅他们需要接收的事件类型，订阅成功后我们把对应的事件类型

推送给第三方，下边详细介绍下对接的具体流程。

二、 流程简介

实时事件对接主要是通过 OpenApi 来实现对接的，在 iSC 平台的 API 列表中提供了“事

件服务”相关的接口来实现第三方对接实时事件，首先还是要搞清楚事件订阅和事件推送是

两件事：

1 、 事件订阅：是第三方向我们订阅他们需要的事件 ( 类型 ) ，就像订阅报纸时要说订阅什么

报纸；

2 、 事件推送：我们根据第三方订阅的事件类型，推送对应类型的事件给第三方。

接下来主要介绍下 API 的事件对接流程：

2.1 事件对接流程简介

1.  第三方调用 API 的事件订阅接口，传入需要订阅的事件类型和他们接收事件的接口地址 (第三方开发的 http 接口用来接收事件)；
2.  订阅成功后，esc 收到对应事件类型的事件，回调第三方的 http 接口地址，以 post 方式把事件报文通过 json 的格式推送给第三方。

三、 接口调用流程

1. 接口调用流程

1.1 事件订阅

      第三方调用 API 的“按事件类型订阅事件”接口向我们平台订阅指定的事件类型 (eventTypes)，并传入第三方用来接收事件的接口地址 (eventDest) 。 注意：不同版本平台间的接口定义略有差异，详情如下：

iSC1.2.0 及之前版本 ( 其他行业平台根据基于的 iSee 架构版本对应 ) 接口定义如下，请求 参数中只有事件类型(eventTypes) 和接收事件的接口地址 (eventDest) ：

 

 

      iSC1.3.0 及之后版本 ( 其他行业平台根据基于的 iSee 架构版本对应 ) 接口定义如下，请求

参数中相比 1.2.0 版本新增了订阅类型 (subType) 和事件等级 (eventLvl) ， subtype(订阅类型 ) ： 0- 订阅原始事件， 1- 联动事件， 2- 原始事件和联动事件，不填使用默认 值 0 。原始事件是事件本身，通常是设备直接触发的事件；联动事件指的是平台收到原始事 件后联动执行的相关动作事件，例如联动抓图、录像等，该参数根据实际传，如果不确定建 议传 2 ； eventLvl (事件等级 ) ： 0- 未配置， 1- 低， 2- 中， 3- 高，此处事件等级是指在事件联动中配置的 等级，指定等级的话只会给第三方推送对应等级的事件，建议默认不传该参数。

 

备注：事件码参考开放平台 - 文档 - 软件产品 - 综合安防管理平台 - 附录 - 附录 D 事件列表下的各子系统的事件码。

1.2 事件回调  

      第三方事件订阅成功后，当 esc 收到对应类型的事件就会回调第三方的接口地址 (eventDest)推送事件 ( 通过 http 请求的方式把事件报文推送给第三方，事件报文以 json 串格 式，放在 Http 请求的 body 中传入 ) 。第三方接收到事件后，按照事件报文格式进行解析， 需要注意的 events 的值是个 List ，里边可能会包含多条事件，解析的时候需要遍历 List 解析所有的事件，否则可能会出现事件漏解析的情况。

 

备注：事件详细报文参考开放平台 - 文档 - 软件产品 - 综合安防管理平台 - 附录 - 附录 D 事件列表下的各子系统的事件报文格式说明。

      另外，联动事件和原始事件的 json 报文格式不一致的，如果两种事件都有订阅的话， 解析的时候需要做下判断，可以通过 ”srcType”:”eventRule” 判断为联动事件。联动事件报文中 的 eventDetails 对应的是触发该联动的原始事件； linkageAcion 对应的是联动动作，例如联动 客户端弹窗预览、弹事件录像、弹事件图片、设备语音对讲、声音提醒、语音提醒事件信息、 弹窗实时画面叠加指定字符、确认开门等；LinkageResult 对应的是联动结果更新，例如联动录像、联动抓图等。

 

四、 常见问题

1. 事件订阅后收不到事件

      第三方经常会反馈事件订阅成功后，接收不到事件，主要排查第三方是否订阅成功和

esc 是否回调第三方接口推送事件了。常见原因包括以下几种：

1. a) 第三方未订阅成功，可以通过调用“按用户查询事件订阅信息”接口查询当前订阅的事件类型及对应的回调地址；
2. b) 第三方订阅成功了，但是没有收到事件，此时需要排查下 esc 所在的服务器到第三方的接口网络是否畅通，简单测试可通过 telnet 接口的 ip 和端口；
3. c) 第三方订阅成功了，第三方的接口地址是通过域名访问的，接收不到事件，如果第三方用的是域名的接口接收事件，就需要确保 esc 所在服务器可以解析第三方的域名(需要配置正常的 DNS 服务器)，否则服务器无法解析第三方的域名就无法调用到对方的接口，简单测试可以通过在服务器上 ping 第三方的域名看是否可以解析出 ip；
4. d) 第三方订阅成功了，并且接口也是通的，还是收不到事件，此时需要排查下第三方订阅事件所用合作方配置的用户名(userId)是否有接收事件的权限；
5. e) iSC1.3.0 及以上版本，第三方订阅事件的时候按照请求参数的默认示例中 subType 传 1，只订阅了联动事件，实际触发的是原始事件，需要第三方取消重新订阅事件，subType传 2，订阅原始事件及联动事件。

2、事件后怎么关联事件源

      第三方收到事件后需要知道是哪个设备上报的事件，第三方收到事件内容中一般都包含了事件源编号(srcIndex) 和事件源类型 (srcType) ，通过事件源类型以及事件源编号即可准确关联到对应的事件源信息。视频事件的事件源通常是监控点，门禁事件的事件源通常是门禁点，停车场过车事件通常会关联到对应的车道和出入口，人脸事件的事件源信息中通常会包括人脸分组和监控点，其他事件以实际事件内容为准。

3. 关于事件联动信息推送

      平台上配置联动抓图，联动录像等信息，第三方希望通过接口获取到这些联动信息，截止 V1.2.0 版本，平台还不支持推送联动信息给第三方，目前只能满足事件自带抓拍信息的推送。

4. 停车场压线事件无抓拍

      停车场的出入场压线事件中的抓拍是异步抓拍的，车辆压线后，先上报了压线事件，同时，抓拍机把抓拍的图片上报到 ASW 进行存储，图片存好后返回图片的存储路径 url ，岗亭客户端收到图片 url 后结合车辆压线事件再上报一次压线事件，此次事件算是异步上报抓拍图片，事件状态(status=5 ，异步图片上传 ) ， esc 的配置中默认只给第三方推送的事件状态为0,1,2 三种类型的事件 (0- 瞬时 1- 开始 2- 停止 ) 。通过修改 esc 配置项中的事件状态，增加上 5后，第三方取消订阅并重新订阅车辆压线事件后，就可以正常推送事件给第三方。

      如果上述配置已经正常，还是收不到抓拍，请检查图片存储相关配置是否正常。

5. 取消事件订阅

      第三方不需要接收部分类型的事件时，可以通过调用“按事件类型取消订阅”接口，传入需要取消的事件类型，取消对应的事件订阅，取消之后就不会再收到对应类型的事件。