Informationen zur API zum Abrufen spezifischer Daten aus dem Swarm Control Center.
Über eine API können Sie alle Einstellungen und Informationen, die im Swarm Control Center verfügbar sind, problemlos abrufen. Nachfolgend finden Sie die Swagger-Dokumentation, als Beispiel fungiert unsere Demo-Instanz: Swagger UI
Im Allgemeinen halten wir uns an den hier dokumentierten OAuth 2.0 Client Credentials Flow (Microsoft).
Stellen Sie sicher, dass Sie Ihre Tenant-ID als Kopfzeile in den Authentifizierungsfluss einfügen.
Um den ersten Teil der URL für Ihre spezifische API-Dokumentation, bzw. Swagger UI zu erhalten, können Sie entweder unseren Support kontaktieren oder sie aus dem Quellcode Ihres Swarm Control Centers abrufen:
In unserem Beispiel lautet die URL:
https://demo-control-center-api-2a97516c.azurewebsites.net/v3/documentation/swagger-ui/#/
Rufen Sie die Swagger UI auf
2. Der API-Call gibt Ihnen wie folgt Auskunft zum Gerätestatus:
3. Die verschiedenen Status sind wie folgt in der API-Dokumentation definiert:
4. Sie können ebenfalls den Status der einzelnen Streams abrufen. Die API liefert folgende Ergebnisse:
Wie Sie Ihre generierten Daten ganz einfach in externe Anwendungen integrieren können.
Wenn Sie Ihre Daten in andere Plattformen oder beispielsweise Anzeigetafeln integrieren möchten, bieten wir dafür zwei Möglichkeiten.
Möglichkeit 1: Erhalten Sie nur die Daten, die Sie gemäß den Abfragen, die Sie in Data Analytics erstellen können, benötigen, und verwenden Sie dann unsere API:
Möglichkeit 2: Erhalten Sie jedes generiertes Event direkt von der Box, ohne, dass dieses über die Cloud verarbeitet wird, indem Sie die MQTT-Option verwenden:
Beachten Sie bitte, dass Sie mit dieser Option die Daten von jedem Event erhalten. Data Analytics kann nicht verwendet werden.
So nutzen Sie Ihre benutzerdefinierte MQTT-Verbindung.
Sobald Sie Ihren Anwendungsfall im Swarm Control Center konfiguriert haben, generiert unsere Software Events. Diese werden als Standard-JSON übertragen. Wenn Sie Data Analytics nicht nutzen und die Daten stattdessen lieber via API abrufen möchten, bieten wir Ihnen die Möglichkeit, einen benutzerdefinierten MQTT-Broker zu konfigurieren.
Die Swarm Perception Box sendet Events in Form eines JSON an einen von Ihnen konfigurierten MQTT-Broker. Für die Übertragung wird das QoS Level 1 verwendet. Falls Events nicht zugestellt werden können, z.B. aufgrund einer fehlenden Verbindung, werden Events bis zu 24.000 Messages gecacht.
Für noch höhere Sicherheit können Sie MQTT über SSL verwenden. Fügen Sie dafür einfach das Präfix ssl:// zur Broker-Konfiguration hinzu.
Wenn die Komprimierung konfiguriert ist, werden die Events mit zlib/inflate komprimiert:
Im unten verlinkten GitHub-Repository finden Sie das Event-Schema der verschiedenen Konfigurationstypen:
Es gibt mehrere Möglichkeiten, wie Sie ein JSON gegen ein Schema validieren können. Eine gute Übersicht bietet json-schema.org. Wir empfehlen außerdem jsonschemalint.com als Online-Tool zur manuellen Validierung eines JSON gegen unser Schema.
Der Header des JSON wird durch eine Version des verwendeten Formats definiert (Propertyversion). Das Format ist major.minor, wobei eine Änderung der Hauptversion eine Änderung mit Abwärtskompatibilität darstellt. Für eindeutige Identifikatoren verlassen wir uns auf UUID. Zeitstempel werden gemäß ISO8601 definiert.
Ein Counting-Line-Event wird ausgelöst, wenn ein Objekt besagte Counting Line überquert (identifiziert durch lineId). Diese Linie hat einen benutzerdefinierten Namen (lineName). Ein Zeitstempel (timestamp) wird gesetzt, wenn das Event auftritt. Das Objekt kann die Counting Line in zwei Richtungen überqueren (direction) und sich entweder hinein- (In) oder hinausbewegen (Out). Zusätzlich wird das Objekt, das die CL überquert, klassifiziert (class und subclass). Die Klassen hängen vom Anwendungsfall ab.
Wenn das ANPR-Feature aktiviert ist, werden die Kennzeichen (plateNumber) sowie das Herkunftsland des Kennzeichens (numberPlateOrigin) zum Event hinzugefügt.
ANPR wird benötigt, um Bilder der Kennzeichen bei Ein- und Ausfahrt zu machen. Die Kennzeichenbilder werden im JPG-Format an die MQTT-Message angehängt und mit BASE64 codiert.
Bitte kontaktieren Sie unseren Support, um Kennzeichenbilder via MQTT zu aktivieren.
Wenn Speed Estimation aktiviert sowie konfiguriert ist, gibt speedestimate die Ausgabe der Geschwindigkeitsschätzung in km/h an.
Das Region-of-Interest-Event hängt vom Typ der RoI ab. Beispiel: Eine Region of Interest mit dem Typ Parking generiert ein ParkingEvent, während der Typ Generic ein RegionOfInterestEvent generiert:
ParkingEvent:
Dieses Event wird in einem Zeitintervall von zehn Sekunden ausgelöst. Die Informationen aller konfigurierten Parking-RoI werden in einem einzelnen Event aggregiert. In parkingSummary werden alle RoI mit der konfigurierten capacity und der aktuellen Anzahl der vehicles in der RoI selbst angezeigt.
Als Gesamtübersicht haben Sie dann totalCapacity und totalVehicles, die einen vollständigen Überblick über alle konfigurierten RoI mit dem Typ Parking in diesem Kamerastream geben. Zusätzlich besteht die Möglichkeit, ANPR für Parking-RoI zu aktivieren. Dadurch werden das Kennzeichen (plateNumber) sowie das Herkunftsland des Kennzeichens (numberPlateOrigin) im String-Format bereitgestellt.
Ein RegionOfInterestEvent wird entweder durch eine Zustandsänderung oder ein bestimmtes Zeitintervall ausgelöst (triggerType). Der Zustand (state) kann von occupied to vacant oder umgekehrt wechseln. Occupied trifft zu, wenn die Anzahl der Objekte in der RoI mindestens so hoch ist wie zuvor als capacity konfiguriert.
Jedes Event enthält einen benutzerdefinierten Namen (roiName) und einen Zeitstempel (timestamp), wann das Event auftritt, bzw. aufgetreten ist. Erkannte Objekte und ihre zugeordneten Klassen sowie Verweilzeiten werden aufgelistet (objects). Die Klassen hängen vom Anwendungsfall ab.
Wenn eine Regel für ein bestimmtes Ereignis angelegt wurde, wird ein entsprechendes Rule-Event gesendet. Dieses wird entsprechend basierend auf der gewählten Logik in Kombination mit den definierten Bedingungen ausgelöst. Ein Zeitstempel (timestamp) wird gesetzt, wenn das Event auftritt. Das Rule-Event enthält allgemeine Informationen zum Namen, zum Gerät und zur Stream-UUID. Darüber hinaus ist die gewählte gewählte, standardmäßige Eventinformation Teil der Message und im gleichen Format wie andere Messages für diese Eventtrigger.
In diesem Modus werden Objekte getrackt, während sie sich im Sichtfeld bewegen. Sobald das Objekt das Sichtfeld wieder verlassen hat, wird entsprechend die vollständige Route des Objekts generiert.
Der Raw Track enthält die Klassifizierung () und die Spur des Objekts durch das Sichtfeld. Die Klassen hängen vom Anwendungsfall ab.
Die Spur ist als eine Abfolge von path-Elementen definiert, die einen Zeitstempel sowie die Koordinaten enthalten. Die Koordinaten basieren auf dem Punkt der oberen linken Ecke kombiniert mit Breite und Höhe des jeweiligen Objekts. Pro Event gibt es maximal zehn path-Elemente. Zum besseren Verständnis der Berechnung der Koordinaten dient folgende Aufschlüsselung:
Wie bereits erwähnt, enthält jedes Event eine Information zur Klasse/Klassifizierung des jeweiligen, erkannten Objekts. Zur besseren Übersicht haben wir in Klassen (class) und Unterklassen (sub class) aufgeteilt. Beispiele finden Sie hier:
Beispiel: Eine Counting Line erkennt einen Lieferwagen (van). Hinweis: Die class ist hier car, während die sub class van ist.
Zugriff auf die zugrunde liegenden Daten von Data Analytics, bzw. der Widgets via API.
Für jedes Widget in Data Analytics können die zugrunde liegenden Daten über eine bereitgestellte REST-API abgefragt werden. Die Integration in Anwendungen von Drittanbietern funktioniert schnell und unkompliziert.
Sobald Sie ein Widget konfigurieren, finden die den Punkt API Call im Seitenmenü. Diese Option ist für jedes Widget verfügbar.
Das dann angezeigte Dialogfeld enthält detaillierte Informationen darüber, wie der API-Call für die Daten dieses Widgets aussieht. Kopieren Sie den bereitgestellten Curl-Befehl und führen Sie ihn entsprechend aus. Sie können den Call direkt im Dialogfeld testen, einschließlich des Antwortformats, indem Sie auf Try it out! klicken:
Dieser Access Token ist temporär. Für eine dauerhafte Integration in Anwendungen von Drittanbietern benötigen Sie einen permanenten Token. Melden Sie sich diesbezüglich gerne bei unserem Support.
Wir halten uns strikt an den von Microsoft dokumentieren OAuth flow. Es gibt mehrere Client Libraries, die Sie verwenden können.
In der untenstehenden GitHub-Repository finden Sie Beispielcodes, die zeigen, wie Sie die Daten in Ihre eigene Anwendung integrieren können. Es wird veranschaulicht, wie Sie die erforderliche Authentifizierung durchführen und Abfragen durchführen können.
Untenstehend sehen Sie ein Widget in Data Analytics, das für die Fahrradzählung genutzt wird. Der entsprechende Widget-Typ (Traffic Counting) wurde ausgewählt, die Daten werden pro Tag aggregiert, nach Objektklasse und Richtung aufgeschlüsselt und nach Fahrrädern gefiltert.
API-Request
Der API-Call zeigt den entsprechenden GET-Request für diese Daten wie untenstehend dargestellt:
API-Response (gekürzt):
Die REST-API basiert auf Cube.js. Weitere Informationen und Details dazu und zur Funktionsweise generell finden Sie in dieser externen Dokumentation.
