JSON Daten in Homematic Script verarbeiten

Java Script Object Notation (JSON) ist ein gängiges Format zum Austausch strukturierter Daten. Viele Web-Services und APIs nutzen JSON um Anfragen und Rückgabewerte zu formatieren. Besonders bei der Integration von API’s oder Drittsystemen ist eine Verarbeitung von JSON formatierten Daten mit Homematic Scripten notwendig.

Leider bietet die Homematic Script Engine keine integrierte JSON-Unterstützung, daher muss man JSON Daten auf Umwegen verarbeiten. In diesem Artikel stellen wir die Verbarbeitung von JSON mit jq in Homematic Scripten vor.

Als Beispiel werden wir JSON Daten von https://dummyjson.com nutzen und über cURL abrufen. Hierfür nehmen wir den Endpunkt https://dummyjson.com/products/1 welches ein Produkt, genauer ein Apple iPhone und dessen Lagerbestand repräsentiert. In Homematic Script werden wir die JSON Daten mit jq auswerten und den Lagerbestand (“stock”) im Script ausgeben. Die Beispieldaten, die wir hierfür nutzen sehen wir folgt aus:

{
  "id": 1,
  "title": "iPhone 9",
  "description": "An apple mobile which is nothing like apple",
  "price": 549,
  "discountPercentage": 12.96,
  "rating": 4.69,
  "stock": 94,
  "brand": "Apple",
  "category": "smartphones",
  "thumbnail": "https://i.dummyjson.com/data/products/1/thumbnail.jpg",
  "images": [
    "https://i.dummyjson.com/data/products/1/1.jpg",
    "https://i.dummyjson.com/data/products/1/2.jpg",
    "https://i.dummyjson.com/data/products/1/3.jpg",
    "https://i.dummyjson.com/data/products/1/4.jpg",
    "https://i.dummyjson.com/data/products/1/thumbnail.jpg"
  ]
}

Vorbereitung: jq auf der CCU3 installieren

jq ist ein Leistungsfähiger Kommandozeilen-Parser für JSON. Linux basierte Systeme wie RasbperryMatic bringen jq in der Regel standardmäßig mit oder man installier es über gängige Paketmanager wie apt. Auf der CCU3 ist jq nicht verfügbar und muss nachinstalliert werden. Die einfachste – auch wenn etwas veraltete – Variante ist das ccu-addon-jq von Hobbyquaker. Dieses lässt sich einfach als AddOn über die CCU Weboberfläche installieren. Den Download und die Anleitung ist auf GitHub verfügbar:
https://github.com/hobbyquaker/ccu-addon-jq

JSON Daten laden und im Homematic Script verarbeiten

Das Holen und Parsen der JSON Daten erfolgt auf Systemebene über system.Exec(). Hierfür initialisieren wir werden zuerst die notwendigen Variablen:

var stdout;
var stderr;

Sind die Variablen initialisiert, erfolgt die Abfrage der API über cURL. Das Ergebnis wird anschließend in-line an jq übergeben.

system.Exec("curl -k --location --request GET 'https://dummyjson.com/products/1' | \
jq -r '.stock'", &stdout, &stderr);

Die Syntax für jq kann man online auf https://jqplay.org erarbeiten und ausprobieren. Im Beispiel ist der Selektor simpel: .stock selektiert das gewünschte Attribut im des JS Objekts. Mit jq sind jedoch auch beliebig komplexe Abfragen und Transformationen möglich.

Ergänzt durch eine rudimentäre Fehlerbehandlung sieht das Ergebnis sieht wie folgt aus:

var stdout;
var stderr;
system.Exec("curl -k --location --request GET 'https://dummyjson.com/products/1' | \
jq -r '.stock'", &stdout, &stderr);
if(stdout){
  var stock = stdout.ToInteger();
  WriteLine("Products in stock: "#stock);
}
else {
  WriteLine("An error occurred: "#stderr);
}

Damit ist die die Grundlage geschaffen, JSON Daten per WebAPI abzurufen und die notwendigen Informationen zu extrahieren. Diese können anschließend im Homematic Script ausgewertet und die Informationen ins Smart Home eingebunden werden.