SOAP-Interface

4.9 SOAP-Interface

Version 1.1

Die gesamte Kommunikation zwischen Clients und Servern als auch zwischen den Servern untereinander erfolgt über das Simple Object Access Protocol (SOAP) (http://www.w3.org/TR/SOAP/).
Viele der primär intern genutzten Methoden erlauben auch, Informationen über das System und aus den Datenbanken abzurufen.
Einige dieser Methoden werden hier vorgestellt.

4.9.1 Vorbemerkungen

Alle Methoden werden in der Reihenfolge 'Request', gefolgt von den Antwortdaten 'Response' und 'Fault' vorgestellt.

'Request' wird vom Web-Client an den Server übermittelt.
Erwartet ein Request Parameter, so werden diese immer in der Form '$Parametername' angegeben.
'Response' beschreibt stets exemplarisch das Ergebnis, falls kein Fehler aufgetreten ist.
Enthält eine Response Werte, die als Parameter im Request mitgegeben wurden, so werden sie genauso wie im Request - also in der Form $Parametername - notiert.
Enthält eine Response Inhalte und Attribute, deren Inhalt variiert, so wird nur die Bedeutung in der Form [Bedeutung] angegeben.
'Fault' beschreibt die Fehlermeldungen, falls 'Request' nicht bearbeitet werden konnte.

Grundsätzlich beginnen alle Dokumente mit dem XML-Prolog <?xml version="1.0" encoding="UTF-8"?>.
Der SOAP-Envelope hat immer die Form

<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsi="http://www.w3.org/2001/XMLSchema">

...
</SOAP-ENV:Envelope>

Da die angegebenen URI's standard sind, können sie auch weggelassen werden.

4.9.1.1 Zugangsdaten

Im SOAP-Header erscheint immer eine Sequenz

<check xsi:type="xsd:string">...</check>

zur Zugangsicherung.

Der Inhalt des Elements check wird hier nicht weiter dokumentiert.

4.9.1.2 Zeitangaben

Alle Zeitangaben (4.9.1.2) in den Austauschdokumenten sind vom Typ xsi:type="xsd:dateTime" und werden entsprechend ISO 8601 formuliert, d.h. in der Form CCYY-MM-DDTHH:MM:SS.

4.9.2 QryEvt: Anfordern von Ereignisstammdaten und -protokoll

Die Methode liefert zu einem gegebenen Ereignis die wesentlichen Deskriptoren des Ereignisses und das bislang zum Ereignis angefallenene Leitstellenprotokoll (2.4).

4.9.2.1 QryEvt-Request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>

<check xsi:type="xsd:string">$Zugangsdaten (4.9.1.1)</check>
</SOAP-ENV:Header>
<SOAP-ENV:Body>

<QryEvt>

<eventId xsi:type="xsd:positiveInteger">$Ereignisnummer</eventId>
</QryEvt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.9.2.2 QryEvt-Response:

Das Ergebnis setzt sich zusammen aus einem EVENT-Element, dessen Attribute die Stammdaten beschreiben, sowie geschachtelten PROTOCOLITEM-Elementen, deren Attribute die festen Parameter jedes Protokolleintrags angeben.
Innerhalb der PROTOCOLITEM-Elemente findet sich PCDATA, das den Protokolltext beschreibt. Der Protokolltext besitzt als Formatierung maximal Zeilenumbrüche. Diese werden durch %0D repäsentiert.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>

<EVENT eventId="$Ereignisnummer" eventObjAlertID="[Meldernummer]" eventStreet="[Straße Hausnummer]" eventTown="[Ort]"
eventType="[Ereignisart]" eventSign="[Ereigniskennzeichen]" eventCreation="[Zeitpunkt Ereigniserzeugung]"
eventAccess="Zeitpunkt Stand">

<PROTOCOLITEM eventId="$Ereignisnummer" eventType="[Ereignisart]" time="[Zeitpunkt Protokolleintrag]" userid="[Benutzerkennung]">

[Protokolltext, Zeilenumbrüche werden UUEncoded durch %0D]
</PROTOCOLITEM>
<PROTOCOLITEM ...>
...
</PROTOCOLITEM>

</EVENT>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.9.2.3 QryEvt-Fault:

Einzige Fehlerbedingung ist die Angabe einer falschen Ereignisnummer:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

<SOAP-ENV:faultcode>Client</SOAP-ENV:faultcode>
<SOAP-ENV:faultstring>UNKNOWN EVENT</SOAP-ENV:faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.9.3 QryEvtList: Abfragen von Ereignislisten

Die Methode liefert für einen vorgegebenen Zeitraum alle Ereignisse (2.2), die in diesem Zeitraum eröffnet wurden:

4.9.3.1 QryEvtList-Request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema">

<SOAP-ENV:Header>

<check xsi:type="xsd:string">$Zugangsdaten (4.9.1.1)</check>
</SOAP-ENV:Header>
<SOAP-ENV:Body>

<QryEvtList>

<from xsi:type="xsd:dateTime">$unterer Zeitpunkt</from>
<until xsi:type="xsd:dateTime">$oberer Zeitpunkt</until>
</QryEvtList>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.9.3.2 QryEvtList-Response:

Die im Zeitraum aufgefundenen Ereignisse (2.2) werden als Sequenz von leeren EVENT-Elementen zurückgegeben, deren Attribute die Ereibnisinformationen beschreiben.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope"
xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema">

<SOAP-ENV:Body>
<EVENT eventId="[Ereignisnummer]" eventObjAlertID="[Meldernummer]" eventStreet="[Strasse Hausnummer]"
eventTown="[Ort]" eventType="[Ereignisart]' eventSign="[Ereigniskennzeichen]" eventCreation="[Zeitpunkt Ereigniseröffnung]"
eventAccess="[Zeitpunt Stand]">

...
<EVENT ...>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.9.3.3 QryEvtList-Fault:

Fehlerbedingungen sind fehlende oder ungültige Zeitangaben (4.9.1.2) der Untergrenze <from>...</from> bzw. Obergrenze <until>...</until>
Ist die Untergrenze größer als die Obergrenze, so führt dies zu keinem Fehler, sondern zu einem leeren Ergebnis.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV="http://www.w3.org/2001/06/soap-envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema">

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

<SOAP-ENV:faultcode>Client</SOAP-ENV:faultcode>
<SOAP-ENV:faultstring>ERROR IN from-PARA</SOAP-ENV:faultstring>
<SOAP-ENV:faultstring>ERROR IN until-PARA</SOAP-ENV:faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>