海康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. ****取消事件订阅 **

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