Schnittstellenbeschreibung SensorThings API (FROST‑Server)

Einleitung

Der FROST‑Server ist die Referenzimplementierung des OGC SensorThings API Standards (Version 1.1) und die Schnittstelle, über die die vom Adapter exportierten Daten gelesen werden. Diese Seite ist eine Kurzreferenz für den Zugriff darauf — der vollständige Standard und die vollständige Serverdokumentation stehen unter Weiterführende Referenzen.

Es gibt keine gemeinsame Basis‑URL. Jeder Mandant hat einen eigenen FROST‑Server, und dessen Service‑Root steht als frost_server_url in seiner Zeile der Mandanten‑Registry — abrufbar über GET /tenant oder ablesbar auf der Seite Tenants der Verwaltungsoberfläche. Die Beispiele auf dieser Seite schreiben dafür den Platzhalter {frost_server_url}; er endet auf /v1.1.

Entitäten – Übersicht

Die SensorThings API modelliert IoT‑Daten anhand von sieben Kern‑Entitäten.

Entität Zweck Endpunkt

Thing

Repräsentiert ein physisches oder virtuelles Objekt (z. B. eine Messstation).

/Things

Location

Geografischer Standort eines Things.

/Locations

Sensor

Beschreibt das Messinstrument oder den Gerätetyp.

/Sensors

ObservedProperty

Die gemessene Eigenschaft (z. B. Temperatur, CO₂‑Konzentration).

/ObservedProperties

Datastream

Verbindet Thing, Sensor und ObservedProperty zu einem Messdatenkanal.

/Datastreams

Observation

Einzelner Messwert innerhalb eines Datastreams.

/Observations

FeatureOfInterest

Räumliches Objekt, auf das sich eine Observation bezieht.

/FeaturesOfInterest

Der Adapter legt sechs davon selbst an; FeaturesOfInterest erzeugt FROST bei Bedarf selbst. Womit der Adapter die Felder jeder Entität füllt, steht in Datenmodell.

Die Beziehungen zwischen den Entitäten folgen dem UML‑Modell des OGC SensorThings Standards:

SensorThings API – Entitätenmodell

Quelle: OGC SensorThings API – Data Model

Adressierung

Jeder Entitätstyp wird über einen eigenen Pfad angesprochen. Die folgende Konvention gilt durchgängig für alle sieben:

Muster Bedeutung

/{EntitySet}

Alle Entitäten dieses Typs abrufen (Collection).

/{EntitySet}({id})

Eine einzelne Entität anhand ihrer ID abrufen.

/{EntitySet}({id})/{NavigationProperty}

Verknüpfte Entitäten über eine Beziehung navigieren.

 
curl -s "{frost_server_url}/Things"
curl -s "{frost_server_url}/Things(1)"
curl -s "{frost_server_url}/Things(1)/Datastreams"
curl -s "{frost_server_url}/Datastreams(1)/Observations"

Abfrageparameter und Filterung

Die SensorThings API unterstützt standardisierte Query‑Optionen, die als URL‑Parameter übergeben werden.

Parameter Beschreibung Beispiel

$top

Begrenzt die Anzahl der zurückgegebenen Entitäten.

$top=10

$skip

Überspringt die angegebene Anzahl an Entitäten (für Pagination).

$skip=20

$count

Gibt die Gesamtzahl der Entitäten im Ergebnis mit zurück.

$count=true

$orderby

Sortiert die Ergebnisse nach einem oder mehreren Feldern.

$orderby=phenomenonTime desc

$select

Beschränkt die zurückgegebenen Eigenschaften auf die genannten Felder.

$select=name,description

$expand

Lädt verknüpfte Entitäten inline mit (reduziert Anzahl der Anfragen).

$expand=Datastreams

$filter

Filtert Ergebnisse anhand logischer Ausdrücke.

$filter=result gt 30

Pagination

Der FROST‑Server liefert standardmäßig eine begrenzte Anzahl von Entitäten pro Anfrage (serverseitige Pagination). Enthält die Antwort mehr Daten als das Limit erlaubt, wird im JSON ein Feld @iot.nextLink ausgegeben, das die URL für die nächste Seite enthält.

# Erste Seite mit 100 Einträgen
curl -s "{frost_server_url}/Observations?\$top=100&\$count=true"

# Nächste Seite manuell abrufen
curl -s "{frost_server_url}/Observations?\$top=100&\$skip=100"
Programmatische Clients sollten das @iot.nextLink‑Feld auswerten und iterativ abrufen, bis kein weiterer Link mehr vorhanden ist.

Filter‑Ausdrücke

Operator Bedeutung Beispiel

eq

Gleichheit

$filter=name eq 'Temperatur'

ne

Ungleichheit

$filter=name ne 'Temperatur'

gt / ge

Größer als / Größer oder gleich

$filter=result gt 25

lt / le

Kleiner als / Kleiner oder gleich

$filter=result le 100

and / or

Logische Verknüpfung

$filter=result gt 20 and result lt 30

substringof

Teilzeichenkette prüfen

$filter=substringof('Temperatur', name)

startswith

Anfangszeichenkette prüfen

$filter=startswith(name, 'CO2')

Expand mit verschachtelter Abfrage

$expand kann mit Unter‑Query‑Optionen kombiniert werden, um gezielt verknüpfte Daten einzugrenzen.

# Datastream mit den letzten 5 Observations
curl -s "{frost_server_url}/Datastreams(1)?\$expand=Observations(\$top=5;\$orderby=phenomenonTime desc)"

# Things mit expandierten Datastreams und deren ObservedProperty
curl -s "{frost_server_url}/Things?\$expand=Datastreams(\$expand=ObservedProperty)"
Für komplexe und tief verschachtelte Abfragen konsultieren Sie die offizielle Dokumentation unter https://fraunhoferiosb.github.io/FROST-Server/settings/queryDefaults.html.

Praxisbeispiele

# Alle Things mit ihren Standorten und der Anzahl
curl -s "{frost_server_url}/Things?\$expand=Locations&\$count=true"

# Observations eines Datastreams in einem Zeitfenster, absteigend, auf 50 begrenzt
curl -s "{frost_server_url}/Datastreams(1)/Observations?\$filter=phenomenonTime ge 2024-06-01T00:00:00Z and phenomenonTime le 2024-06-30T23:59:59Z&\$orderby=phenomenonTime desc&\$top=50&\$count=true"

# Nur Name und Beschreibung aller Sensors
curl -s "{frost_server_url}/Sensors?\$select=name,description"

# Things, deren Name mit 'KSPB' beginnt
curl -s "{frost_server_url}/Things?\$filter=startswith(name,'KSPB')"

# Die jüngste Observation überhaupt — dieselbe Abfrage, die die Erreichbarkeitsprüfung stellt
curl -s "{frost_server_url}/Observations?\$orderby=phenomenonTime desc&\$top=1"

System‑Endpunkte

Neben den Entity‑Endpunkten stellt der FROST‑Server System‑Endpunkte bereit, die für Betrieb und Monitoring relevant sind. Sie liegen unterhalb der Service‑Root, also nicht unter /v1.1.

Endpunkt Beschreibung

/

Willkommensseite des FROST‑Servers (HTML).

/v1.1

Service‑Root – listet alle verfügbaren Entity‑Sets auf (JSON). Dies ist der Endpunkt, den die Erreichbarkeitsprüfung des Adapters abfragt.

/DatabaseStatus

Status der Datenbankverbindung. Zugleich die Admin‑Seite, über die eine neue Instanz ihr Schema initialisiert (FROST‑Instanz bereitstellen).
In Kubernetes‑Umgebungen eignet sich /DatabaseStatus als Liveness‑ oder Readiness‑Probe für den FROST‑Server‑Pod.

Weiterführende Referenzen