Zum Hauptinhalt springen
Administration · Datenmodelle

Context Hoster verwalten

Der Context Hoster wird wie eine versionierte Konfiguration gepflegt. Administratoren bearbeiten Modell- und Kontextdateien direkt in GitLab, lassen die Änderung prüfen und stellen sie nach dem Merge automatisch in der UDSP bereit.

Ein fachlich abgestimmtes Datenmodell und sein JSON-LD-Kontext sind im zentralen Repository nachvollziehbar gepflegt. Nach Review und Merge sind die Dateien über eine stabile Context-Hoster-URL erreichbar und können in NGSI-LD-Payloads verwendet werden.

Einordnung

Dateien bestimmen

Vorhandenes Modell, Erweiterung oder eigener Kontext werden dem passenden Verzeichnis zugeordnet.

GitLab

Dateien bearbeiten

JSON- und JSON-LD-Dateien werden direkt im Browser geändert oder neu angelegt.

Freigabe

Review durchführen

Ein Merge Request bündelt fachliche und technische Prüfung der Änderung.

Auslieferung

Kontext prüfen

Nach erfolgreicher Pipeline wird das neue Image übernommen und die öffentliche URL kontrolliert.

Vor der Änderung​

Die Auswahl des Datenmodells und die Bedeutung neuer Attribute müssen bereits fachlich abgestimmt sein. Die Context-Hoster-Administration veröffentlicht diese Entscheidung; sie ersetzt nicht die fachliche Modellierung.

Fachliche Vorarbeit

Mapping in der Verarbeitung

Für ein NGSI-LD-Ziel sind Entitätstyp, Attribute, Einheiten und notwendige Erweiterungen festgelegt.

Verarbeitung öffnen
Arbeitszugang

GitLab-Berechtigung

Sie dürfen im Context-Hoster-Projekt einen Branch und Merge Request erstellen.

Prüfgrundlage

Beispiel-Payload

Eine repräsentative NGSI-LD-Entität zeigt, welche Begriffe tatsächlich benötigt werden.

Ziel

Mandantendomain

Die vorgesehene Context-Hoster-Adresse der Zielumgebung ist bekannt.

1. Passende Dateien bestimmen​

Öffnen Sie das NGSI-LD Context Hoster Repository und prüfen Sie zuerst die vorhandenen Dateien. Legen Sie nichts neu an, wenn Modell und Begriffe bereits passend veröffentlicht werden.

Offizielles Modell

dataModels

Enthält übernommene Schemata der Smart Data Models, gegliedert nach Kategorie und Modellname.

Eigenes Modell

customDataModels

Enthält Schemata für fachlich begründete Modelle, die nicht in den Smart Data Models vorkommen.

Gemeinsamer Kontext

context

Enthält den zentralen Einstiegskontext und Definitionen gemeinsam verwendeter zusätzlicher Felder.

Eigener Kontext

customContext

Enthält eigene Kontext- und Felddateien bei bewusst abweichender fachlicher Semantik.

Datei oder VerzeichnisWann wird es verwendet?
dataModels/<Kategorie>/<Modell>.jsonDas Modell stammt aus den Smart Data Models.
customDataModels/<Kategorie>/<Modell>.jsonEs wurde ein eigenes, fachlich begründetes Modell definiert.
context/main-context.jsonldModelltypen und gemeinsam verwendete Begriffe werden über den zentralen Kontext bereitgestellt.
context/custom-fields.jsonldEin zusätzliches Feld soll mit eindeutiger Bedeutung gemeinsam verwendet werden.
customContext/<Modell>-context.jsonldEin Modell benötigt einen bewusst getrennten Kontext.
customContext/<Modell>-fields.jsonldDie Begriffe des getrennten Kontexts werden definiert.
Gemeinsamen Kontext bevorzugen

Verwenden Sie main-context.jsonld, wenn ein vorhandenes Modell übernommen, nur gezielt erweitert oder aus bestehenden Begriffen kombiniert wird. Ein eigener Kontext ist nur sinnvoll, wenn gleich benannte Begriffe bewusst eine andere fachliche Bedeutung besitzen.

2. Datei direkt in GitLab bearbeiten​

Für die übliche Änderung benötigen Sie keine lokale Entwicklungsumgebung und keine Konsolenbefehle:

  1. Öffnen Sie im Repository über Code die gewünschte Datei.
  2. Wählen Sie Edit und anschließend Edit single file.
  3. Ergänzen Sie den neuen Modelltyp oder das neue Feld an der vorgesehenen Stelle.
  4. Kontrollieren Sie in der Vorschau beziehungsweise im Diff, dass keine bestehenden Einträge unbeabsichtigt verändert wurden.
  5. Tragen Sie unter Commit message eine kurze, fachlich verständliche Beschreibung ein.
  6. Wählen Sie Create a new branch and start a merge request und übernehmen Sie den von GitLab vorgeschlagenen Branch oder vergeben Sie einen eindeutigen Namen.
  7. Starten Sie den Merge Request und ergänzen Sie darin Zweck, verwendetes Modell und einen Beispiel-Payload.

Eine neue Datei anlegen​

Soll ein neues Schema oder ein eigener Kontext ergänzt werden, öffnen Sie im Repository das Zielverzeichnis und wählen Sie über das Plus-Symbol die Aktion New file. Der Dateiname enthält bei Bedarf den vollständigen Unterordner, beispielsweise:

dataModels/Environment/MeinModell.json

GitLab kann damit Datei und noch nicht vorhandene Unterordner gemeinsam anlegen. Committen Sie auch diese Änderung in einen neuen Branch und nicht direkt nach main.

Einen Begriff zum gemeinsamen Kontext ergänzen​

Ein zusätzliches Feld benötigt zwei zusammenpassende Änderungen:

  1. context/main-context.jsonld ordnet den verwendeten Begriff seiner Definition zu.
  2. context/custom-fields.jsonld beschreibt dessen eindeutige fachliche Bedeutung.

Das folgende Beispiel zeigt nur die zu ergänzenden Einträge, nicht den vollständigen Inhalt der Dateien:

context/main-context.jsonld
{
  "@context": {
    "MeinModell": "https://context.{{ DOMAIN }}/dataModels/<Kategorie>/MeinModell",
    "meinFeld": "https://context.{{ DOMAIN }}/custom-fields.jsonld#/definitions/meinFeld"
  }
}
context/custom-fields.jsonld
{
  "definitions": {
    "meinFeld": "Eindeutige fachliche Beschreibung des Feldes."
  }
}

Fügen Sie neue Begriffe alphabetisch in die vorhandenen Objekte ein. Datenmodellnamen beginnen gemäß Repository-Konvention mit einem Großbuchstaben; Kontextfelder werden kleingeschrieben. Verwenden Sie für lokale Links den vorhandenen Platzhalter {{ DOMAIN }}.

3. Merge Request prüfen und freigeben​

Prüfen Sie im GitLab-Diff gemeinsam:

  • Sind JSON und JSON-LD syntaktisch vollständig?
  • Stimmen Kategorie, Modellname und Dateiname überein?
  • Ist die Bedeutung jedes neuen Attributs eindeutig beschrieben?
  • Werden vorhandene Begriffe weiterhin mit derselben Bedeutung verwendet?
  • Zeigen lokale Schema- und Kontextverweise auf {{ DOMAIN }}?
  • Passen Schema, Kontext und Beispiel-Payload zusammen?
  • Bleiben bereits verwendete Kontext-URLs kompatibel?

Der Merge Request sollte von einer fachlich verantwortlichen und einer technisch verantwortlichen Person geprüft werden. Erst danach wird er nach main zusammengeführt.

4. Automatische Auslieferung abwarten​

Nach dem Merge sind keine manuellen Änderungen an einem Container notwendig:

GitLab

Merge nach main

Die freigegebenen Dateien werden Teil des zentralen Context-Hoster-Repositories.

Pipeline

Image bauen

Die GitLab-Pipeline erstellt aus dem Repository automatisch ein neues Container-Image mit dem Tag main.

UDSP

Image übernehmen

Keel erkennt den neuen Image-Stand und aktualisiert den laufenden Context Hoster automatisch.

Abnahme

URL prüfen

Der veröffentlichte Kontext und das neue Schema werden über die Mandantendomain kontrolliert.

Öffnen Sie nach erfolgreicher Pipeline die betroffene URL direkt im Browser. Der gemeinsame Kontext ist typischerweise unter folgender Adresse erreichbar:

https://context.<DOMAIN>/main-context.jsonld

Neue Schemata und eigene Kontexte folgen beispielsweise diesen Pfaden:

https://context.<DOMAIN>/dataModels/<Kategorie>/<Modell>.json
https://context.<DOMAIN>/customContext/<Modell>-context.jsonld

Prüfen Sie, ob der Browser den erwarteten JSON-Inhalt anzeigt. Testen Sie anschließend einen repräsentativen NGSI-LD-Payload mit genau dieser URL. Zwischen erfolgreichem Image-Build und sichtbarer Änderung können durch das Aktualisierungsintervall wenige Minuten liegen.

Änderungen über das Repository zurücknehmen

Eine fehlerhafte Änderung wird nicht direkt im laufenden Container korrigiert. Setzen Sie sie über einen neuen GitLab-Commit beziehungsweise Merge Request zurück. Der daraus gebaute main-Stand wird anschließend wieder automatisch und nachvollziehbar ausgeliefert.

Ergebnis prüfen​

  • Merge Request und fachliche Entscheidung sind nachvollziehbar dokumentiert.
  • Pipeline und Image-Build wurden erfolgreich abgeschlossen.
  • Schema und Kontext sind unter den vorgesehenen URLs erreichbar.
  • Der Beispiel-Payload verwendet die freigegebene Kontext-URL.
  • Stellio verarbeitet die Entität mit den erwarteten Attributen.

Damit weiterarbeiten​

Technische Referenz

NGSI-LD-Schnittstelle verwenden

Den veröffentlichten @context in Entitäten verwenden und die Daten über die vorgesehene Stellio-Schnittstelle schreiben.

Referenz öffnen
Technische Referenz

Context Hoster

Technische Rolle, Bereitstellung und Abhängigkeiten des Context Hosters in der UDSP.

Referenz öffnen

Externe Referenzen​