Format Konventionen und Beispiele

Eliona bietet leistungsstarke Werkzeuge wie JSONPath und MQTT-Wildcards, um eingehende Daten dynamisch und präzise den richtigen Assets zuzuordnen. Während JSONPath eine flexible Auswahl von Werten aus JSON-Daten ermöglicht, erlauben MQTT-Wildcards die Nutzung dynamischer Werte aus Topic-Strukturen. Diese Dokumentation zeigt, wie Sie beide Methoden effektiv einsetzen können, um Ihre Datenverarbeitung zu optimieren.

JSONPath-Konvention

JSONPath ist eine Syntax zur Auswahl und Verarbeitung von Werten in einem JSON-Dokument. Die Grundstruktur und Symbole von JSONPath:

1. $: Der Root-Knoten des JSON-Dokuments.

2. .: Der Zugriff auf ein Kind-Element.

3. []: Ermöglicht den Zugriff auf ein Element anhand eines Indexes oder einer Bedingung.

4. ?(): Filter-Ausdruck, um Elemente anhand einer Bedingung auszuwählen.

5. @: Repräsentiert das aktuelle Element im Filter-Ausdruck.

6. *: Wildcard, um alle Elemente eines Arrays oder Objekts auszuwählen.

7. ..: Rekursiver Zugriff, um alle Instanzen eines bestimmten Namens in der Hierarchie zu finden.

---

Beispiel 1: Einfache Abfrage aus einem JSON-Payload

JSON-Daten:

{
    "devices": [
        {
            "id": "A8032A13B850",
            "name": "WiFi Switch 4",
            "type": "ws2",
            "wifiSwitchTemp": 23.75
        },
        {
            "id": "F008D1C4B034",
            "name": "WiFi Switch 3",
            "type": "ws2",
            "wifiSwitchTemp": 23.93
        }
    ]
}

JSONPath-Abfragen und Ergebnisse:

1. Alle Gerätedaten abfragen: JSONPath: $.devices[*] Ergebnis:

   [
       {
           "id": "A8032A13B850",
           "name": "WiFi Switch 4",
           "type": "ws2",
           "wifiSwitchTemp": 23.75
       },
       {
           "id": "F008D1C4B034",
           "name": "WiFi Switch 3",
           "type": "ws2",
           "wifiSwitchTemp": 23.93
       }
   ]

2. Temperatur aller Geräte abfragen: JSONPath: $.devices[*].wifiSwitchTemp Ergebnis:

   [23.75, 23.93]

3. Ein Gerät mit einer bestimmten ID abfragen: JSONPath: $.devices[?(@.id=="A8032A13B850")] Ergebnis:

   [
       {
           "id": "A8032A13B850",
           "name": "WiFi Switch 4",
           "type": "ws2",
           "wifiSwitchTemp": 23.75
       }
   ]

4. Nur die Temperatur eines bestimmten Geräts abfragen: JSONPath: $.devices[?(@.id=="A8032A13B850")].wifiSwitchTemp Ergebnis:

[23.75]

Beispiel für wenn man ein bestimmtes Gerät will.

---

Beispiel: Funktion zur Erzeugung eines GAI/Zugehörige ID, wenn der Payload keinen Identifikator enthält

Wenn ein eingehender Payload keinen eindeutigen Identifikator enthält oder der Identifikator von mehreren Elementen im Payload abhängt, kann eine benutzerdefinierte Funktion verwendet werden, um den Identifikator zu generieren.

Szenario: Kein Identifier im Payload

Stellen wir uns folgendes Beispiel für einen Payload vor:

{
    "device": {
        "name": "WiFi Switch",
        "type": "ws2",
        "status": "active",
        "location": {
            "building": "Building_01",
            "floor": "Floor_02",
            "room": "Room_01"
        }
    }
}

In diesem Beispiel enthält der Payload keinen direkten Identifikator da es vielleicht mehrere WiFi Switch gibt, aber die Kombination aus Gebäude, Etage und Raum kann verwendet werden, um einen eindeutigen Identifikator zu erstellen.

Lösung: Funktion erstellen

Verwenden Sie eine benutzerdefinierte Funktion in Eliona, um den Identifikator aus den Bestandteilen des Payloads zu generieren.

Code-Beispiel: Identifikator aus mehreren Feldern erzeugen

javascriptCode kopierenfunction parsePayloadCustom(json, context) {
    const input = JSON.parse(json);

    // Objektstruktur initialisieren
    let obj = {
        "eliona": {
            "uin": null // Der Identifikator wird hier gespeichert
        }
    };

    // Prüfen, ob die erforderlichen Daten vorhanden sind
    if (
        input.device &&
        input.device.location &&
        input.device.location.building &&
        input.device.location.floor &&
        input.device.location.room
    ) {
        // Identifikator aus den Feldern im Payload generieren
        obj.eliona.uin = `${input.device.location.building}_${input.device.location.floor}_${input.device.location.room}`;
    } else {
        // Fallback: Standardwert setzen, wenn Felder fehlen
        obj.eliona.uin = null;
    }

    return obj;
}

---

Konfiguration in Eliona

1. Funktion erstellen:

   • Gehen Sie zur Option "Funktion erstellen" im Menü.

   • Geben Sie der Funktion einen Namen, z. B. parsePayloadCustom.

   • Fügen Sie den obigen Code im Code-Editor ein.

2. Funktion mit einem Format verbinden:

   • Wählen Sie im Menü "Format konfigurieren" das entsprechende Format.

   • Fügen Sie die Funktion mit dem Button "Funktion anhängen" hinzu.

3. Identifikator verwenden:

   • Das Format verwendet den generierten Identifikator (eliona.uin), um eingehende Daten auf das korrekte Asset zuzuordnen. Dafür kann entweder Extern für die Zugehörige ID oder GAI ausgewählt werden je nach dem wo man die Id dann haben will.

   

---

Verwendung von MQTT-Wildcards zur GAI/Zugehörige ID-Erstellung

MQTT-Topic-Struktur im Beispiel:

Wildcards in MQTT

MQTT unterstützt zwei Wildcard-Typen, die in den Topics verwendet werden können:

1. + (Einzel-Ebenen-Wildcard)

   • Stellt "alle Werte auf dieser Topic-Ebene" dar.

   • Beispiel: Das Topic building_01/+/room_01 passt auf folgende Topics:

     • building_01/floor_01/room_01

     • building_01/floor_02/room_01

2. # (Mehr-Ebenen-Wildcard)

   • Stellt "alle Werte ab dieser Ebene und darunter" dar.

   • Kann nur am Ende eines Topics verwendet werden.

   • Beispiel: Das Topic building_01/# passt auf folgende Topics:

     • building_01/floor_01

     • building_01/floor_01/room_01

     • building_01/floor_02/room_02

---

Funktionsweise der MQTT-Wildcards

• +-Wildcard: Jede +-Wildcard ersetzt genau einen Teil des Topics. Wenn es mehrere +-Wildcards in einem Topic gibt, können Sie in Eliona durch Nummern (1, 2, usw.) auf sie zugreifen. Beispiel: Im Topic building_01/+/+, repräsentiert:

  • 1: den ersten Teil, der durch + ersetzt wurde.

  • 2: den zweiten Teil, der durch + ersetzt wurde.

• #-Wildcard: Erfasst alle Werte und Ebenen ab der Position, an der sie steht. Alles, was im Topic den Platz von # einnimmt, kann in Eliona direkt über # referenziert werden.

---

Beispiele für MQTT-Wildcard-Nutzung

Beispiel 1: Nutzung von # zur Erfassung von Räumen

Subscription-Topic: building_01/#

Erhaltene Nachricht: building_01/floor_01/room_01

Konfiguration in Eliona:

• Identifikator: #

Ergebnis: Das Thema floor_01/room_01 wird als GAI/Zugehörige ID verwendet.

---

Beispiel 2: Nutzung von + zur Identifikation einer Ebene

Subscription-Topic: building_01/+/room_01

Erhaltene Nachricht: building_01/floor_02/room_01

Konfiguration in Eliona:

• Identifikator: 1

Ergebnis: Der Wert floor_02 (die Ebene, die durch das erste + ersetzt wurde) wird als GAI/Zugehörige ID verwendet.

---

Beispiel 3: Kombination von + und # zur Erfassung mehrerer Ebenen

Subscription-Topic: building_01/+/+/#

Erhaltene Nachricht: building_01/floor_01/room_02/sensor_01

Konfiguration in Eliona:

• Identifikator:

  • 1 → floor_01 (erste +-Wildcard)

  • 2 → room_02 (zweite +-Wildcard)

  • # → sensor_01 (alle Werte, die # ersetzen)

Ergebnis: Die Werte floor_01, room_02 und sensor_01 können individuell als GAI/Zugehörige ID verwendet werden.

---

Wichtige Hinweise

1. MQTT-Wildcards funktionieren nur mit dem Topic-Modus: Wählen Sie in der Identifikation "Topic" aus, wie im folgenden Bild dargestellt:

   
2. Automatische Verarbeitung in Eliona:

   • Eliona ersetzt Wildcards automatisch durch die tatsächlichen Werte des Topics.

   • Keine zusätzliche Verarbeitung ist erforderlich.

3. Nummerierung der +-Wildcards beachten:

   • Verwenden Sie die entsprechende Nummer (1, 2, usw.), um auf die spezifischen Werte zuzugreifen.