4. Seznam zpráv HTTP API

2N^® Helios HTTP API definuje následující typy zpráv:

Subscribe
SubscribeResponse
CreatePullPoint
CreatePullPointResponse
Renew
RenewResponse
Unsubscribe
UnsubscribeResponse
GetMessages
GetMessagesResponse
Notify

Detailní popis zpráv, jejich parametry a použití jsou popsány v následujícím textu.

Zpráva Subscribe

Požadavek Subscribe slouží k registraci klienta jako odběratele událostí z 2N Helios IP v režimu Subscribe, kdy 2N Helios IP autonomně posílá události v podobě zprávy Notify na HTTP adresu specifikovanou klientem.

Klient musí odeslat požadavek Subscribe na adresu 2N Helios IP: http://helios_ip_address/notification.

2N Helios IP odpovídá na požadavek Subcribe odpovědí SubscribeResponse.

Formát požadavku Subscribe:

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:a="http://www.w3.org/2005/08/addressing"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
  </s:Header>
  <s:Body>
    <wsnt:Subscribe>
      <wsnt:ConsumerReference>
        <a:Address>
          {HTTP_CONSUMER_ADDRESS}
        </a:Address>
      </wsnt:ConsumerReference>
      <wsnt:Filter>
        <wsnt:TopicExpression Dialect= 
            "http://www.2n.cz/2013/TopicExpression/Multiple">
          {EVENTS_LIST}
        </wsnt:TopicExpression>
      </wsnt:Filter>
      <wsnt:InitialTerminationTime>
        {DATETIME_OR_DURATION}
      </wsnt:InitialTerminationTime>
      <wsnt:SubscriptionPolicy>
        <event2n:MaximumNumber>
          {MAX_NUMBER_OF_MSGS_AT_ONCE}
        </event2n:MaximumNumber>
        <event2n:StartRecordId>
          {START_RECORD_ID}
        </event2n:StartRecordId>
        <event2n:StartTimestamp>
          {START_TIMESTAMP}
        </event2n:StartTimestamp>
      </wsnt:SubscriptionPolicy>
    </wsnt:Subscribe>
  </s:Body>
</s:Envelope>

Parametry zprávy

HTTP_CONSUMER_ADDRESS

Adresa, na kterou se budou posílat zprávy Notify obsahující události. Adresa musí být ve formátu HTP URI, např. http://192.168.23.73/notify_server. Parametr je povinný.

DATETIME_OR_DURATION

Udává dobu, na kterou se chce klient registrovat. Po vypršení této doby je registrace na straně 2N Helios IP automaticky zrušena. Registraci lze před jejím vypršením prodloužit pomocí požadavku Renew. Pro specifikaci doby trvání registrace je možné použít absolutní čas (DateTime) nebo relativní dobu trvání (Duration), viz kap. Formát vybraných parametrů. Parametr je povinný.

EVENTS_LIST

Seznam typů vyžadovaných událostí. Jednotlivé typy událostí jsou v seznamu odděleny čárkou, např. event2n:KeyPressed, event2n:CardEntered. Parametr je nepovinný. V případě, že není uveden, klient bude dostávat všechny typy událostí.

MAX_NUMBER_OF_MSGS_AT_ONCE

Maximální počet událostí, které mohou být odeslány v rámci jedné zprávy Notify. Parametr je nepovinný. V případě, že není uveden, v jedné zprávě Notify bude odesláno maximálně 10 událostí.

START_TIMESTAMP

Udává datum a čas nejstarší událostí, kterou chce klient obdržet v rámci zpráv Notify jako první. Parametr je nepovinný. V případě, že není uveden, klient obdrží všechny události uložené v logu.

START_RECORD_ID

Udává RecordId události v logu, kterou chce klient obdržet v rámci zpráv Notify jako první. Parametr je nepovinný. V případě, že není uveden, klient obdrží všechny události uložené v logu.

Zpráva SubscribeResponse

Zpráva SubscribeResponse slouží jako odpověď na požadavek Subscribe. Pomocí této zprávy 2N Helios IP informuje o provedení registrace klienta k odběru událostí.

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeResponse
    </wsa5:Action>
  <s:Header>
  <s:Body>
    <wsnt:SubscribeResponse>
      <wsnt:SubscriptionReference>
        <wsa5:Address>
          {NOTIFICATIONS_PRODUCER_ADDRESS}
        </wsa5:Address>
        <wsa5:ReferenceParameters>
          <event2n:SubscriptionId>
            {SUBSCRIPTION_ID}
          </event2n:SubscriptionId>
        </wsa5:ReferenceParameters>
      </wsnt:SubscriptionReference>
      <wsnt:CurrentTime>
        {CURRENT_TIME}
      </wsnt:CurrentTime>
      <wsnt:TerminationTime>
        {EXPIRE_TIME}
      </wsnt:TerminationTime>
    </wsnt:SubscribeResponse>
  </s:Body>
</s:Envelope>

Parametry zprávy

NOTIFICATIONS_PRODUCER_ADDRESS

Adresa, kterou lze použít pro následující komunikaci s 2N Helios IP týkající se této registrace (tj. cílová adresa pro požadavky Unsubscribe a Renew). V současné implementaci je tato adresa vždy http://helios_ip_address/notification.

SUBSCRIPTION_ID

Jednoznačná identifikace registrace (subscription), kterou lze použít pro následující komunikaci s 2N Helios IP (v požadavcích Renew, Unsubscribe). Klient by měl zacházet s tímto Id jako s obecným textem.

CURRENT_TIME

Aktuální datum a čas z pohledu 2N Helios IP v okamžiku provedení registrace. Formát viz kap. Formát vybraných parametrů.

EXPIRE_TIME

Datum a čas automatického ukončení registrace. Klient může prodloužit registraci před jejím vypršením pomocí požadavku Renew. Formát viz kap. Formát vybraných parametrů.

Zpráva CreatePullPoint

Požadavek CreatePullPoint slouží k registraci klienta jako odběratele událostí z 2N Helios IP v režimu PullPoint, kdy klient aktivně vyčítá události z logu pomocí požadavku GetMessages..

Klient musí odeslat požadavek CreatePullPoint na adresu 2N Helios IP:

http://helios_ip_address/notification

2N Helios IP odpovídá na požadavek CreatePullPoint odpovědí CreatePullPointResponse.

Formát požadavku CreatePullPoint:

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
  </s:Header>
  <s:Body>
    <wsnt:CreatePullPoint>
      <wsnt:Filter>
        <wsnt:TopicExpression Dialect=
           "http://www.2n.cz/2013/TopicExpression/Multiple">
          {EVENTS_LIST}
        </wsnt:TopicExpression>
      </wsnt:Filter>      
      <wsnt:InitialTerminationTime>
        {DATETIME_OR_DURATION}
      </wsnt:InitialTerminationTime>
      <wsnt:SubscriptionPolicy>
        <event2n:StartRecordId>
          {START_RECORD_ID}
        </event2n:StartRecordId>
        <event2n:StartTimestamp>
          {START_TIMESTAMP}
        </event2n:StartTimestamp>
      </wsnt:SubscriptionPolicy>
    </wsnt:CreatePullPoint>
  </s:Body>
</s:Envelope>

Zpráva CreatePullPointResponse

Zpráva CreatePullPointResponse slouží jako odpověď na požadavek CreatePullPoint. Pomocí této odpovědi 2N Helios IP informuje o provedení registrace klienta k odběru událostí.

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa5="http://www.w3.org/2005/08/addressing" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" 
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <wsa5:Action>//http://docs.oasis-open.org/wsn/bw-2/CreatePullPoint/CreatePullPointResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:CreatePullPointResponse>
      <wsnt:SubscriptionReference>
        <wsa5:Address>
          {NOTIFICATIONS_PRODUCER_ADDRESS}
        </wsa5:Address>
        <wsa5:ReferenceParameters>
          <event2n:SubscriptionId>
            {SUBSCRIPTION_ID}
          </event2n:SubscriptionId>
        </wsa5:ReferenceParameters>
      </wsnt:SubscriptionReference>
      <wsnt:CurrentTime>
        {CURRENT_TIME}
      </wsnt:CurrentTime>
      <wsnt:TerminationTime>
        {EXPIRE_TIME}
      </wsnt:TerminationTime>
    </wsnt:CreatePullPointResponse>
  </s:Body>
</s:Envelope>

Parametry zprávy

NOTIFICATIONS_PRODUCER_ADDRESS

Adresa, kterou lze použít pro následující komunikaci s 2N Helios IP týkající se této registrace (tj. cílová adresa pro požadavky Unsubscribe a Renew, GetMessages). V současné implementaci je tato adresa vždy http://helios_ip_address/notification.

SUBSCRIPTION_ID

Jednoznačná identifikace registrace (subscription), kterou je nutno použít pro následující komunikaci s 2N Helios IP (v požadavcích Renew, Unsubscribe, GetMessages). Klient by měl zacházet s tímto Id jako s obecným textem.

CURRENT_TIME

Aktuální datum a čas z pohledu 2N Helios IP v okamžiku provedení registrace. Formát viz kap. Formát vybraných parametrů.

EXPIRE_TIME

Datum a čas automatického ukončení registrace. Klient může prodloužit registraci před jejím vypršením pomocí požadavku Renew. Formát viz kap. Formát vybraných parametrů.

Zpráva Renew

Požadavek Renew slouží k prodloužení registrace odběru událostí ze strany klienta. Klient odesílá tento požadavek na adresu uvedenou v odpovědi SubscribeResponse. 2N Helios IP odpovídá zprávou RenewResponse.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <event2n:SubscriptionId a:IsReferenceParameter="true">
      {SUBSCRIPTION_ID}
    </event2n:SubscriptionId>
  </s:Header>
  <s:Body>
    <wsnt:Renew>
      <wsnt:TerminationTime>
        {DATETIME_OR_DURATION}
      </wsnt:TerminationTime>
    </wsnt:Renew>
  </s:Body>
</s:Envelope>

Parametry zprávy

SUBSCRIPTION_ID

Jednoznačná identifikace registrace (subscription), získaná z odpovědi SubscriptionResponse. Parametr je povinný.

DATETIME_OR_DURATION

Udává dobu, na kterou se chce klient prodloužit registraci. Po vypršení této doby je registrace na straně 2N Helios IP automaticky zrušena. Registraci lze před jejím vypršením prodloužit pomocí dalšího požadavku Renew. Pro specifikaci doby trvání registrace je možné použít absolutní čas (DateTime) nebo relativní dobu trvání (Duration), viz kap. Formát vybraných parametrů. Parametr je povinný.

Zpráva RenewResponse

Zpráva RenewResponse slouží jako odpověď na požadavek Renew. Pomocí této zprávy 2N Helios IP informuje o prodloužení registrace klienta k odběru událostí.

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/SubscriptionManager/RenewResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:RenewResponse>
      <wsnt:TerminationTime>
        {CURRENT_TIME}
      </wsnt:TerminationTime>
      <wsnt:CurrentTime>
        {EXPIRE_TIME}
      </wsnt:CurrentTime>
    </wsnt:RenewResponse>
  </s:Body>
</s:Envelope>

Parametry zprávy

CURRENT_TIME

Aktuální datum a čas z pohledu 2N Helios IP v okamžiku provedení registrace. Formát parametru viz kap. Formát vybraných parametrů.

EXPIRE_TIME

Datum a čas automatického ukončení registrace. Klient může prodloužit registraci před jejím vypršením pomocí požadavku Renew. Formát parametru viz kap. Formát vybraných parametrů.

Zpráva Unsubscribe

Požadavek Unsubscribe slouží k ukončení registrace odběru událostí ze strany klienta. Klient odesílá tento požadavek na adresu uvedenou v odpovědi SubscribeResponse. 2N Helios IP odpovídá na zprávou UnsubscribeResponse.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <event2n:SubscriptionId a:IsReferenceParameter="true">
      {SUBSCRIPTION_ID}
    </event2n:SubscriptionId>
  </s:Header>
  <s:Body>
    <wsnt:Unsubscribe>
    </wsnt:Unsubscribe>
  </s:Body>
</s:Envelope>

Parametry zprávy

SUBSCRIPTION_ID

Jednoznačná identifikace registrace (subscription) získaná z odpovědi SubscriptionResponse. Parametr je povinný.

Zpráva UnsubscribeResponse

Zpráva UnsubscribeResponse slouží jako odpověď na požadavek Unsubscibe. Pomocí této zprávy 2N Helios IP potvrzuje klientu ukončení registrace.

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope
    xmlns:s="http://www.w3.org/2003/05/soap-envelope"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/SubscriptionManager/UnsubscribeResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:UnsubscribeResponse>
    </wsnt:UnsubscribeResponse>
  </s:Body>
</s:Envelope>

Zpráva GetMessages

Požadavek GetMessages slouží k aktivnímu vyčítání událostí z 2N Helios IP klientem. Klient odesílá tento požadavek na adresu uvedenou v odpovědi CreatePullPointResponse. 2N Helios IP odpovídá zprávou GetMessageResponse.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" 
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <event2n:SubscriptionId a:IsReferenceParameter="true">
      {SUBSCRIPTION_ID}
    </event2n:SubscriptionId>
  </s:Header>
  <s:Body>
    <wsnt:GetMessages>
      <wsnt:MaximumNumber>
        {MAXIMUM_MSGS_IN_RESPONSE}
      </wsnt:MaximumNumber>
      <wsnt:Timeout>
        {WAIT_TIMEOUT}
      </wsnt:Timeout>
    </wsnt:GetMessages>
  </s:Body>
</s:Envelope>

Parametry zprávy

SUBSCRIPTION_ID

Jednoznačná identifikace registrace (subscription), získaná z odpovědi SubscriptionResponse. Parametr je povinný.

MAXIMUM_MSGS_IN_RESPONSE

Maximální počet událostí, které mohou být odeslány v rámci odpovědi GetMessagesResponse. Parametr je nepovinný. V případě, že není uveden, v jedné odpovědi GetMessagesResponse bude odesláno maximálně 10 událostí.

WAIT_TIMEOUT

Zpoždění odeslání odpovědi. Hodnota může být v rozmezí 0–90 (nastavuje se v sekundách). Pokud je hodnota větší než 90, tak se použije 90. Pokud není parametr nastaven, tak se zpoždění neuplatní. Parametr je volitelný.

Zpráva GetMessagesResponse

Zpráva GetMessagesResponse slouží jako odpověď na požadavek GetMessages.

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:topic2n="http://www.2n.cz/2013/event/topics" 
    xmlns:wsa5="http://www.w3.org/2005/08/addressing" 
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2" 
    xmlns:event2n="http://www.2n.cz/2013/event">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/PullPoint/GetMessagesResponse
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:GetMessagesResponse>
       {EVENT_LIST}
    </wsnt:GetMessagesResponse>
  </s:Body>
</s:Envelope>

Parametry zprávy

EVENT_LIST

Seznam událostí – viz kapitola Logované události. Seznam událostí může být prázdný. Maximální počet událostí odeslaných najednou lze specifikovat při registraci (v požadavku CreatePullPoint) nebo přímo v požadavku GetMessages.

Zpráva Notify

Zpráva Notify slouží k oznámení vzniku nové události v režimu odběru událostí typu Subscription. 2N Helios IP posílá zprávu Notify na adresu uvedenou při registraci pomocí požadavku Subscribe. Zpráva Notify musí být potvrzena druhou druhou stranou zprávou OK, jinak se další zpráva Notify pošle po vypršení časového limitu cca 5 s.

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope 
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:topic2n="http://www.2n.cz/2013/event/topics" 
    xmlns:event2n="http://www.2n.cz/2013/event"
    xmlns:wsa5="http://www.w3.org/2005/08/addressing"
    xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2">
  <s:Header>
    <wsa5:Action s:mustUnderstand="true">
      http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify
    </wsa5:Action>
  </s:Header>
  <s:Body>
    <wsnt:Notify>
       {EVENT_LIST}
    </wsnt:Notify>
  </s:Body>
</s:Envelope>

Parametry zprávy

EVENT_LIST

Seznam událostí – viz kapitola Logované události. Zpráva obsahuje vždy alespoň jednu událost. Maximální počet událostí lze specifikovat při registraci (v požadavku Subscribe).