Data Operations · NGSI-LD und Stellio

Stellio Create Subscription

Der Node erzeugt eine NGSI-LD-Subscription, die den Broker anweist, bei neuen oder geänderten Entitäten eines Typs eine Benachrichtigung an eine URL zu senden, typischerweise an eine Zeitreihendatenbank. Vor dem Anlegen prüft er, ob für den Typ bereits eine Subscription existiert, und vermeidet so Duplikate.

• Subscriptions
• Anlegen
• NGSI-LD

Node-Typ

stellio-create-subscription

Paket

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

Eingänge / Ausgänge

1 / 1

Ziel

Stellio Context Broker (NGSI-LD)

Wofür Sie den Node verwenden

Damit historische Werte in einer Zeitreihendatenbank landen, muss der Context Broker über jede Änderung informieren. Das übernimmt eine Subscription je Entitätstyp. Dieser Node richtet sie mit einer bewährten Standardkonfiguration ein: Er beobachtet ein oder mehrere Attribute, löst bei angelegten und aktualisierten Entitäten aus und liefert Benachrichtigungen im normalisierten Format.

Typische Einsatzfälle sind:

• Zeitreihen aufbauen: nach dem ersten Import eines neuen Entitätstyps eine Subscription zur Zeitreihendatenbank (zum Beispiel QuantumLeap) anlegen.
• Deployment-Flows: beim Start eines Flows per Inject-Node sicherstellen, dass die Subscription vorhanden ist, ohne sie bei jedem Lauf zu duplizieren.
• Mehrere Typen: den Entitätstyp per msg.dataModel übergeben und in einer Schleife mehrere Subscriptions anlegen.

So funktioniert der Node

1

Konfiguration prüfen

API URL, Tenant und Data Model müssen vorliegen; Platzhalter in URLs werden aus Umgebungsvariablen ersetzt.

→

2

Duplikate prüfen

Der Node prüft, ob im Tenant bereits eine Subscription für den Entitätstyp existiert.

→

3

Anlegen oder melden

Existiert keine passende Subscription, wird sie per POST angelegt; sonst meldet der Node die vorhandene ID.

→

4

Ergebnis ausgeben

msg.payload enthält die ID und den Status created oder exists.

Ergebnis: Genau eine aktive Subscription je Entitätstyp, deren ID im Flow weiterverwendet werden kann.

Der Node ist nachrichtenbasiert und arbeitet je eingehender Nachricht einmal den oben beschriebenen Ablauf ab.

Konfiguration

Feld	Typ	Standard	Bedeutung
Name	Text	leer	Anzeigename des Nodes im Flow.
NGSILD-Tenant	Text (Pflicht)	leer	Wert des Headers NGSILD-Tenant, zum Beispiel ds_public_parking.
API URL	Text	${STELLIO_API_URL}	Basis-URL des Brokers. Platzhalter ${VAR} werden zur Laufzeit aus Umgebungsvariablen ersetzt.
Data Model	Text (Pflicht)	leer	Entitätstyp, für den die Subscription gilt, zum Beispiel OffStreetParking.
Watched Attr.	Text	dateObserved	Beobachtete Attribute, kommagetrennt. Nur Änderungen an diesen Attributen lösen eine Benachrichtigung aus; so vermeiden Sie doppelte Meldungen.
Notify URL	Text	siehe unten	Empfänger der Benachrichtigungen. Der Standard verweist auf den Notify-Endpunkt einer QuantumLeap-Instanz. Platzhalter werden ersetzt.
Context URL	Text	siehe unten	JSON-LD-Kontext, der in das Feld @context der Subscription geschrieben wird. Platzhalter werden ersetzt.

Standardwerte der URL-Felder:

Notify URL:  ${QL_LD_API_URL}/v2/notify
Context URL: https://context.${DOMAIN}/main-context.jsonld

Eingang

Eigenschaft	Typ	Bedeutung
msg.tenant	Text	Überschreibt den konfigurierten Tenant.
msg.dataModel	Text	Überschreibt das konfigurierte Data Model (Entitätstyp).
msg.payload	beliebig	Wird nicht ausgewertet; die Nachricht dient nur als Auslöser.

Ausgang

Beim Anlegen einer neuen Subscription enthält msg.payload:

{
  "id": "urn:ngsi-ld:Subscription:7f3a2c1e-0000-4000-8000-000000000001",
  "status": "created",
  "response": ""
}

Existiert bereits eine Subscription für den Typ:

{
  "id": "urn:ngsi-ld:Subscription:7f3a2c1e-0000-4000-8000-000000000001",
  "status": "exists"
}

Feld	Bedeutung
id	URN der neu angelegten Subscription aus dem Location-Header des Brokers beziehungsweise der bereits vorhandenen Subscription. Fehlt der Header, steht hier created.
status	created (neu angelegt) oder exists (bereits vorhanden, nichts geändert).
response	Nur bei created: Antwortkörper des Brokers, bei Stellio in der Regel leer.

Die angelegte Subscription hat folgende Struktur (Beispiel für WeatherObserved):

{
  "type": "Subscription",
  "subscriptionName": "Subscription for entity type WeatherObserved.",
  "description": "This subscription triggers everytime an entity from type WeatherObserved is updated. Only watching attribute dateObserved to avoid duplications.",
  "entities": [{"type": "WeatherObserved"}],
  "watchedAttributes": ["dateObserved"],
  "notificationTrigger": ["entityCreated", "attributeCreated", "attributeUpdated"],
  "notification": {
    "format": "normalized",
    "endpoint": {"uri": "https://quantumleap.beispielstadt.example/v2/notify", "accept": "application/json"}
  },
  "@context": ["https://context.beispielstadt.example/main-context.jsonld"]
}

Beispiel-Flow

Das Paket bringt einen gemeinsamen Beispiel-Flow für mehrere Stellio-Nodes mit. Sie importieren ihn in Node-RED über Menü → Importieren → Beispiele → @htag/node-red-contrib-hypertegrity-ngsi-ld → stellio-helper-nodes. Alternativ laden Sie die Datei stellio-helper-nodes.json herunter und importieren sie über Menü → Importieren.

Schritt 1

Inject

Ein Inject-Node löst das Anlegen manuell aus, zum Beispiel einmalig nach der Bereitstellung des Flows.

Schritt 2

Create Subscription

Der Node legt eine Subscription für OffStreetParking an, die das Attribut accessModified beobachtet.

Schritt 3

Debug

Ein Debug-Node zeigt ID und Status (created oder exists) an.

Beispiel-Flow als JSON anzeigen (Ausschnitt Create Subscription)

[
  {"id": "tab1", "type": "tab", "label": "Stellio Helper Nodes", "disabled": false, "info": ""},
  {"id": "inject1", "type": "inject", "z": "tab1", "name": "", "props": [{"p": "payload"}], "repeat": "", "once": false, "payload": "", "payloadType": "date", "x": 100, "y": 540, "wires": [["create1"]]},
  {"id": "create1", "type": "stellio-create-subscription", "z": "tab1", "name": "", "tenant": "ds_public_parking", "apiUrl": "${STELLIO_API_URL}", "dataModel": "OffStreetParking", "watchedAttributes": "accessModified", "notificationUrl": "${QL_LD_API_URL}/v2/notify", "contextUrl": "https://context.${DOMAIN}/main-context.jsonld", "x": 290, "y": 540, "wires": [["debug1"]]},
  {"id": "debug1", "type": "debug", "z": "tab1", "name": "Subscription", "active": true, "tosidebar": true, "complete": "false", "x": 510, "y": 540, "wires": []}
]

Status und Fehler

Anzeige	Bedeutung
Blauer Punkt „checking...“	Vorhandene Subscriptions werden geladen.
Blauer Punkt „creating...“	Die neue Subscription wird angelegt.
Grüner Punkt „created“	Subscription erfolgreich angelegt.
Gelber Punkt „exists“	Für den Typ existiert bereits eine Subscription. Zusätzlich erscheinen die Warnungen „There is already a subscription for this type.“ und „Subscription already exists for type …“.
Roter Ring „error“ mit Fehlermeldung	Der Broker hat mit einem Fehlerstatus geantwortet (zum Beispiel „Request failed with status code 400“) oder ist nicht erreichbar. Es wird keine Nachricht gesendet.
Fehler „Missing required configuration (API URL, Tenant, or Data Model)“	Mindestens eine Pflichtangabe fehlt. Es wird keine Nachricht gesendet.

Typische Statuscodes des Brokers: 201 (angelegt), 400 (ungültiger Subscription-Körper oder Kontext), 409 (ID bereits vergeben). Fehler werden über node.error gemeldet und können mit einem Catch-Node abgefangen werden.

Hinweise

• Duplikatprüfung: Vor dem Anlegen prüft der Node, ob bereits eine Subscription für den Entitätstyp existiert, und legt in diesem Fall keine neue an.
• Benachrichtigungsformat: Benachrichtigungen werden normalisiert und als application/json gesendet. Der Empfänger muss den NGSI-LD-Kontext selbst auflösen können.
• Authentifizierung: Der Node sendet keine Authentifizierungs-Header; der Zugriff auf den Broker wird über das Netzwerk oder ein vorgeschaltetes Gateway geschützt.
• Platzhalter: ${STELLIO_API_URL}, ${QL_LD_API_URL} und ${DOMAIN} müssen als Umgebungsvariablen des Node-RED-Prozesses gesetzt sein, sonst bleiben die Platzhalter im Text stehen und die Requests schlagen fehl.
• Personenbezogene Daten: Die Subscription selbst enthält keine personenbezogenen Daten. Beachten Sie jedoch, dass über sie alle Entitätsänderungen des Typs an den Empfänger weitergeleitet werden.

Weiterführende Themen

Referenzen