Kontextdaten

NGSI-LD

NGSI-LD beschreibt urbane Objekte als Entitäten mit Eigenschaften und Beziehungen. Stellio führt den aktuellen Kontext; APISIX veröffentlicht und schützt den externen Zugang.

Standard

ETSI NGSI-LD

Komponente

Stellio Context Broker

Basis-URL

https://api.<DOMAIN>/stellio/api/ngsi-ld/v1/

Zugriff

OAuth-Scopes und NGSILD-Tenant

Wann NGSI-LD der richtige Zugang ist

Verwenden Sie NGSI-LD für aktuelle Zustände und Beziehungen urbaner Objekte – beispielsweise Gebäude, Fahrzeuge, Ladepunkte, Straßenabschnitte oder Verwaltungsobjekte. Für SensorThings-Ressourcen und zeitlich geordnete Observations ist dagegen die SensorThings API vorgesehen.

Externer Pfad und erforderliche Header

Der öffentliche Plattformpfad lautet:

https://api.<DOMAIN>/stellio/api/ngsi-ld/v1/

APISIX entfernt den Präfix /stellio/api/ und leitet die verbleibende NGSI-LD-Route an Stellio weiter.

Authorization: Bearer <TOKEN>
NGSILD-Tenant: <DATENRAUM>
Accept: application/ld+json

Für schreibende JSON-LD-Anfragen wird zusätzlich Content-Type: application/ld+json verwendet. Bei kompakten Payloads kann der JSON-LD-Kontext über einen Link-Header oder @context angegeben werden.

Zentrale Ressourcen

Ressource	Aufgabe	Typische Operationen
/entities	Entitäten erzeugen und abfragen	POST, GET
/entities/{entityId}	einzelne Entität lesen oder löschen	GET, DELETE
/entities/{entityId}/attrs	Attribute ergänzen oder aktualisieren	POST, PATCH
/subscriptions	Änderungen abonnieren	POST, GET, PATCH, DELETE
/entityOperations/*	mehrere Entitäten gemeinsam verarbeiten	Batch-Operationen

Die genaue Verfügbarkeit einzelner Operationen richtet sich nach der im Plattformrelease enthaltenen Stellio-Version.

Entität anlegen

curl --fail --show-error \
  --request POST \
  "https://api.<DOMAIN>/stellio/api/ngsi-ld/v1/entities" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "NGSILD-Tenant: <DATENRAUM>" \
  --header "Content-Type: application/ld+json" \
  --data '{
    "id": "urn:ngsi-ld:WeatherObserved:station-001",
    "type": "WeatherObserved",
    "temperature": {
      "type": "Property",
      "value": 18.7
    },
    "@context": [
      "https://context.<DOMAIN>/contexts/weather.jsonld"
    ]
  }'

Für POST, PUT und PATCH benötigt das Token api:write. DELETE erfordert api:delete.

Entitäten abfragen

curl --fail --show-error \
  --get \
  "https://api.<DOMAIN>/stellio/api/ngsi-ld/v1/entities" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "NGSILD-Tenant: <DATENRAUM>" \
  --header "Accept: application/ld+json" \
  --data-urlencode "type=WeatherObserved" \
  --data-urlencode "limit=100"

GET-Anfragen benötigen api:read. Filter, Pagination, Geoqueries und Attributauswahl folgen der NGSI-LD-Spezifikation.

Subscriptions und Historisierung

Subscriptions veranlassen Stellio, bei passenden Änderungen einen konfigurierten Empfänger aufzurufen. Der Callback ist damit Teil der eigenen Integrationsarchitektur und muss von Stellio erreichbar sowie angemessen abgesichert sein.

Stellio führt den aktuellen Kontext. Ist QuantumLeap aktiviert, können Kontextänderungen zusätzlich historisiert werden. Die historische Ablage ersetzt weder die aktuelle Entity API noch die SensorThings-Observations.

Datenräume und Rechte

APISIX vergleicht den Header NGSILD-Tenant mit dem tenants-Claim des Access Tokens. Ein passender OAuth-Scope allein genügt daher nicht. Details enthält Authentifizierung und API-Zugriff.

Technische Abhängigkeiten

• Stellio Context Broker führt Entitäten und Beziehungen.
• APISIX veröffentlicht und schützt die Route.
• Keycloak stellt Token, Scopes und Datenraum-Claims bereit.
• Context Hoster kann versionierte JSON-LD-Kontexte bereitstellen.
• PostgreSQL und Kafka sind interne Laufzeitabhängigkeiten und keine alternativen öffentlichen Datenzugänge.

Vollständige API-Referenz

ETSI pflegt die vollständige OpenAPI-Spezifikation für NGSI-LD. Sie enthält neben den Entity-Endpunkten unter anderem Subscriptions, Batch-Operationen, temporale Abfragen und Context-Source-Operationen. Für die versionierte UDSP-Dokumentation 3.1 ist die externe Referenz auf ETSI NGSI-LD 1.7.1 fixiert. Der UDSP-spezifische Serverpfad, die Authentifizierung und der Datenraum-Header sind auf dieser Seite beschrieben.

Externe Referenz

ETSI NGSI-LD API 1.7.1

Die von ETSI gepflegte Referenz mit Endpunkten, Parametern, Payloads und Rückgabecodes.

Swagger-UI bei ETSI öffnen ↗