Neues Modul 98_JsonMod.pm (Abfragen und verarbeiten von JSON files via JSONPath)

[herrmannj]

Ab heute ist das Modul 98_JsonMod.pm via update verfügbar. Ähnlich wie HTTPMOD (daher die Namensähnlichkeit) stellt das Modul einen Weg zur Verfügung um JSON Dateien via HTTP zu holen und zu verarbeiten. JsonMod ist im Unterschied zu HTTPMOD auf JSON spezialisiert.

JSON Dateien werden oft über dokumentierte APIs vom Anbieter bereitgestellt. Die Nutzung der APIs erfodert eventuell eine Registrierung beim Anbieter und einen ,API KEY' oder vergleichbar. Diese API KEYS sind häufig Teil der aufzurufenden URL oder werden via HTTP HEADER übergeben. Um zu verhindern dass derart sensitive Information (zum Beispiel beim posten von Listings im Forum) unbeabsichtigt vom user selber geleakt werden, stellt das Modul einen Mechanismus bereit um dass zu verhindern.

Set <name> secret ,KEY' ,SECRET' speichert das mit ,KEY' (frei zu wählen) benannte ,SECRET' getrennt von der normalen Konfiguration. Das ,SECRET' wird danach weder in der fhem.cfg noch in einem Listing angezeigt. Um das ,SECRET' für die Abfrage zu verwenden, ersetzt man die entsprechende Position in der URL oder dem HTTP HEADER (attribut) durch den bei ,KEY' gewählten Bezeichner in eckigen Klammern. Ich empfehle dringend eigene Abfragen vom ersten Augenblick an so aufzubauen.

Beispiel (API KEY ,12345') → http://api.example.com/endoint/12345/daten.json

1. set <name> secret KEY 12345
2. prüfen: list. Unter dem Internal ,SECRET' wird der Bezeichner aufgelistet (natürlich nicht das SECRET an sich).
3. def (source) umschreiben zu: http://api.example.com/endoint/[KEY]/daten.json

Das Update Interval der JSON Quelle wird mit dem bekannten CRON Syntax spezifiziert.  Der CRON Syntax erlaubt es auch komplizierte Angaben wie ,,hole die Datei immer 5 vor halb und 5 vor voll" abzubilden. CRON ist bis auf die Wochentage vollständig mit dem Standard implementiert. Für user die mit dem CRON Syntax nicht ganz vertraut ist ein hilfreicher Link: https://crontab.guru/

Auf die einzelnen Elemente des JSON kann strukturiert via JSONPath (https://goessner.net/articles/JsonPath/) zugegriffen werden. JSONPath ist das Gegenstück von Xpath (XML). Das Modul implementiert alle wesentlichen Elemente des JSONPath Syntax. Implementierte Filter sind der derzeit ,==' / ,!=' / ,<' / ,<=' / ,>' / ,>=' sowie ,in' für Listen.

Für das Erstellen der Abfragen ist es notwendig ein Beispiel der zu parsenden Datei zu besitzen um deren Struktur zur verstehen. JSONPath Abfragen liefern, je nach Abfrage, entweder ein einzelnes Element oder eine Liste von Elementen. Diese Unterscheidung ist für das Verständnis der Funktionsweise elementar. Das Modul interpretiert die Ergebnisse der JSONPath Abfragen, wo immer möglich, großzügig. Wenn zum Beispiel ein einzelnes Reading gefüllt werden soll, die Abfrage jedoch eine Liste ergibt, dann wird versucht das erste Element der Liste zu verwenden. (https://en.wikipedia.org/wiki/Robustness_principle).

Hilfreiche Links zum Verständnis des JSONPath Syntax sowie zum erstellen und testen von Querys:
https://jsonpath.herokuapp.com/
https://github.com/json-path/JsonPath

Forumsbereich ist ,,Automatisierung".
Für Fehlermeldungen (real oder vermutet) gelten die üblichen Regeln:
* Ein BUG, ein thread. Keine Sammelthreads
* list des Device (code Tags)
* erwartetes Verhalten
* beobachtetes Verhalten
* Sample des JSON Files (code Tags)
* (Kontext falls erforderlich)

Ich habe 2 Beispiele zum weiteren Verständnis in getrennten Threads beschrieben und würde mich freuen wenn diese dann (neben anderen) den Weg ins WIKI finden:

• https://forum.fhem.de/index.php/topic,109412.0.html
• https://forum.fhem.de/index.php/topic,109413.0.html