IF_008 – Leistungen abrufen

Für externe Dienste aus den Portalen (Bund, Land, Kommune) ist ein Abruf der Leistungsdaten vom Online-Gateway über den Bereitstelldienst sowohl über das Internet als auch über das Netz des Bundes Verbindungsnetz (NdB-VN) möglich. Über diese Schnittstelle können Verwaltungsportale (Zielsysteme) alle Leistungen abrufen, die sich ab einem angegebenen Zeitpunkt geändert haben und zu einer angegebenen Region (definiert durch eine Liste von amtlichen Regionalschlüsseln) zugehörig sind. Überschreitet die Größe der zurückzugebenden Leistungen einen festzulegenden Schwellwert (z. B. 5Mb), dann werden nur die Leistungen mit den ältesten Änderungsdaten zurückgegeben und in der Antwort vermerkt, dass noch weitere Änderungen abzurufen sind.

Endpunkte

Leistungen, Organisationseinheiten und Onlinedienste werden über eine REST API zur Verfügung gestellt. Die Tabelle enthält alle geplanten Endpunkte:

HTTP Methode	URL	Beschreibung
GET	/{version}/verwaltungsobjekte	Überträgt Leistungen, Leistungsspezialisierungen, Organisationseinheiten, Onlinedienste, Formulare und Zuständigkeiten als XZuFi Transfernachrichten. Mehrere Anfragen unter Verwendung des Update-Index können nötig sein, um alle Daten abzurufen. Der Umfang der abzufragenden Leistungsdaten kann durch Angabe von Amtlichen Regionalschlüsseln auf bestimmte Regionen eingeschränkt werden.

Authentifizierung

Verwaltungsportale, die Leistungsdaten abrufen wollen, müssen sich gegenüber dem Bereitstelldienst authentifizieren. Dementsprechend muss im Vorfeld für das Verwaltungsportal in der PVOG-Komponente Benutzerverwaltung das entsprechende Benutzerkonto (technischer Servicenutzer) angelegt und mit den entsprechenden Berechtigungen versehen worden sein. Das Anlegen des Benutzerkontos kann über die E-Mail-Adresse: dataportpvogsupport@dataport.de formlos beantragt werden.

Nach dem Anlegen des Benutzerkontos in der PVOG-Komponente Benutzerverwaltung erhält der Antragsteller die entsprechenden Anmeldedaten in Form eines Nutzernamens (aka Client ID) und eines Passworts (aka Client Secret).

Mithilfe der Anmeldedaten kann sich das Verwaltungsportal gegenüber der PVOG-Komponente Benutzerverwaltung authentifizieren (Authentifizierungsmethode: OpenID Connect Client Credentials) und erhält im Gegenzug ein Access Token (technisches Format: JSON Web Token).

Beim Zugriff auf die Schnittstelle des Bereitstelldienstes zum Abrufen der Leistungsdaten muss das Verwaltungsportal das Access Token mitsenden. Das Access Token hat nur eine begrenzte Lebensdauer und muss regelmäßig erneuert werden, wofür man von der PVOG-Komponente Benutzerverwaltung ein Refresh-Token mitgeliefert bekommt. Dies wird aber von üblichen Frameworks automatisch erledigt. In der Abbildung wird der gesamte Ablauf in Form eines UML Sequenzdiagramms dargestellt.

Ablauf Authentifizierung und Anfrage an den Bereitstelldienst

Im Folgenden werden einige Beispielnachrichten gezeigt. Authentifizierung gegenüber der PVOG-Komponente Benutzerverwaltung (in der PVOG-Stage-Umgebung) mithilfe des Kommandozeilenbefehls Curl um ein Access Token zu erhalten.

curl -X POST \
  'https://stage.pvog.fitko.net/auth/realms/pvog/protocol/openid-connect/token' \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Host: stage.pvog.fitko.net' \
  -d 'grant_type=client_credentials&client_id=client_example&client_secret=<CLIENT_SECRET>'

Die PVOG-Komponente Benutzerverwaltung validiert die übertragenen Anmeldedaten und antwortet im Erfolgsfall mit einem Access Token.

{
"access_token":
"<ACCESS_TOKEN>",
    …
    "token_type": "bearer",
    …
}

Anfrage an die PVOG-Komponente Bereitstelldienst (in der PVOG-Stage-Umgebung) mithilfe des Kommandozeilenbefehls Curl um Leistungsdaten abzurufen.

curl -X GET \
  'https://stage.pvog.fitko.net/bereitstelldienst/api/v2/verwaltungsobjekte?index=0&ars=%25' \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: stage.pvog.fitko.net' \
  -H 'Authorization: Bearer
<ACCESS_TOKEN>'

Verschlüsselung der Übertragungswege

Der Zugriff auf die Schnittstelle muss über eine verschlüsselte Verbindung erfolgen, um ausschließen zu können, dass die Daten während der Übertragung manipuliert werden können. Die Verschlüsselung der Übertragungswege erfolgt auf Basis von TLS (mindestens Version 1.2).

Anfrageparameter

Die zu übertragenden Datenmengen können schnell sehr groß werden. Aus diesem Grund müssen die Daten in sinnvolle Teilmengen unterteilt werden. Dafür sind die Datensätze in eine Reihenfolge gebracht worden. Bei einer Anfrage muss angegeben werden, welche Daten man zuletzt empfangen hat, indem man den zuletzt erhaltenen index übergibt. Gibt man das nicht an, dann werden die ersten Daten aus der Datenreihe geliefert. In der Antwort ist auch die Information enthalten, ob die Anfrage vollständig beantwortet wurde oder ob weitere Datensätze abgerufen werden müssen. Dazu müssen die entsprechenden Parameter gesetzt werden. Die Request-Parameter der Schnittstelle sind in der folgenden Tabelle aufgelistet.

Parameter	Beschreibung
ars	Eine komma-separierte Liste an amtlichen Regionalschlüssel (ARS) oder ARS-Mustern. Ein amtlicher Regionalschlüssel ist eine 12-stellige Ziffernfolge. Ein ARS-Muster ist ein ARS-Schlüssel, bei dem ein Teil des Schlüssels von rechts an durch % ersetzt wurde. Mithilfe dieses Parameters kann die Abfrage auf bestimmte geografische Bereiche eingeschränkt werden. Für einen Abruf des Gesamtdatenbestandes muss ars den Wert ‚%‘ haben. Wichtig: Beim Abruf eines Datenbestandes und späterer Aktualisierungen muss der ars-Parameter bei jeder Anfrage den gleichen Wert haben, damit die gelieferten Daten referenzkonsistent sind. Bitte beachten: Das Sonderzeichen ‚%‘ muss in der URL als %25 kodiert werden. Für die Abfrage aller Hamburger Daten muss das ARS-Muster 02% also als Parameter ars=02%25` übergeben werden.
index	Ein Update-Index über alle Verwaltungsobjekte. Bei einer initialen Abfrage muss dieser auf 0 gesetzt sein. Als Teil der Antwort bekommt man den nächsten Wert mitgeteilt, um die nächsten Daten abzurufen. [required=true]
XZuFi-Schema-Version	Die Verwaltungsobjekte im Rückgabeobjekt der Schnittstelle werden in Form einer XZuFi Transfernachricht übergeben. Wenn aktuell mehrere Versionen des XZuFi-Schemas unterstützt werden, muss die gewünschte Version als Teil der Anfrage formuliert werden. Bei den verschiedenen Versionen der Schnittstelle wird dies unterschiedlich gehandhabt. Im Produktportal finden sich bei den Beschreibungen der REST-Schnittstellen des Bereitstelldienstes (öffnet in neuem Tab) genaue Informationen dazu.

info

Der Update-Index („Timestamp“) ist ein logischer Zähler. Beim ersten Aufruf ist dieser auf den Wert ‚0‘ zu setzen. In der Antwort wird der nächste Update-Index zurückgeliefert, der beim darauffolgenden Aufruf wieder als Eingabewert gesetzt werden soll, um weitere Datensätze abzufragen.

Nachrichtenformat

Die Rückgabe der Antwort auf die Anfrage erfolgt im folgenden JSON-Format:

Parameter	Beschreibung
anzahlObjekte	Anzahl der Objekte innerhalb der Antwort. Diese Anzahl wird vom Server berechnet für eine performante Auslieferung. Um alle Objekte zu erhalten, müssen gegebenenfalls mehrere Anfragen gestellt werden. Die nächste Anfrage muss dann den Update-Index der letzten Antwort verwenden.
naechsterIndex	Der für die nächste Anfrage benötigte Update-Index, um weitere Antwortobjekte zu erhalten.
naechsteAnfrageURL	Vorgefertigte URL der nächsten Anfrage.
vollstaendig	Boolean der anzeigt, ob alle Daten für den aktuellen Datenabruf übermittelt wurden (true) oder ob noch Updates vorhanden sind (false).
xzufiObjekte	Die angeforderten Objekte im Format einer XZuFi Transferoperation in der angeforderten XZuFi-Schema-Version.

Nachfolgend ein Auszug aus einer beispielhaften Antwortnachricht.

{
    "naechsterIndex": 41221,
    "vollstaendig": false,
    "anzahlObjekte": 10,
    "naechsteAnfrageUrl": "https://stage.pvog.fitko.net/bereitstelldienst/api/v2/verwaltungsobjekte?index=41221&ars=%25",
    "xzufiObjekte": "…"
}

Der Rückgabeparameter xzufiObjekte enthält eine Transfernachricht nach der XZuFi-Spezifikation (öffnet in neuem Tab) in einer der aktuell unterstützten Versionen, je nach Wahl des Anfrageparameters xzufiversion im Accept-Header. Da der Datenbestand im Bereitstelldienst in gemischten Versionen vorliegen kann, für die Ausgabe aber eine konkrete Version angegeben werden muss, werden einzelne Verwaltungsobjekte bei Bedarf vor der Auslieferung in das Format der gewünschten XZuFi-Version konvertiert.

Falls es keine neuen Daten gibt, hat anzahlObjekte den Wert 0 und der Parameter vollstaendig hat den Wert true. Wenn es neue Daten gibt, dann bekommt man einen größeren Wert für nextIndex geliefert sowie eine neue naechsteAnfrageUrl. Dieser muss wie bei der initialen Datenabfrage gefolgt werden, bis vollstaendig wieder den Wert true annimmt. Dann wurde der aktuell im Bereitstelldienst vorhandene Datenbestand komplett übertragen.

Rückgabecodes

Der REST-Endpunkt für den Abruf von Leistungen antwortet mit den folgenden HTTP-Statuscodes auf eingehende Anfragen:

HTTP Statuscode	Bedeutung
200	Anfrage erfolgreich abgearbeitet.
400	Fehler in den Anfrageparametern.
401	Autorisierung gegenüber Keycloak fehlt.
403	Berechtigung für den Zugriff auf den Endpunkt fehlt.
500	Interner Fehler bei der Verarbeitung der Anfrage.

Datenfilter

Die Bereitstellung der Daten durch den Bereitstellungsdienst unterstützt lediglich ein Filtern auf Basis der regionalen Zuordnung mithilfe der amtlichen Regionalschlüssel (siehe Anfrageparameter).

Bei dem Abruf von mehreren Teilmengen (z. B. einzelne Bundesländer, Landkreise oder Gemeinden), die sich nicht mit einem Muster abbilden lassen, gibt es mehrere Punkte zu berücksichtigen. Es können ein oder mehrere ARS-Schlüssel und ARS-Muster in der gleichen Abfrage abgefragt werden. Werden mehrere Sätze an ARS-Schlüsseln und ARS-Mustern benutzt, dann muss für jeden Satz an amtlichen Regionalschlüsseln und ARS-Mustern, ein eigener Update-Index verwaltet werden. Zum Beispiel in einem separaten Prozess. Wenn nun ein Update des eigenen Datenbestandes durchgeführt werden soll, muss für jeden Satz an ARS-Schlüsseln und ARSMustern der richtige Update-Index verwendet werden und man darf nicht den Update-Index eines anderen Satzes verwenden. Dies würde sonst zur Folge haben, dass gewisse Updates möglicherweise verloren gehen, wenn der Update-Index zu weit erhöht wird. Es kann passieren, dass dadurch die gespeicherten Zähler (größere) Unterschiede aufweisen, wenn für einzelne Sätze an ARS-Schlüsseln und ARS-Mustern über einen längeren Zeitraum keine Updates über die Redaktionssysteme kamen. Sobald jedoch ein Update da ist, wird die "Lücke" geschlossen. Es wird jedoch aus Performancegründen empfohlen, sich auf möglichst wenige parallele Anfragen zu beschränken.

Beim Abruf von Teildatenbeständen mithilfe der ARS-basierten Datenfilter kann es unter bestimmten Umständen dazu kommen, dass Objekte (z. B. Zuständigkeiten) ausgeliefert werden, die auf Objekte verweisen, die bisher noch nicht ausgeliefert worden sind. Ruft der Schnittstellenkonsument aber konsequent alle Datenänderungen weiter ab, bis alle Datenänderungen komplett ausgeliefert worden sind (Attribut vollstaendig in der Antwortnachricht enthält den Wert true), dann sind auch die zwischenzeitlich "fehlenden" Objekte (z. B. Organisationseinheiten) korrekt ausgeliefert.

Datenaktualität

Die Aktualität der Daten ist abhängig von der Frequenz, in der die Daten über den Sammlerdienst im Portalverbund aktualisiert werden. Nach aktueller Planung bezieht der Sammlerdienst einmal am Tag aktuelle Daten von den angeschlossenen Redaktionssystemen (Quellsysteme). Dementsprechend werden auch die Daten, die der Bereitstelldienst zur Verfügung stellt, nur einmal am Tag pro Redaktionssystem aktualisiert.

Nutzungsfrequenz

In bestimmten Fällen kann es vorkommen, dass ein Redaktionssystem falsche Daten geliefert hat (z. B. falsche URL zu einem Online-Dienst). In diesem Fall können die falschen Daten im PVOG korrigiert werden. Es muss nicht auf den nächsten Export des Redaktionssystems gewartet werden. Um auch diese Änderungen zeitnah abzurufen, wird empfohlen, die Schnittstelle mehrmals am Tag abzurufen. Abrufintervalle unter 15 Minuten werden nicht empfohlen, um nicht unnötig Last zu generieren.

Paging

Aufgrund der großen Datenmengen wird die Rückgabe der angefragten Datensätze auf eine maximale Größe begrenzt (z. B. 5 Mb). Die Datensätze sind dabei aufsteigend nach Änderungsdatum sortiert. Es werden also zunächst die jeweils ältesten Datensätze zurückgegeben. Dementsprechend muss der Aufrufer ggf. mehrere Anfragen senden bis alle Daten übermittelt worden sind (siehe auch Nachrichtenformat).

Aufbewahrungsfristen

Die abgerufenen Daten können personenbezogene Daten enthalten. Beispielsweise werden in den Organisationseinheiten die Kontaktinformationen zu Ansprechpartner für Verwaltungsleistungen gepflegt. Dementsprechend müssen die heruntergeladenen Daten gemäß Datenschutz-Grundverordnung (DSGVO) und Bundesdatenschutzgesetz (BDSG) weiterverarbeitet werden. Beispielsweise dürfen die Daten nur für die notwendige Dauer der Verarbeitung aufbewahrt werden.