从零开始精通Onvif之事件处理

💡 如果想阅读最新的文章，或者有技术问题需要交流和沟通，可搜索并关注微信公众号“希望睿智”。

概述

        Onvif的事件处理允许IPC等摄像头主动向客户端（比如：NVR、VMS、平台服务等）推送事件通知，比如：运动检测、音频侦测、视频丢失等报警事件。这种模式打破了传统的轮询查询方式，显著降低了延迟，提高了事件响应效率。这些事件的有效处理，不仅关乎系统的安全性，也直接影响到用户的使用体验。

工作机制

        Onvif的事件处理基于订阅-发布模型，通常涉及以下四个重要步骤。

        1、创建订阅。客户端首先向设备发送CreatePullPointSubscription消息，请求订阅特定事件类型。订阅请求中需明确事件过滤条件、期望的事件类型以及回调地址（也就是客户端接收通知的URL）。

        2、确认与配置。设备收到订阅请求后，会验证请求的有效性。同时，确认订阅并返回Subscription ID，此ID用于后续的事件通知关联及订阅管理。

        3、事件触发与通知。一旦设备检测到符合订阅条件的事件，它会构造包含事件详情的Notify消息，并通过HTTP POST请求发送到客户端的回调地址。通知中不仅有事件数据，还包括Subscription ID，确保客户端能识别事件来源。

        4、重订阅与取消订阅。为了维持事件订阅的有效性，客户端需定期发送Renew消息更新订阅。若不再需要某事件通知，可通过发送Unsubscribe消息取消订阅。

创建订阅

        创建订阅是事件处理的第一步，客户端通过发送CreatePullPointSubscription请求来告诉设备它想订阅哪些事件，并提供一个回调地址，以便设备在事件发生时发送通知。

        可以参考下面的示例报文来进行理解，其中的一些关键节点和属性描述如下。

        <tev:CreatePullPointSubscription>：标记着请求的目的，即创建一个基于Pull Point模型的事件订阅。Pull Point模型允许客户端按需（而非实时推送）从服务端拉取事件信息，有助于管理和控制网络流量。

        <tev:InitialTerminationTime>：指定订阅的有效事件，这里是P1D，代表持续1天。也就是说，如果不进行续订，订阅将在一天后自动失效。

        <tev:Filter>：包含了订阅的过滤条件，允许客户端指定感兴趣的事件类型。

        <tev:SubscriptionPolicy>：定义了订阅策略，进一步细化过滤条件。

        <wstop:TopicSet>：包含了订阅的事件主题集合。

        <wstop:Topic>：定义了具体的事件主题，这里使用的方言（Dialect）指向ONVIF的Concrete Set规范，MotionAlarm表示订阅的是移动侦测报警事件。这意味着，客户端只关心与移动检测相关的事件通知。

        <tev:ConsumerReference>：提供了接收事件通知的消费者（客户端）的引用信息。

        <wsa:Address>：表示回调地址。当所订阅的事件被触发时，设备将通过HTTP POST请求向这个地址发送事件通知。开发者需要在此地址部署服务，用于接收并处理这些通知。

  <soapenv:Body>
    <tev:CreatePullPointSubscription>
      <tev:InitialTerminationTime>P1D</tev:InitialTerminationTime>
      <tev:Filter>
        <tev:SubscriptionPolicy>
          <wstop:TopicSet>
            <wstop:Topic Dialect="http://www.onvif.org/ver10/subscription/wsnt/topicExpression/ConcreteSet">
              MotionAlarm
            </wstop:Topic>
          </wstop:TopicSet>
          <!-- 其他过滤条件可根据需要添加 -->
        </tev:SubscriptionPolicy>
      </tev:Filter>
      <tev:ConsumerReference>
        <wsa:Address>http://your-callback-url.com/onvif-event-handler</wsa:Address>
      </tev:ConsumerReference>
    </tev:CreatePullPointSubscription>
  </soapenv:Body>

确认与配置

        当客户端发送一个CreatePullPointSubscription请求后，设备将会响应一个确认订阅成功的SOAP报文，其中包含订阅的详细信息，比如：订阅标识符（Subscription ID）、终止时间等。

        在下面的示例报文中，一些关键节点和属性描述如下。

        <tev:SubscriptionReference>：包含了订阅的唯一标识符<wsa:Address>，客户端可以用它来续订、取消订阅，或识别通知消息中的订阅来源。

        <wsnt:TerminationTime>：表示订阅的有效截止时间，客户端应在该时间之前发送续订请求以延长订阅。

  <soapenv:Body>
    <tev:CreatePullPointSubscriptionResponse>
      <tev:SubscriptionReference>
        <wsa:Address>urn:uuid:6f9d210b-2c82-78b2-b8b5-1690da02ee68aba2a5</wsa:Address>
        <wsa:ReferenceParameters>
          <!-- 可选的参考参数 -->
        </wsa:ReferenceParameters>
      </tev:SubscriptionReference>
      <tev:CurrentTime>2024-06-09T16:30:00Z</tev:CurrentTime>
      <wsnt:TerminationTime>2024-06-15T16:30:00Z</wsnt:TerminationTime>
    </tev:CreatePullPointSubscriptionResponse>
  </soapenv:Body>

事件触发与通知

        设备在检测到订阅的事件发生时，会向客户端的回调地址发送Notify消息。

        在下面的示例报文中，一些关键节点和属性描述如下。

        <wsnt:SubscriptionReference>：包含了订阅的唯一标识符，用于识别该通知属于哪个订阅。

        <wsnt:Topic>：表示事件的主题，这里是移动侦测事件。

        <tt:MotionDetectionEvent>：实际的移动侦测事件数据，可能包含事件状态（比如：激活状态）、检测区域（比如：多边形坐标）等信息。

  <soapenv:Body>
    <wsnt:Notify>
      <wsnt:SubscriptionReference>
        <wsa:Address>urn:uuid:subscription-uuid</wsa:Address>
      </wsnt:SubscriptionReference>
      <wsnt:Topic>http://www.onvif.org/ver10/events/wsdl/MotionAlarm</wsnt:Topic>
      <wsnt:ProducerReference>
        <wsa:Address>http://device-ip/onvif/services</wsa:Address>
      </wsnt:ProducerReference>
      <wsnt:Data>
        <!-- 事件的具体数据，根据事件类型不同而变化 -->
          <tt:MotionDetectionEvent
            xmlns:tt="http://www.onvif.org/ver10/schema">
            <tt:Source>
              <tt:SimpleItem Name="DeviceToken">device-uuid</tt:SimpleItem>
            </tt:Source>
            <tt:Properties>
              <tt:SimpleItem Name="EventState">active</tt:SimpleItem>
              <tt:SimpleItem Name="DetectionRegion">
                <tt:Polygon>
                  <tt:Point X="0.3" Y="0.4"/>
                  <tt:Point X="0.6" Y="0.4"/>
                  <tt:Point X="0.6" Y="0.8"/>
                  <tt:Point X="0.3" Y="0.8"/>
                </tt:Polygon>
              </tt:SimpleItem>
              <!-- 其他可能的属性，如：时间戳、图像等 -->
            </tt:Properties>
          </tt:MotionDetectionEvent>
      </wsnt:Data>
    </wsnt:Notify>
  </soapenv:Body>

重订阅与取消订阅

        为保持订阅有效，客户端需要在订阅到期前发送Renew续订请求。如果客户端不再需要接收事件通知，则应发送Unsubscribe取消订阅请求。

        在下面的示例报文中，<wsa:Address>为Subscription ID，可从CreatePullPointSubscription的响应中获取。

  <soapenv:Body>
    <wsnt:Renew>
      <!-- 新的订阅有效时间 -->
      <wsnt:TerminationTime>P1D</wsnt:TerminationTime>
      <wsnt:SubscriptionReference>
        <!-- Subscription ID -->
        <wsa:Address>urn:uuid:subscription-uuid</wsa:Address>
      </wsnt:SubscriptionReference>
    </wsnt:Renew>
  </soapenv:Body>
  
  <soapenv:Body>
    <wsnt:Unsubscribe>
      <wsnt:SubscriptionReference>
        <!-- Subscription ID -->
        <wsa:Address>urn:uuid:subscription-uuid</wsa:Address>
      </wsnt:SubscriptionReference>
    </wsnt:Unsubscribe>
  </soapenv:Body>