Zum Hauptinhalt springen
Data Operations

NGSI-LD und Stellio

Das Paket bildet den Kern der Bibliothek: Der NGSI-LD Builder formt beliebige JSON-Daten anhand von Smart Data Models in normalisierte NGSI-LD-Entitäten um, Post to Stellio schreibt sie in den Context Broker, und sechs Stellio-Nodes fragen Entitäten, Typen und Subscriptions ab oder verwalten sie. Alle Nodes sind auf den Stellio Context Broker ausgelegt, sprechen aber die standardisierte NGSI-LD-API.

Paket
@htag/node-red-contrib-hypertegrity-ngsi-ld
Version
0.3.1
Nodes
8
Lizenz
EUPL-1.2

Enthaltene Nodes​

Die Nodes decken den gesamten Weg vom Rohdatensatz bis zur verwalteten Entität im Broker ab. In der Palette finden Sie den Builder in der Kategorie DataOps, die übrigen Nodes in der Kategorie Stellio.

Entitäten erzeugen und veröffentlichen​

ngsi-builder

NGSI-LD Builder

Formt flache JSON-Objekte anhand eines Smart Data Models in NGSI-LD-Entitäten mit URN-ID, @context, GeoProperty, Relationship und observedAt um.

Node öffnen
post-to-stellio

Post to Stellio

Überträgt ein Entitäten-Array per Batch-Upsert in einen Tenant des Stellio Context Brokers.

Node öffnen

Entitäten abfragen​

stellio-entities

Stellio Entities

Fragt Entitäten nach Typ, Filter und ID-Muster ab, liest einzelne Entitäten, zählt Treffer und löscht einzeln oder als Stapel.

Node öffnen
stellio-types

Stellio Types

Ermittelt lesend, welche Entitätstypen und Attribute im Broker vorhanden sind, inklusive Details und Instanzanzahl.

Node öffnen

Subscriptions verwalten​

stellio-subscriptions

Stellio Subscriptions

Listet, liest, aktiviert, deaktiviert und löscht Subscriptions über einen einzigen Node mit Browser-Registerkarte.

Node öffnen
stellio-create-subscription

Stellio Create Subscription

Legt eine Subscription für einen Entitätstyp an, sofern noch keine existiert, zum Beispiel zur Anbindung einer Zeitreihendatenbank.

Node öffnen
stellio-get-subscriptions

Stellio Get Subscriptions

Ruft die Liste aller Subscriptions eines Tenants ab.

Node öffnen
stellio-delete-subscription

Stellio Delete Subscription

Löscht eine einzelne Subscription anhand ihrer ID.

Node öffnen

Installation​

npm install @htag/node-red-contrib-hypertegrity-ngsi-ld

Alternativ installieren Sie das Paket im Node-RED-Editor über Menü → Palette verwalten → Installieren und suchen dort nach @htag/node-red-contrib-hypertegrity-ngsi-ld. Das Paket setzt Node-RED ab Version 4.0.5 und Node.js ab Version 20.18 voraus.

Gemeinsame Verbindungseinstellungen​

Alle Stellio-Nodes sprechen denselben Broker und verwenden dafür ein einheitliches Schema aus Broker-URL, Tenant und Kontext. Werte aus der Nachricht haben stets Vorrang vor der Node-Konfiguration; diese wiederum hat Vorrang vor Umgebungsvariablen.

Broker-URL​

EinstellungBedeutung
Feld API URL (Post to Stellio: Stellio API URL)Basis-URL des Brokers, zum Beispiel https://stellio.beispielstadt.example. Der Node hängt selbst den Pfad /ngsi-ld/v1/… an.
Platzhalter ${STELLIO_API_URL}Standardwert der meisten Dialoge. Platzhalter der Form ${VAR} werden zur Laufzeit aus der gleichnamigen Umgebungsvariable des Node-RED-Prozesses ersetzt.
Umgebungsvariable STELLIO_API_URLRückfallwert, wenn weder Nachricht noch Konfiguration eine URL liefern.
msg.apiUrlÜberschreibt die URL je Nachricht. Bei Post to Stellio heißt die Eigenschaft msg.stellioApiUrl.

Tenant​

Der Tenant trennt Datenräume innerhalb eines Brokers. Alle Nodes senden ihn als HTTP-Header NGSILD-Tenant; msg.tenant überschreibt den konfigurierten Wert. Bei Post to Stellio, Stellio Create Subscription, Stellio Get Subscriptions und Stellio Delete Subscription ist der Tenant ein Pflichtfeld. Bei Stellio Entities, Stellio Types und Stellio Subscriptions darf er leer bleiben; dann wird kein Header gesendet und der Broker verwendet seinen Standard-Tenant.

Authentifizierung​

Die Nodes dieses Pakets senden keine Authentifizierungs-Header; der Zugriff auf den Broker wird über das Netzwerk oder ein vorgeschaltetes Gateway geschützt. Die Browser-Registerkarten der Nodes Stellio Entities, Stellio Types und Stellio Subscriptions sind über die Node-RED-Berechtigungen stellio.read (Anzeigen) und stellio.write (Löschen, Aktivieren, Deaktivieren) abgesichert; der NGSI-LD Builder nutzt ngsi-builder.read und ngsi-builder.write für Schema-Abruf und Cache-Löschung.

JSON-LD-Kontext (@context)​

NodeUmgang mit dem Kontext
NGSI-LD BuilderSchreibt die Kontext-URL als Array in das Feld @context jeder erzeugten Entität und lädt daraus das Schema für Mapping und Validierung. Standard: https://context.${DOMAIN}/main-context.
Post to StellioSendet den Payload als application/ld+json; der Kontext muss in den Entitäten enthalten sein. Es wird kein Link-Header gesetzt.
Stellio Entities, Stellio Types, Stellio SubscriptionsSenden das Feld Context als HTTP-Header Link mit rel="http://www.w3.org/ns/json-ld#context". Der Kontext bestimmt, ob Typ- und Attributnamen in der Antwort kurz oder als vollständige URIs erscheinen. msg.contextUrl überschreibt den Wert. Standard: https://context.${DOMAIN}/main-context.jsonld.
Stellio Create SubscriptionSchreibt die Context URL in das Feld @context der angelegten Subscription.
Stellio Get Subscriptions, Stellio Delete SubscriptionSenden keinen Kontext.

Verwenden Sie beim Lesen denselben Kontext wie beim Schreiben, damit Attributnamen übereinstimmen. Der Platzhalter ${DOMAIN} muss als Umgebungsvariable gesetzt sein.

Weitere gemeinsame Eigenschaften​

  • Antwortformat: Alle Stellio-Nodes schreiben die Broker-Antwort in msg.payload sowie den HTTP-Status in msg.statusCode und die Antwort-Header in msg.headers. Stellio Entities, Stellio Types und Stellio Subscriptions senden die Nachricht auch bei Fehlerstatus weiter und zeigen den Status als gelben Ring an.
  • Zeitüberschreitung: Stellio Entities, Stellio Types und Stellio Subscriptions brechen Requests nach 30 Sekunden ab.
  • Platzhalter: Die Standardwerte nutzen ${STELLIO_API_URL}, ${DOMAIN} und ${QL_LD_API_URL}. Setzen Sie diese Umgebungsvariablen für den Node-RED-Prozess.

Gemeinsame Hinweise​

  • Abhängigkeiten: Das Paket benötigt die Bibliothek axios (Version 1.13 oder neuer), die bei der Installation automatisch mitinstalliert wird. Der NGSI-LD Builder lädt im Editor zusätzlich die Kartenbibliothek Leaflet von unpkg.com; ohne Internetzugang des Browsers fehlt lediglich die Kartenvorschau.
  • Netzwerkzugriff des Servers: Der Node-RED-Server muss die Kontext-URL, die Schema-URLs der Smart Data Models und den Broker erreichen können. Hinter einem Proxy setzen Sie die üblichen Proxy-Umgebungsvariablen.
  • Beispiel-Flows: Das Paket enthält die Beispiele ngsi-builder und stellio-helper-nodes (Menü → Importieren → Beispiele). Der Beispiel-Flow für den Builder enthält mehrere tausend Luftqualitäts-Datensätze eines Satellitendienstes und ist entsprechend groß.
  • Datenschutz: Die Nodes entfernen keine Inhalte und protokollieren im Debug-Modus vollständige Nachrichten. Prüfen Sie vor dem Veröffentlichen, ob Entitäten personenbezogene Daten enthalten (Namen, Adressen, Fahrzeugkennzeichen), und wählen Sie den Ziel-Tenant entsprechend.
  • Einheiten: Die Nodes übernehmen Werte unverändert und setzen keinen unitCode. Konvertieren Sie Messwerte vor dem Builder in metrische Einheiten.