# 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:** ```json { "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**: ```json [ { "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**: ```json [23.75, 23.93] ``` 3. **Ein Gerät mit einer bestimmten ID abfragen**:\ **JSONPath**: `$.devices[?(@.id=="A8032A13B850")]`\ **Ergebnis**: ```json [ { "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**: ```json [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: ```json { "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** ```javascript 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:** {% @mermaid/diagram content="graph TD A(building\_01) --> B(building\_01/floor\_01) A --> C(building\_01/floor\_02) B --> D(building\_01/floor\_01/room\_01) B --> E(building\_01/floor\_01/room\_02) C --> F(building\_01/floor\_02/room\_01) C --> G(building\_01/floor\_02/room\_02) " %} ### **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.