ScaleIT Messaging Spezifikation

Die ScaleIT Messageing Spezifikation besteht aus 3 Schichten (ähnlich wie bei den OSI-Schichten baut eine Schicht auf der darunter liegenden auf):

• Obere Schicht / Layer 2: Anwendungs-/Domain-Kommunikation
• Mittlere Schicht / Layer 1: App2App-Kommunikation
• Untere Schicht / Layer 0: MQTT Transportprotokoll

Nachfolgend wird zur leichteren Verständlichkeit die App Pacman (sorry!) verwendet.

Untere Schicht / Layer 0: MQTT Transportprotokoll

Jede ScaleIT Message ist zunächst eine MQTT Nachricht. Eine MQTT Nachricht besteht aus

• ein Topic (Überschrift)
• einem Message-Body (Inhalt)

In ScaleIT wird MQTT in der Version 3.1.1 unterstützt.

Mittlere Schicht / Layer 1: App2App-Kommunikation

Damit ScaleIt Apps miteinander kommunizieren kommen, gelten die nachfolgende Spezifikationen für Topic und Body.

Das ScaleIT Message Topic

Ein ScaleIT-Topic hat immer folgende Struktur:

   app/<appname>/<stackname>/<message-spec>/...

Die Elemente sind:

• app: Damit startet ein Topic
• <appname>: Der Name der App, z.B. de-ondics-pacman
• <stackname>: Der Name der App-Instanz (wird vom Rancher beim Start vergeben), z.B. de-ondics-pacman_1
• <message-spec>: Der Name der Message, z.B. "gameover"
• ...: weitere Konkretisierunges des Topics, um viele unterschiedliche nachrichten besser zu unterscheiden

Beispiel-Topic:

   app/de-ondics-pacman/de-ondics-pacman_1/gameover

Wenn eine App als Subscriber alle "gameover"-Nachrichten alle Pacman-Apps empfangen will, müss sie als Topic beim Broker abonnieren:

   app/de-ondics-pacman/#/gameover

"#" ist ein Wildcard-Symbol in MQTT-Topics. Weitere Details zur Topic-Angabe im Mosquitto-Handbuch.

Der ScaleIT Message-Body

Eine ScaleIT Message-Body hat immer ein JSON-Format.

• Jede Message enthält nur die notwendigsten Daten, als z.B. keine Metadaten.
• Jede Message enthält einen Schema-Verweis zu dieser Message

   {
       "$schema": "gameover.json" 
       "score": 10230,
       "isHighscore": true
   }

Die vollständige URL zum Schema lässt sich bilden aus

• der API-Url (in der App-Registry)
• dem Messaging-Pfad (i.d.R. /api/messages)
• dem Schema-Verweis (hier: gameover.json)

Das ScaleIT Message Schema in der sendenden App

Das JSON Schema spezifiziert den Message Body. Mehr zu JSON Schema steht in der offziellen JSON Schema Spezifikation.

Inhaltlich müssen im Schema enthalten sein:

• "description": Beschreibung jedes einzelnen Elements (Sprache: deutsch)
• "type": Typ: integer, boolean, string

Es können weitere Elemente hinzukommen, z.B.

• "description_en": Beschreibung in englisch

Beispiel:

   {
       "$schema": "http://json-schema.org/draft-06/schema#",
       "title": "Pacman-Spielende",
       "description": "Ein Pacman-Spiel wurde korrekt beendet",
       "type": "object",
       "properties": {
           "score": {
               "description": "Der erzielte Spielstand",
               "type": "integer" 
           },
           "isHighscore": {
               "desription": "Ist das ein neuer Highscore?",
               "type": "boolean" 
           }   
       },
       "required": ["score","isHighscore"]
   }

Dieses Schema ist unter gameover.json abrufbar.

Obere Schicht / Layer 2: Anwendungs-/Domain-Kommunikation

Die Anwendungsschicht wird zunächst von App-Herstellern spezifiziert.

App-Ökosystemanbieter können zudem domänenspezifische Vorgaben machen, z.B.

• Sensorwerte
• Maschinenzustände
• Ereignisse am Arbeitsplatz (z.B. Beginn/Erledigung von Arbeitsschritten)
• Alarmsituationen
• technische Ereignisse (Installation von Apps, Neustart-Ankündigung, ...)