Erste Schritte mit OctoMesh

In diesem Tutorial lernen Sie die wenigen Begriffe kennen, auf denen alles andere in OctoMesh aufbaut, finden sich im Refinery Studio zurecht und richten octo-cli ein, um auf der Kommandozeile zu arbeiten. Nichts in diesem Tutorial verändert Daten.

Dauer: etwa 30 Minuten.

Grundbegriffe

OctoMesh ist eine Datenplattform: Sie speichert, was Dinge sind (Stammdaten, ein Modell Ihrer Welt), und was sie messen (Zeitreihen), und sie bewegt Daten über Pipelines hinein und hinaus. Sechs Begriffe tragen den Großteil davon.

Tenant

Ein Tenant (Mandant) ist ein abgeschotteter Arbeitsbereich mit eigener Datenbank, eigenen Benutzern, Rollen und eigener Konfiguration. Jede Anfrage nennt einen Tenant, entweder in der URL (/tenants/<tenant>/GraphQL) oder über das Token, mit dem Sie sich angemeldet haben. Tenants können eine Hierarchie bilden: Ein übergeordneter Tenant kann gemeinsame Anwendungen beherbergen und untergeordnete Tenants für einzelne Kunden oder Projekte. Siehe Tenant-Lebenszyklus.

Construction Kit (CK)

Ein Construction Kit ist das Datenmodell einer Domäne. Es ist versioniert, wird als Bibliothek veröffentlicht (zum Beispiel Basic.Energy-1.9.0 oder EnergyCommunity-4.9.0) und enthält:

Typen, vergleichbar mit Klassen mit Vererbung. Eine CK-Typ-Id wird <Model>/<Type> geschrieben, zum Beispiel EnergyCommunity/Customer.
Attribute: die typisierten Felder eines Typs (String, Zahl, Datum/Uhrzeit, Enum, Record, ...).
Records: strukturierte Werte ohne eigene Identität, zum Beispiel eine Adresse oder ein Zeitraum.
Enums: geschlossene Wertelisten, zum Beispiel die Datenqualität L1, L2, L3.
Assoziationen: typisierte Beziehungen zwischen Typen, zum Beispiel die Eltern-Kind-Beziehung System/ParentChild.

Ein Tenant verwendet ein CK, sobald die Bibliothek in ihn importiert ist. Siehe Construction Kits.

Runtime-Entity

Eine Runtime-Entity ist eine Instanz eines CK-Typs: ein konkreter Kunde, ein konkreter Zählpunkt. Jede Entity hat

eine rtId, eine 24-stellige hexadezimale Id, die im Tenant eindeutig ist,
eine ckTypeId, die ihren Typ benennt,
optional einen rtWellKnownName, einen stabilen Namen, über den man sie findet,
Attributwerte und Assoziationen zu anderen Entities.

Die Entities eines Tenants bilden sein Runtime-Modell, das in MongoDB gespeichert und über GraphQL abgefragt wird.

Stream Data, Archive und Rollups

Werte, die sich über die Zeit ändern, etwa ein Zählerwert alle 15 Minuten, sind Stream Data. Sie werden nicht an der Entity selbst gespeichert, sondern in einem Archiv: einer Zeitreihentabelle in CrateDB, mit einer Zeile pro Entity und Zeitpunkt (oder pro Zeitfenster). Die Entity dient als Anker ihrer Zeitreihe: Die rtId der Zeile verweist auf sie.

Ein Raw-Archiv oder Time-Range-Archiv nimmt die Originalwerte auf.
Ein Rollup-Archiv verdichtet ein anderes Archiv automatisch in gröbere Buckets (stündlich, täglich, monatlich, ...), sodass lange Zeiträume gelesen werden können, ohne Millionen Rohzeilen aufzusummieren.

Siehe Stream Data und Archive.

Blueprint

Ein Blueprint ist ein installierbares Paket für einen Tenant. Es benennt die CK-Bibliotheken, die es braucht, und bringt Seed-Daten mit: Konfigurations-Entities, Abfragen, Dashboards, Archive und Pipelines. Die Installation eines Blueprints macht aus einem leeren Tenant eine funktionierende Anwendung. Siehe Blueprints.

Pipelines, Data Flows und Adapter

Eine Pipeline ist eine Folge von Knoten, die durch ein Ereignis ausgelöst wird (einen Zeitplan, eine HTTP-Anfrage, eine Nachricht), Daten umformt und das Ergebnis ins Runtime-Modell, in ein Archiv oder in ein externes System schreibt. Pipelines werden in Data Flows gruppiert und laufen auf einem Adapter, einem Dienst, der für den Tenant bereitgestellt wird. Der Mesh Adapter führt allgemeine Pipelines aus, andere Adapter binden bestimmte Systeme an (zum Beispiel SAP, Modbus oder den österreichischen Energiedatenaustausch EDA). Siehe Kommunikation.

Rundgang durch das Refinery Studio

Das Refinery Studio ist die Weboberfläche von OctoMesh. Öffnen Sie https://studio.<your-domain>/<tenant> und melden Sie sich mit Ihrem Konto an. Die genauen Bezeichnungen in der Navigation hängen von Ihrer Studio-Version und Ihren Rollen ab, Sie finden aber diese Bereiche:

Bereich	Was Sie dort tun	Referenz
Daten-Explorer / Repository	Runtime-Entities nach CK-Typ durchsuchen, eine Entity öffnen, ihren Assoziationen folgen, Attribute bearbeiten (sofern Ihre Rolle es erlaubt)	Refinery Studio
Modellbibliotheken	Sehen, welche CK-Bibliotheken im Tenant installiert sind, und ihre Typen, Attribute und Enums ansehen	Modellbibliotheken
Query Builder	Abfragen über Runtime-Entities und Stream Data erstellen und speichern, ohne GraphQL zu schreiben	Query Builder
Archive	Die Stream-Data-Archive des Tenants mit Status und Rollups ansehen	Archive
Blueprints	Sehen, welche Blueprints in welcher Version installiert sind	Blueprints
MeshBoards	Dashboards, die aus gespeicherten Abfragen gebaut sind	MeshBoards
Kommunikation	Adapter, Data Flows und Pipelines mit ihrer Ausführungshistorie	Kommunikation
Identity	Benutzer, Gruppen, Rollen und OAuth-Clients des Tenants (nur Administration)	Identity

Probieren Sie diesen kurzen Rundgang:

Öffnen Sie Modellbibliotheken und notieren Sie die Bibliotheken, die Ihr Tenant verwendet.
Wählen Sie einen Typ aus einer Domänenbibliothek und öffnen Sie ihn im Daten-Explorer. Notieren Sie die rtId einer Entity; Sie verwenden sie im nächsten Tutorial wieder.
Öffnen Sie Archive und prüfen Sie, ob der Tenant Archive hat und ob sie Activated sind. Nur aktivierte Archive enthalten Daten.

Arbeiten auf der Kommandozeile mit octo-cli

octo-cli ist das Kommandozeilenwerkzeug für OctoMesh. Sie brauchen es, um sich aus Skripten anzumelden und administrative Befehle auszuführen. Siehe die Installationsanleitung.

Einen Kontext anlegen

Ein Kontext bündelt die Service-URLs, den Tenant und die gespeicherten Tokens, ähnlich einem kubectl-Kontext. Legen Sie einen pro Tenant an, mit dem Sie arbeiten:

octo-cli -c AddContext -n <context-name> \
  -isu https://connect.<your-domain>/ \
  -asu https://assets.<your-domain>/ \
  -bsu https://bot.<your-domain>/ \
  -csu https://communication.<your-domain>/ \
  -tid <tenant>

Der erste angelegte Kontext wird automatisch aktiv. Wechseln Sie mit octo-cli -c UseContext -n <context-name> und listen Sie alle Kontexte mit octo-cli -c ListContexts auf. Jeder Befehl kann mit --context <context-name> auch gezielt einen Kontext ansprechen, ohne den aktiven zu ändern.

Anmelden

octo-cli -c LogIn -i

octo-cli verwendet den OAuth-Device-Flow: Es öffnet einen Browser (oder gibt eine URL und einen Code aus), Sie melden sich wie gewohnt an, und die CLI erhält ein Access-Token und ein Refresh-Token. Beide werden in der Kontextdatei ~/.octo-cli/contexts.json gespeichert.

Anmeldung prüfen:

octo-cli -c AuthStatus

AuthStatus erneuert ein abgelaufenes Access-Token automatisch, solange das Refresh-Token noch gültig ist; eine Meldung expired ist also meist kein Grund, sich neu anzumelden. Für Skripte, die oft laufen, meldet octo-cli -c LogIn -i -in nur dann neu an, wenn das gespeicherte Token sich nicht mehr erneuern lässt.

Behandeln Sie die Kontextdatei wie ein Passwort

~/.octo-cli/contexts.json enthält Ihre Tokens, und AuthStatus gibt das Access-Token aus. Kopieren Sie beides nie in einen Chat, ein Ticket oder ein Repository.

Erste lesende Befehle

# Which CK libraries are installed in the tenant, and in which version?
octo-cli -c LibraryStatus

# Which blueprints are installed?
octo-cli -c ListBlueprintInstallations

LibraryStatus listet jede Bibliothek mit installierter und verfügbarer Version und ihrem Zustand; Available bedeutet, dass das Modell in Ordnung ist. Die vollständige Befehlsliste finden Sie in der Befehlsreferenz und unter Häufige Abläufe.

Zusammenfassung

Ein Tenant enthält ein Runtime-Modell aus Entities, deren Typen aus Construction Kits stammen.
Zeitreihen liegen in Archiven, über die rtId an Entities verankert, und werden durch Rollups verdichtet.
Blueprints installieren Modelle, Konfiguration und Pipelines in einem Schritt.
Das Refinery Studio ist der visuelle Zugang, octo-cli der skriptbare.

Weiter: Auf Daten zugreifen zeigt Ihnen, wie Sie all das aus eigenem Code abfragen.

Grundbegriffe​

Tenant​

Construction Kit (CK)​

Runtime-Entity​

Stream Data, Archive und Rollups​

Blueprint​

Pipelines, Data Flows und Adapter​

Rundgang durch das Refinery Studio​

Arbeiten auf der Kommandozeile mit octo-cli​

Einen Kontext anlegen​

Anmelden​

Erste lesende Befehle​

Zusammenfassung​