Getting started
XML-/JSON-Parser – Benutzerhandbuch
1. Zweck
Der Logikbaustein extrahiert Texte und Zahlen aus XML- oder JSON-Daten. Die Auswahl erfolgt mit XPath-Ausdrücken. Damit lassen sich beispielsweise Werte aus Wetterdiensten, Smart-Home-Schnittstellen oder eigenen Webservices auf Datenpunkte legen und in weiteren Logiken verwenden.
Unterstützt werden:
- erster Treffer als Text oder Zahl,
- mehrere Treffer als verketteter Text,
- Summe, Minimum oder Maximum mehrerer Zahlen,
- Skalierung numerischer Ergebnisse,
- Textvorsatz und frei wählbarer Trenner.
Der Baustein ist ein eigenständiges TerraBytes-Paket für Gira X1/L1.
2. Installation und Inbetriebnahme
- Das signierte Paket
TerraBytes.XmlJsonParser-<Version>.zipim Gira Project Assistant (GPA) installieren. - XML-/JSON-Parser auf ein Logikblatt ziehen.
- Eingangskodierung auf
XMLoderJSONeinstellen. - Anzahl der Pfade und Ausgänge auf den benötigten Wert von 1 bis 50 setzen.
- Je Ausgang Pfad, Auswahlart und gegebenenfalls Skalierung, Textvorsatz oder Trenner konfigurieren.
- Den Eingang XML oder JSON und die benötigten Ausgänge verbinden.
- Zuerst in der GPA-Simulation und anschließend auf dem X1/L1 testen.
3. Eingang
| Eingang | Typ | Beschreibung |
|---|---|---|
| XML oder JSON | Text | Vollständiges XML- oder JSON-Dokument. Bezeichnung und erwartetes Format richten sich nach Eingangskodierung. |
Wenn ein Dienst beide Formate anbietet, ist XML vorzuziehen: XML ist das native Eingabeformat des Parsers und vermeidet Einschränkungen der JSON-zu-XML-Abbildung.
4. Datenausgänge
| Ausgang | Typ | Beschreibung |
|---|---|---|
| Ausgang 1 … n | Any | Ergebnis des zugehörigen Pfads. Der konkrete Wert ist Text oder Fließkommazahl. |
| Laufzeitfehler | Text | Meldet ungültige Pfade, nicht lesbare Eingaben oder Konvertierungsfehler. Der betroffene Datenausgang bleibt bei einem Fehler unverändert. |
Benannte HTML-Zeichen werden in Textausgaben dekodiert, zum Beispiel wird ä zu ä. Ein Any-Ausgang wird beim Verbinden mit einem nachfolgenden Eingang entsprechend dessen Porttyp automatisch konvertiert, soweit GPA diese Konvertierung unterstützt.
5. Fachliche Parameter
Eingangskodierung
Legt fest, ob XML- oder JSON-Daten erwartet werden.
Anzahl der Pfade und Ausgänge
Legt 1 bis 50 unabhängige XPath-Auswertungen und die gleiche Anzahl Datenausgänge an.
Pfad 1 … n
XPath-Ausdruck für den jeweiligen Ausgang. XPath-Indizes beginnen bei 1.
Für JSON gelten zusätzlich:
- Jeder Pfad beginnt mit
/root. - JSON-Arrays werden als
item-Elemente abgebildet. - JSON-Schlüssel, die keine gültigen XML-Namen sind, können auf dem X1/L1 einen Laufzeitfehler auslösen. Ein Schlüssel wie
"3h"sollte vor dem Parser in einen gültigen Namen geändert werden.
Art der Pfadauswahl 1 … n
| Auswahlart | Ergebnis bei Treffern | Ergebnis ohne Treffer |
|---|---|---|
| Erster Treffer als Text | erster Wert als Text | Laufzeitfehler; Ausgang unverändert |
| Erster Treffer als Zahl | erster Wert als Zahl | Laufzeitfehler; Ausgang unverändert |
| Alle Treffer als verketteter Text | alle Texte mit Trenner | leerer Text |
| Alle Treffer als summierte Zahl | Summe aller Zahlen | 0 |
| Minimum aller Treffer als Zahl | kleinste Zahl | Laufzeitfehler; Ausgang unverändert |
| Maximum aller Treffer als Zahl | größte Zahl | Laufzeitfehler; Ausgang unverändert |
Skalierungsfaktor 1 … n
Nur für numerische Auswahlarten. Das Ergebnis wird mit diesem Faktor multipliziert. Leer oder 1 lässt den Wert unverändert. Beispiel: Milliwatt werden mit 0,001 in Watt umgerechnet.
Textvorsatz 1 … n
Nur bei Erster Treffer als Text. Der Text wird vor den gefundenen Wert gesetzt.
Text-Trenner 1 … n
Nur bei Alle Treffer als verketteter Text. Der Text wird zwischen den Treffern eingefügt.
6. Beispiele
6.1 Einfaches XML: Temperatur und Status
Eingabe:
<sensor>
<name>Außenfühler</name>
<temperature>21.7</temperature>
<online>true</online>
</sensor>
| Ausgang | Pfad | Auswahlart | Ergebnis |
|---|---|---|---|
| 1 | /sensor/name |
Erster Treffer als Text | Außenfühler |
| 2 | /sensor/temperature |
Erster Treffer als Zahl | 21,7 |
| 3 | /sensor/online |
Erster Treffer als Text | true |
6.2 JSON mit Objekt und Array
Eingabe:
{
"room": "Küche",
"values": [19.5, 20.0, 20.5]
}
| Ausgang | Pfad | Auswahlart | Zusatz | Ergebnis |
|---|---|---|---|---|
| 1 | /root/room |
Erster Treffer als Text | Textvorsatz Raum: |
Raum: Küche |
| 2 | /root/values/item |
Alle Treffer als verketteter Text | Trenner / |
19.5 / 20 / 20.5 |
| 3 | /root/values/item |
Maximum aller Treffer als Zahl | – | 20,5 |
6.3 XML mit Attribut, Filter und Skalierung
Eingabe:
<devices>
<device name="Pumpe" active="true"><power>12500</power></device>
<device name="Licht" active="false"><power>800</power></device>
</devices>
| Ausgang | Pfad | Auswahlart | Zusatz | Ergebnis |
|---|---|---|---|---|
| 1 | /devices/device[@active="true"]/@name |
Alle Treffer als verketteter Text | Trenner , |
Pumpe |
| 2 | /devices/device[@name="Pumpe"]/power |
Erster Treffer als Zahl | Faktor 0,001 |
12,5 |
6.4 Summe und Minimum einer Wettervorhersage
Für ein OpenWeatherMap-XML-Dokument können die ersten vier Prognosewerte so ausgewählt werden:
- Niederschlag:
/weatherdata/forecast/time[position()<5]/precipitation/@value - Temperatur:
/weatherdata/forecast/time[position()<5]/temperature/@value
Für Niederschlag eignet sich Alle Treffer als summierte Zahl. Für den Temperaturverlauf kann Alle Treffer als verketteter Text mit dem Trenner | oder Minimum aller Treffer als Zahl verwendet werden.
6.5 FRITZ!Box Smart Home
Typische Pfade für die XML-AHA-Schnittstelle:
- offene Kontakte:
/devicelist/device[./alert/state="1"]/name - Schaltstatus:
/devicelist/device[./name="Steckdose 1"]/switch/state - Leistung:
/devicelist/device[./name="Steckdose 1"]/powermeter/power
Die Leistung wird in Milliwatt geliefert. Mit dem Skalierungsfaktor 0,001 entsteht Watt.
7. Lizenzparameter und Statusausgänge
| Parameter | Bedeutung |
|---|---|
| ActivationCode | Aktivierungscode für den ProductCode XmlJsonParser |
| OfflineToken | Optionaler signierter Offline-Nachweis |
| OfflineProfile | Lizenzprofil Private, Business oder Partner |
| ReleaseChannel | Updatekanal Stable, Beta oder Rc |
| Ausgang | Bedeutung |
|---|---|
| LicenseStatus | Ergebnis der Lizenzprüfung |
| LicenseOwner | Lizenzinhaber |
| UpdateAvailable | Kennzeichnet ein verfügbares Update |
| LatestVersion | Neueste angebotene Version |
| DownloadUrl | Bezugsadresse des Updates |
| OfflineExpiresAt | Ablaufzeitpunkt des Offline-Tokens |
In der GPA-Simulation wird der Baustein automatisch freigeschaltet. Auf dem Zielgerät ist eine passende Lizenz für XmlJsonParser erforderlich.
8. Fehlerbehebung
- Laufzeitfehler meldet ungültiges XML/JSON: Das vollständige Dokument mit einem Validator prüfen und die richtige Eingangskodierung wählen.
- Pfad findet keinen Wert: Pfad zunächst auf ein einzelnes, sicher vorhandenes Element reduzieren; XPath zählt ab 1.
- JSON-Array bleibt leer: Zwischen Arrayname und Wert fehlt wahrscheinlich
/item. - JSON funktioniert in der Simulation, nicht auf X1/L1: Schlüssel auf gültige XML-Namen prüfen, besonders Namen, die mit einer Zahl beginnen.
- Zahl kann nicht gelesen werden: Eingabewert muss eine XML-kompatible Zahl mit Dezimalpunkt enthalten.
- Ausgang ändert sich bei einem Fehler nicht: Das ist beabsichtigt; die Ursache steht am Ausgang Laufzeitfehler.
- Lizenz nicht aktiv: ProductCode, Aktivierungscode, Gerätebindung und Netzwerkzugang prüfen.
9. Datenschutz und Netzwerk
Die Parserfunktion führt selbst keine HTTP-Anfragen aus; Daten müssen von einem anderen Baustein bereitgestellt werden. Nur die Lizenzprüfung kommuniziert mit dem TerraBytes-Lizenzdienst.
Die mitgelieferte Datei Help/XmlJsonParser.html enthält dieselbe fachliche Referenz und wird im GPA direkt am Baustein angezeigt.
