Sensor- und IoT-Daten

OGC SensorThings API

FROST verwaltet SensorThings-Ressourcen und zeitlich geordnete Observations. Der geschützte Plattformzugang wird über APISIX bereitgestellt.

Standard

OGC SensorThings API 1.1

Komponente

FROST-Server

HTTP-Basis-URL

https://api.<DOMAIN>/frost-http/v1.1/

Weitere Zugänge

WebSocket; optional MQTT

Wann SensorThings der richtige Zugang ist

Verwenden Sie SensorThings, wenn Messsystem, beobachtete Größe, Datenstrom und einzelne Messwerte gemeinsam beschrieben werden sollen. Im Unterschied zu NGSI-LD sind zeitlich geordnete Observations bereits Bestandteil des fachlichen Modells.

Ressourcenmodell

Thing
  ├─ Location
  └─ Datastream
       ├─ Sensor
       ├─ ObservedProperty
       └─ Observation
            └─ FeatureOfInterest

Ressource	Bedeutung
Things	physische oder virtuelle Beobachtungsobjekte
Locations	räumliche Zuordnung eines Things
Sensors	Messverfahren oder Messgerät
ObservedProperties	fachlich beobachtete Größe
Datastreams	Verbindung zwischen Thing, Sensor und Messgröße
Observations	einzelner Messwert mit Zeitbezug
FeaturesOfInterest	das konkret beobachtete Objekt

Geschützter HTTP-Zugang

Der kanonische Plattformpfad lautet:

https://api.<DOMAIN>/frost-http/v1.1/

APISIX schreibt diesen Präfix intern auf /FROST-Server/ um. Verwenden Sie in externen Integrationen deshalb nicht den internen Servicepfad.

curl --fail --show-error \
  --get \
  "https://api.<DOMAIN>/frost-http/v1.1/Things" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Accept: application/json" \
  --data-urlencode '$expand=Datastreams/Observations($orderby=phenomenonTime desc;$top=1)' \
  --data-urlencode '$top=20'

Für lesende Zugriffe ist api:read erforderlich. Schreibende Operationen benötigen api:write, Löschvorgänge api:delete.

OData-Abfragen

SensorThings verwendet OData-Queryparameter. Besonders relevant sind:

Parameter	Zweck
$filter	Ressourcen nach Eigenschaften oder Zeiträumen filtern
$select	ausgegebene Felder begrenzen
$expand	verknüpfte Ressourcen gemeinsam laden
$orderby	Ergebnisse sortieren
$top und $skip	Pagination steuern

Komplexe $expand-Abfragen können große Antworten erzeugen. Integrationen sollten benötigte Felder begrenzen und Pagination berücksichtigen.

Observation schreiben

curl --fail --show-error \
  --request POST \
  "https://api.<DOMAIN>/frost-http/v1.1/Observations" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "phenomenonTime": "2026-07-31T10:00:00Z",
    "result": 18.7,
    "Datastream": {"@iot.id": 42}
  }'

WebSocket und MQTT

Bei aktiviertem FROST-MQTT-Modul richtet die Plattform zusätzlich einen WebSocket-Zugang über APISIX ein:

wss://api.<DOMAIN>/frost-wss

Das MQTT-Modul stellt clusterseitig Ports für MQTT (1883) und WebSocket (9876) bereit. Seine externe Erreichbarkeit hängt jedoch von der konkreten Cluster-, NodePort- und Firewall-Konfiguration ab. Aus mqtt_enable: true folgt daher nicht automatisch ein öffentlich erreichbarer MQTT-Broker.

Direkter Komponenten-Ingress

Das aktuelle FROST-Deployment erzeugt zusätzlich den Host https://frost.<DOMAIN>/FROST-Server/. Für kontrollierte Plattformintegrationen sollte der geschützte APISIX-Pfad verwendet werden. Ob und für wen der direkte Host erreichbar sein darf, ist eine bewusste Betriebs- und Sicherheitsentscheidung.

Technische Abhängigkeiten

• FROST-Server stellt das SensorThings-Modell bereit.
• APISIX veröffentlicht HTTP und WebSocket.
• Keycloak liefert die OAuth-Scopes.
• PostgreSQL/PostGIS persistiert die Ressourcen intern.
• Das optionale FROST-MQTT-Modul stellt den MQTT-Zugang bereit; Mosquitto dient innerhalb des FROST-Stacks ausschließlich als interner Message Bus.

Offizielle Referenzen

Der OGC-Standard ist die verbindliche Referenz für Ressourcen, Operationen und Abfrageparameter der SensorThings API 1.1. Die FROST-Dokumentation ergänzt implementierungsspezifische Beispiele und Hinweise. Der von FROST optional bereitgestellte OpenAPI-Endpunkt ist laut Projektdokumentation noch experimentell und wird deshalb hier nicht als vollständige API-Referenz verwendet.

OGC-Standard

SensorThings API 1.1

Normative Spezifikation der SensorThings API Part 1: Sensing in Version 1.1.

OGC-Standard öffnen ↗

Implementierung

FROST-Server

Offizielle Hinweise und Beispiele zur SensorThings-Implementierung des FROST-Servers.

FROST-Dokumentation öffnen ↗