Zum Hauptinhalt springen

IF_046 – Leistungsdaten empfangen und für die weitere Verarbeitung bereitstellen (Push-Schnittstelle)

Über die Push-Schnittstelle hat der Redaktionssystem-Betreiber die Möglichkeit, die im Redaktionssystem vorgenommenen Änderungen - einzeln - direkt an das PVOG zu senden. Der Sammlerdienst gibt diese Änderungen dann ad hoc an Bereitstelldienst und Suchdienst weiter.

Die Verarbeitung der Daten, die an die Push-Schnittstelle geliefert werden, erfolgt synchron. Dies ermöglicht direktes Feedback an die Redaktionssysteme im Fehlerfall. Der gesamte Ablauf findet innerhalb des eingehenden Aufrufs statt. Bei einem Virenfund oder bei einer negativen Validierung werden Fehlercodes an das aufrufende Redaktionssystem zurückgegeben.

API-Beschreibung der Push-Schnittstelle​

Die Push-Nachrichten werden über eine REST-API als POST-Request an das PVOG übermittelt. Die Verwaltungsobjekte müssen in Form einer XZuFi 2.3.1 TransferOperation050502 (öffnet in neuem Tab) im HTTP-Body übergeben werden. Auf der Seite Nachrichtenformat ist die Datenstruktur beschrieben.

FeldnameBereichErläuterungDatentypWertePflichtfeld
X-PVOG-SENDERHTTPHeaderName des Redaktionssystems muss mit dem Element sender im Nachrichtenkopf übereinstimmenStringja
X-PVOGSCHEMEAGENCYIDHTTPHeaderSchemeAgencyId des RedaktionssystemsStringja
X-PVOGNACHRICHTUUIDHTTPHeaderIdentifikator der Nachricht, muss mit dem Element nachrichtUUID im Nachrichtenkopf übereinstimmen.StringUUIDFormat, 36 Zeichenja
HTTPBodyXZuFi Payload in Form einer Transfernachricht transfer.operation.050502 übertragen.Stringja

Der Sammlerdienst quittiert die Anfragen mit folgenden HTTP-Return-Codes:

Return-CodeErläuterung
200 (OK)Die Nachricht wurde erfolgreich an den Sammlerdienst übertragen und verarbeitet.
400 (Bad Request)Die Nachricht kann nicht verarbeitet werden, da Informationen fehlen oder falsch sind.
401 (Unauthorized)Die Anfrage wurde wegen fehlender Authentifizierung abgelehnt.
403 (Forbidden)Die Anfrage wurde wegen fehlender Berechtigung abgelehnt.
404 (Not-Found)Die verwendete URL ist falsch.
422 (Unprocessable Entity)Die Nachricht konnte nicht erfolgreich vom Sammlerdienst verarbeitet werden. Dies gilt insbesondere bei einem Virenfund oder wenn die übertragene XZuFi-Nachricht syntaktisch oder semantisch nicht valide ist.
423 (Locked)
  1. Der Return-Code wird gesendet, wenn eine Nachricht mit gleicher nachrichtUUID sich noch im Sammlerdienst in Verarbeitung befindet. Dieser Fall kann auftreten, falls es zu einem Request-Abbruch zum Beispiel durch einen Read-Timeout beim Absender der Nachricht kommt und im Weiteren durch einen Retry, dieselbe Nachricht erneut gesendet wird.
  2. Das betreffende Redaktionssystem im Sammlerdienst ist gerade durch einen Importvorgang (Pull-Verfahren) gesperrt.
In beiden Fällen sollte versucht werden, dieselbe Nachricht nach einer Latenzzeit erneut an den Sammlerdienst zu übertragen.

Bei einer erfolgreichen Anfrage wird ein Protokoll an den Aufrufer zurückgegeben, das ggf. Warnungen und Hinweise des Fachvalidators enthält.

{
    "nachrichtUUID": {
        "type": "string",
        "description": "UUID der Push-Nachricht.",
        "format": "uuid"
    },
    "schemeAgencyId": {
        "type": "string",
        "description": "Die SchemeAgencyId der Push-Nachricht."
    },
    "meldungen": {
        "type": "array",
        "description": "Liste der Meldungen des Validators",
        "items": {
            "type": "object",
            "properties": {
                "nachricht": {
                    "description": "Validatormeldung",
                    "type": "string"
                },
                "status": {
                    "description": "Status der Meldung (WARNING, HINT)",
                    "type": "string"
                },
                "validatorId": {
                    "description": "Die Id des Validators",
                    "type": "string"
                },
                "anzahl": {
                    "description": "Anzahl dieser Art von Meldungen",
                    "type": "int32"
                }
            }
        }
    }
}

Arbeitsweise bei Timeouts​

Wenn die Nachrichtenverarbeitung im Sammlerdienst längere Zeit in Anspruch nimmt, kann es Client-seitig zu (Read-)Timeouts kommen, wenn der Sammlerdienst innerhalb einer gewissen Zeitspanne nicht antwortet (zumeist 30 Sekunden). Der Client sollte dann versuchen, dieselbe Nachricht (mit identisches nachrichtUUID) erneut zu versenden (ggf. auch mehrfach). Ist der Sammlerdienst weiterhin mit der Verarbeitung dieser Nachricht beschäftigt, antwortet der Dienst mit dem HTTP-Code 423 (Locked). Wurde die Nachricht verarbeitet, antwortet der Sammlerdienst entweder mit dem HTTP-Code 200 (OK) oder mit HTTP-Code 422 (Unprocessable Entity) im Fehlerfall.

Datenkonsistenz​

Beim Versenden von Push-Nachrichten müssen folgende Regeln eingehalten werden, da es ansonsten zu Inkonsistenzen im Datenbestand kommen kann:

  1. Die Verwaltungsobjekte Leistung, Spezialisierung, Onlinedienst und Organisationseinheit müssen auf oberster Ebene in der Schreib- oder Lösch-Operation stehen. Die Zuständigkeiten werden, wie auch im Pull-Verfahren, unterhalb der Onlinedienste und Organisationseinheiten geschachtelt übertragen.
  2. Organisationseinheiten und Onlinedienste können nur angelegt werden, wenn die entsprechende Leistung bereits existiert.
  3. Beim Löschen von Organisationseinheiten und Onlinediensten werden alle referenziertem Zuständigkeiten ebenfalls gelöscht.
  4. Spezialisierungen können nur angelegt werden, wenn die entsprechende Leistung bereits existiert.
  5. Leistungen können nur gelöscht werden, wenn zuvor alle referenzierten Spezialisierungen gelöschten wurden. Ein implizites Löschen der Spezialisierungen erfolgt nicht. Falls Zuständigkeiten auf die Leistung verweisen, darf die Leistung ebenfalls nicht gelöscht werden.

Eine Nichtbeachtung dieser Regeln führt zur Ablehnung der gesamten Push-Nachricht mit allen Verwaltungsobjekten. Voneinander abhängige Verwaltungsobjekte sind idealerweise in einer Push- Nachricht zu versenden.

Sicherheit​

Der Zugriff auf die Push-Schnittstelle ist nur für berechtigte Nutzer bzw Clients möglich. Die Berechtigungsprüfung erfolgt auf Basis eines OpenID Connect Access Tokens, das der Client beim Aufruf der Schnittstelle mitliefern muss. Detaillierte Informationen bzgl. des Anmeldeverfahrens sind in dem Dokument PVOG-Berechtigungsmanagementkonzept beschrieben.

Beispiele​

Anlegen einer Leistung mit Spezialisierung:

<?xml version="1.0" encoding="UTF-8"?>

<xzufi:transfer.operation.050502
 produktbezeichnung=""
 produkthersteller=""
 xzufiVersion="2.3.1"
 xmlns:xzufi="http://xoev.de/schemata/xzufi/2_3_1"
 xmlns:gml="http://www.opengis.net/gml/3.2"
 xmlns:xlink="http://www.w3.org/1999/xlink">

    <xzufi:nachrichtenkopf>
        <xzufi:nachrichtUUID>a9b91de0-13ae-11ea-af84-8dbfdac30fbb</xzufi:nachrichtUUID>
        <xzufi:erstelltDatumZeit>2024-11-30T21:18:43</xzufi:erstelltDatumZeit>
        <xzufi:empfaenger>Portalverbund Sammlerdienst</xzufi:empfaenger>
        <xzufi:sender>HamburgService Informationssystem (HaSI)</xzufi:sender>
    </xzufi:nachrichtenkopf>

    <xzufi:schreibe>
        <xzufi:leistung>
            <xzufi:id schemeAgencyID="S100002">S1000020010000002011</xzufi:id>
            <xzufi:referenzLeistungsschluessel schemeAgencyID="L100042" schemeID="OID">99000092111100</xzufi:referenzLeistungsschluessel>
            <xzufi:modulText>
                <xzufi:positionDarstellung>1</xzufi:positionDarstellung>
                <xzufi:inhalt html="true" languageCode="de">Bäume auf öffentlichem Grund (nicht in Parks)</xzufi:inhalt>
                <xzufi:leikaTextmodul listURI="urn:de:xzufi:codeliste:leistungstextmodulleika" listVersionID="20150601">
                    <code>02</code>
                </xzufi:leikaTextmodul>
            </xzufi:modulText>
            ...
            <xzufi:gueltigkeit>
                <xzufi:beginn>2025-04-01</xzufi:beginn>
                <xzufi:ende>2200-01-01</xzufi:ende>
            </xzufi:gueltigkeit>
        </xzufi:leistung>
    </xzufi:schreibe>

    <xzufi:schreibe>
        <xzufi:spezialisierung>
            <xzufi:leistungID schemeAgencyID="S100002">S1000020010000002011</xzufi:leistungID>
            <xzufi:gebietID schemeAgencyID="S100002">091720134134</xzufi:gebietID>
            <xzufi:gebietID schemeAgencyID="S100002">091720134135</xzufi:gebietID>
            <xzufi:modulSpezialisiert>
                <xzufi:modul xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xzufi:Textmodul">
                    <xzufi:leikaTextmodul listURI="urn:de:xzufi:codeliste:leistungstextmodulleika" listVersionID="20150601">
                        <code>18</code>
                    </xzufi:leikaTextmodul>
                    <xzufi:weiterfuehrenderLink languageCode="de">
                        <xzufi:uri>http://www.freistaat.bayern/dokumente/leistung/353323860204?plz=83317&amp;behoerde=70552145735&amp;gemeinde=064191206669</xzufi:uri>
                        <xzufi:titel>BayernPortal</xzufi:titel>
                        <xzufi:description>Diese Leistung wurde vom BayernPortal bereitgestellt.</xzufi:description>
                    </xzufi:weiterfuehrenderLink>
                </xzufi:modul>
                <xzufi:ersetzung>true</xzufi:ersetzung>
            </xzufi:modulSpezialisiert>
            <xzufi:id schemeAgencyID="S100002">12079-091720134134</xzufi:id>
        </xzufi:spezialisierung>
    </xzufi:schreibe>

</xzufi:transfer.operation.050502>