​​How to GeoEvent #2: Integration von Echtzeitdaten über eine REST API​ 

Eine der wichtigsten Fragen bei der Entwicklung einer Echtzeitlösung lautet: Wie integriere ich die gewünschten Daten in mein GIS? Eigentlich ganz einfach. Im zweiten Teil unserer vierteiligen Blogreihe versuchen wir dieser Frage auf die Spur zu kommen und euch beim Integrationsworkflow an die Hand zu nehmen.

Echtzeitdaten können über sehr unterschiedliche Protokolle und in verschiedenen Datenformaten bereitgestellt werden. Diese Protokolle können dann von anderen Anwendungen gelesen, verarbeitet und gespeichert werden. Zu den gängigen Protokollen gehören z.B. REST-API, WebSockets, MQTT, RabbitMQ, Kafka u.a.

Verkehrssituation in Münster

In unserem fiktiven Use Case (lese dazu Teil 1 unserer Reihe)  wollen wir die aktuelle Verkehrssituation in Münster abbilden und die wichtigsten Daten zur Busverspätung abbilden. Anhand dieser Fragestellung können wir festlegen, was wir mit unserer Echtzeitanwendung abbilden wollen und welche Daten wir dafür benötigen.  

Datengrundlage

Die Stadt Münster gemeinsam mit Stadtwerke Münster stellen als Smart City sehr gute öffentliche Daten zur Verfügung, die wir für unseren Use Case gut nutzen können. Viele zusätzliche Layer können direkt aus dem Esri Living Atlas im Map Viewer abgerufen werden. Darauf gehen wir in späteren Teilen genauer ein.

Für unseren Use Case passen Daten zu den aktuellen Buspositionen in Echtzeit perfekt. Hierbei handelt es sich um aktuelle GPS-Positionsmeldungen der Busse im GeoJSON-Format, die sich alle 3 Sekunden aktualisieren. Diese Daten werden über eine REST-API von der Stadtwerke Münster in Zusammenarbeit mit con terra GmbH frei zugänglich bereitgestellt (herzlichen Dank an dieser Stelle!).

Was ist REST API und GeoJSON?

Bevor wir durch die einzelnen Schritte der Datenimplementierung in ArcGIS GeoEvent Server durchgehen, ist es ratsam, die wichtigsten Informationen über die REST API und GeoJSON-Format zu verstehen.

Eine REST-API (Representational State Transfer Application Programming Interface) ist ein Daten-Architekturstil für die Entwicklung von Netzwerk-Anwendungen und Datenkommunikation. Sie zeichnet sich durch eine einfache und einheitliche Architektur, Skalierbarkeit und Flexibilität aus und wird deshalb im Kontext der Echtzeitdaten oft angewendet.

• Die Kommunikation zwischen einem Client und einem Server findet über HTTP-Anfragen statt.
• Die wichtigsten Abfragemethoden sind dabei: GET (abrufen von Datensätzen), POST (erstellen neuer Datensätze), PUT (aktualisieren der Datensätze), DELETE (löschen der Datensätze). Eine API kann gleichzeitig von mehreren Clients genutzt werden.  
• Informationen können dem Client über eine REST API in jedem Format geliefert werden, z. B. JSON, HTML, XLT, PHP, Python usw.

• GeoJSON ist ein offenes Standardaustauschformat für räumliche Daten zur Darstellung von einfachen geographischen Features und deren nichträumlichen Attributen. Mehr über GeoJSON können Sie auch in der ArcGIS Enterprise Dokumentation nachlesen.

Warum brauchen wir den GeoEvent Server?

Sie können mal versuchen, den Datensatz im Map Viewer als GeoJSON hinzuzufügen und werden tatsächlich erfolgreich sein! Allerdings können wir die Daten so nur alle 30 Sekunden aktualisieren und nichts prozessieren oder speichern, weshalb die GeoJSON Query-Layer Funktionalität für unseren Anwendungsfall nicht ausreicht.

Dadurch, dass die Buspositionen sich alle paar Sekunden aktualisieren, müssen wir den ArcGIS GeoEvent Server nutzen. Dieser ist in der Lage, hochfrequente Daten von Drittsystemen abzufragen, zu analysieren und sofort auf der Karte zu Visualisieren oder sie an weitere Systeme weiterzuleiten.

Echzeitdaten integrieren: Schritt für Schritt über REST API

Nachfolgend leiten wir Schritt für Schritt durch den Prozess der Datenimplementierung in ArcGIS GeoEvent Server.

Schritt 1: Vorbereitungen

Nun legen wir los. Bevor wir mit dem Input starten, sollten wir kontrollieren, ob alle Verbindungen funktionieren. Zwei Aspekte sollten beachtet werden: 

1. Sicherstellen, dass unser GeoEvent Server ein aktives ArcGIS Portal als DataStore registriert hat.
2. Die Verbindung zum Spatiotemporal Big Data Store kontrollieren, weil wir Daten im Big Data Store speichern wollen.  

Aktive Verbindung sicherstellen

Im GeoEvent Manager unter Site>Data Store können wir prüfen, ob eine valide Verbindung zu ArcGIS Enterprise besteht. Dies sehen wir bei der Status-Meldung. Falls noch keine Verbindung aufgebaut wurde, sehen wir ein rotes Symbol (siehe Abb. unten) – alles klar, hier müssen wir was tun.

Über das -Symbol gelangen wir in die Registrierungsmaske und können hier unseren Named-User der ArcGIS Enterprise Organisation mit den Zugangsdaten eingeben. Der Named-User muss mindestens über Publisher-Rechte im ArcGIS Enterprise Portal verfügen. Mehr dazu kannst Du hier nachlesen.

Nach einer erfolgreichen Anmeldung wird sich der Status sofort ändern – perfekt!

Big Data Store kontrollieren

Nun checken wir noch den Big Data Store. Unter Site > Spatiotemporal Big Data Store prüfen wir, ob es eine gültige Verbindung zu einem Big Data Store gibt. Sobald Sie ein Spatiotemporal Big Data Store konfiguriert haben, wird dieser automatisch unter der eingerichteten Data Store Verbindung (hier Default) erscheinen.

Schritt 2: Einen Input-Konnektor erstellen

Für den Import von Echtzeitdaten muss im GeoEvent Server ein Input-Konnektor konfiguriert werden. Dazu gehen wir zurück auf den Manager Reiter und klicken auf Add Input.

Übersicht der Konnektoren

Der GeoEvent Server hat zahlreiche Out-of-the Box Konnektoren, mit denen sich die gängigsten Datenformate wie JSON, GeoJSON, Text, RSS oder XML von verschiedenen Endpunkten leicht importieren lassen.

Eingabemaske ausfüllen

Unsere Echtzeit-Beispieldaten liegen im GeoJSON-Format vor und sind direkt über die API abrufbar. Hierfür werden wir deshalb den „Poll an external Website für GeoGSON“ verwenden. In der Eingabemaske müssen wir einige Parameter ausfüllen, damit die Daten richtig ankommen.

1. Name: Hier müssen wir einen eindeutigen und aussagekräftigen Namen für den Input vergeben. Wir haben uns für „busradar-muenster-geojson-poll-in“ entschieden. 
2. URL: Bei der URL geben wir die URL ein, unter der wir die Events im GeoJSON Format abrufen können. In unserem Beispiel: https://rest.busradar.conterra.de/prod/fahrzeuge. Schaut euch die Daten sowie die einzelnen Attribute unbedingt an.
3. Create GeoEvent Definition: Hier können wir auswählen, ob ein neues oder ein bestehendes Datenschema für die Daten verwendet wird. Da wir die Daten zum ersten Mal abrufen, können wir vorerst eine automatische Definition durch GeoEvent erstellen lassen. Deshalb klicken wir erstmal auf Yes.
4. GeoEvent Definition Name: Den automatischen Namen „NewGeoEventDef“ durch einen eindeutigeren Namen ersetzen, z. B. „busradar-muenster-in-temp“. Wir haben einen temporären Namen vergeben, da wir diese Definition später ersetzten werden.

Alle anderen Parameter können in diesem Fall einfach übernommen werden. Eine Beschreibung der Parameter können Sie hier nachlesen.

Input starten

Nun speichern wir den Konnektor und müssen den Input nur starten. Das macht man mit dem -Button.

Sobald der Input läuft, verändern sich auch die Statistiken. Sie bedeuten Folgendes: 

• Anhand der Count-Zahlen können wir ablesen wie viele Events in GeoEvent Server bisher angekommen sind.
• Die Rate verrät uns, wie viele Events pro Sekunde (durchschnittliche über die letzten 5 min) gerade ankommen.
• Die Max Rate gibt uns (logischerweise) die bisher höchste Rate an. 
• Time Since Last zeigt, wann der letzte Event angekommen ist.

Schritt 3: GeoEvent Service erstellen

Nun kommen die einzelnen Buspositionen an – Klasse! Wir sollten das Ganze aber noch ein bisschen aufhübschen. Lasst uns dafür einen Service anlegen, um zu schauen, was für Daten wir nun erhalten. Dafür klicken wir auf Add Service und gib dem Service einen Namen, ich habe es „busradar-muenster“ genannt.

Nach dem Erstellen gelangt man in eine Arbeitsoberfläche, die noch leer ist (das wird sich natürlich ändern).

• In der oberen Leiste können wir den Service starten und speichern (Publish-Button).
• Ganz links greife ich direkt auf alle meine Werkzeuge, Inputs, Outputs und Einstellungen zu (dieser Bereich ist übrigens ausklappbar).
• Unten befindet sich der Sampler, mit dem wir den Datenfluss checken können.

Konnektor hinzufügen und Output erstellen

Apropo Daten, diese wollen wir ja sehen. Dafür müssen wir im Service unseren neu erstellten Konnektor hinzufügen und ein Output erstellen. Unter den Inputs suche ich nun meinen Konnektor „busradar-muenster-geojson-poll-in“ und schiebe ihn per Drag Drop in das Arbeitsfeld.

Man kann Konnektoren übrigens auch direkt in der Service Oberfläche erstellen. Dafür ein Doppelklick auf New Elements > Output und in diesem Fall „Push Text to an External TCP Socket“ auswählen.

Wir lassen alle Einstellungen so wie sie sind, weil das Ganze eben nur für Testzwecke ist, und klicken auf „Speichern“. Dieser Konnektor erscheint ebenfalls in der Arbeitsfläche. Nun verbinden wir den Input- und Output-Konnektor und klicken auf „Publish“, um es zu speichern und gleichzeitig zu starten.

Nach dem Start des Services

Nach dem Starten gehen die Statistiken hoch und jetzt können wir uns mit dem Sampler die Daten anschauen. Dafür klicken wir mit der rechten Maustaste auf den Vierbindungspfeil und wählen „Sample Route“. Im Sampler werden dann die ersten zehn Events im JSON Format angezeigt. Wir können aber auch eine Kartenansicht wählen, um zu schauen, ob die Objekte richtig verortet sind.

Schritt 4: Datenschema anpassen

Wenn wir uns die Daten von einem Event im Sampler genauer anschauen, dann sehen wir, dass sie genau so in der API aussehen. Das bedeutet, dass GeoEvent das Datenschema richtig erkannt hat.

{ 
  "GED_Name": "busradar-muenster-in-temp", 
  "linienid": "15", 
  "richtungsid": "2", 
  "akthst": "44211", 
  "delay": 403.0, 
  "richtungstext": "Albachten Bahnhof", 
  "starthst": "45310", 
  "betriebstag": "2024-08-21", 
  "sequenz": 34.0, 
  "linientext": "15", 
  "fahrzeugid": "5703", 
  "fahrtstatus": "Ist", 
  "fahrtbezeichner": "210824_100008_9_15_8", 
  "abfahrtstart": "1724241840", 
  "visfahrplanlagezst": 1.724245244E9, 
  "ankunftziel": "1724245920", 
  "zielhst": "46350", 
  "geometry": { 
    "x": 7.5918861, 
    "y": 51.9300903, 
    "spatialReference": { 
      "wkid": 4326 
    } 

Warum Datenschemata wichtig sind

Datenschemata sind ein sehr wichtiger Aspekt, wenn es um Echtzeitdaten geht. Zu Beginn passieren hier am häufigsten Fehler. Es ist sehr wichtig, dass GeoEvent Server weiß, welche Daten und in welchem Format ankommen.

Im Falle von JSON bzw. GeoJSON müssen die Attribute im Datenschema mit den Feldnamen in der API übereinstimmen. Außerdem muss der korrekte Datentyp für die Attribute ausgewählt werden, damit der GeoEvent Server die Daten richtig lesen kann. In späteren Analysen können Bezeichnungen, Datenformate angepasst und unnötige Felder gelöscht werden.

Automatisches Datenschema bearbeiten

Beim Erstellen des Input Konnektors haben wir ein automatisches Datenschema generieren lassen. Dieses Datenschema können wir unter GeoEvent Definitions ansehen und bearbeiten. Dazu gehen wir in unserem Service zu Site Settings > GeoEvent Definitions und suchen nach „busradar-muenster-in-temp“. Unter Owner Name sehen wir, dass diese Definition autogeneriert ist und durch unseren Input-Konnektor verwendet wird.

Anstelle einer automatisch generierten Definition, ist es ratsam, eine fixe Definition für einen Input-Konnektor festzulegen, die sich nicht ändert und wo die Datentypen und Tags korrekt konfiguriert sind. Deshalb schließen wir diese Ansicht und machen eine Kopie der Definition, indem wir in der Liste aller Definitionen auf folgendes Symbol klicken:

Es öffnet sich die Definitionsmaske, die wir nun verändern wollen:  

• Wir vergeben als erstes einen festen Namen „busradar-muenster-in“, gehen noch einmal durch alle Attribute durch und prüfen, ob der Datentyp passt.
• Die Felder „abfahrtstart“, „visfahrplanlagezst“ und „ankunftziel“ sind eigentlich Zeitfelder und das möchten wir an der Definition anpassen. Mit dem Stift-Symbol können wir einzelne Felder editieren. So verändern wir für die genannten drei Felder den Datentyp von „String“ bzw. „Double“ auf „Date“.

• Außerdem vergeben wir über das gleiche Edit-Fenster für einige Felder zusätzlich Tags. Warum Tags wichtig sind, könnt ihr hier nachlesen. Das Feld „fahrzeugid“ bekommt das Tag „TRACK_ID“, Feld „visfahrplanlagezst“ „TIME_START“ und das Feld „geometry“ den Tag „GEOMETRY“. Nun speichern wir unsere Veränderungen und schließen das Fenster mit den Definitionen.

Im letzten Schritt ersetzten wir die automatisch erstellte Definition im Input-Konnektor. Dafür klicken wir zweimal auf den grünen Input-Konnektor und verändern die Einstellungen: 

• Create GeoEvent Definition: No. 
• GeoEvent Definition Name (existing): „busradar-muenster-in” aus der Dropdown-Liste auswählen. 

Nun speichern wir den Konnektor sowie den Service („Publish“-Button) und schauen im Sampler, ob sich die Daten geändert haben. Tatsächlich stehen nun in den drei Zeit-Feldern nicht mehr Zahlen, sondern Daten.

Aber Achtung: Wenn wir genauer hinsehen, fällt auf, dass der Zeitstempel circa vier Jahre in der Vergangenheit liegt. Das müssen wir beim nächsten Mal noch unbedingt beseitigen. Aber für heute reicht es erstmal. Der dritte Teil der Reihe folgt in Kürze auf unserem Blog.

Weitere Infos

Liest noch unbedingt den ersten Beitrag dieser vierteiligen Blogreihe. Dort beschreiben wir, was man bei der Arbeit mit Echtzeitdaten beachten muss und erklären, wofür wir uns jetzt mit all den Konnektoren und Datenschemata beschäftigen. 

• Viele Infos zum GeoEvent findet ihr im englischsprachigen Community Blog von Esri Inc. sowie in der ebenfalls englischsprachigen Dokumentation für ArcGIS Entersprise. 
• Informationen zu den letzten Neuerungen im GeoEvent Server sind in diesem Blog zu finden: Neuerungen im ArcGIS GeoEvent Server | Analytics Solutions.  
• Schaut euch auch gerne das Webinar Räumliche Analyse und Data Science an.