UDP Transformer - http2mqtt (shipped)

Der http2mqtt Transformer ermöglicht sehr flexible HTTP und HTTPS Abfragen über das MQTT Gateway. Die Ergebnisse werden per MQTT zurück zum Miniserver übertragen.

Begriffserklärung (wird unten mehrfach verwendet): Der "Response" ist die Antwort des Webservers nach einem URL-Abruf, wie z.B. die Webseite, die normalerweise im Browser angezeigt wird.

Funktionen:

  • HTTP und HTTPS
  • GET, POST und PUT-Requests
  • Authentifizierung mit HTTP-Methoden (Basic, Digest)
  • Implizite Verwendung von Cookies (z.B. Login → Request)
  • JSON-Responses werden direkt zerlegt und als Einzelwerte an MQTT übergeben
  • Unterstützt auch JSONP-Responses (wird automatisch zu JSON umgewandelt)
  • HTML-Response wird übergeben (kann auch im Transformer vorab gekürzt werden) und kann mit dem Befehlserkennungs-Baustein in Loxone verarbeitet werden.


 Aufrufsyntax

publish http2mqtt to/my/topic http://url [param:value] [param:value] [....:....] [POST/JSON-Data]

http2mqtt ist der Transformer-Name.

to/my/topic ist der Topic-Name, an das das Ergebnis gesendet wird (dies muss in den Subscriptions enthalten sein)

http://url ist der URL, der abgerufen werden soll. http und https ist möglich. Der URL kann einen Querystring enthalten (GET-Abruf), z.B. https://mydevice/set?a=1&b=2&c=3)

param:value sind optionale Parameter zur Steuerung des Transformers. Es können mehrere Parameter mitgegeben werden, siehe Tabelle unten. Die eckigen Klammern werden nicht angegeben!

POST/JSON-Data sind die Daten, die bei einem POST-Request mitgegeben werden. Es werden alle Daten verwendet, die nach dem letzten param:value Parameter folgen.

Mögliche Parameter

Bei der Angabe von param:value sind folgende Parameter möglich. Der value darf keine Leerzeichen enthalten!

ParameterBeispielStandardwertBedeutung
startstart:10000

Der Response des HTMLs wird erst ab dieser Anzahl zurückgegeben. Damit kann der Response gekürzt werden. Start beginnt bei 0 (= ab erstem Zeichen). Die Angabe 1000 startet beim 1001. Zeichen.

Bei einem JSON-Response wird dieser Wert ignoriert (sonst würde das JSON invalide werden)

lengthlength:2002500

Der Response des HTMLs wird gekürzt auf diese Länge, beginnen beim start-Wert. Damit kann der Response gekürzt werden. start:1000 und length:200 liefert die Zeichen von 1001 bis 1201.

Bei einem JSON-Response wird dieser Wert ignoriert (sonst würde das JSON invalide werden)

timeouttimeout:25

Abfrage-Timeout in Sekunden. Nach dieser Zeit wird der Request mit einem Fehler abgebrochen.

Beachte, dass während dieser Wartezeit das MQTT Gateway auch sonst keine Daten übermittelt und auf das Ergebnis wartet.

methodmethod:postget

Unterstützt wird: GET, POST, PUT. Für einen GET-Request ist der Parameter nicht erforderlich.

Bei einem POST- und PUT-Request muss nach allen param:value Parametern der zu übertragende Datensatz folgen:

Für POST-Daten die Daten wie einen Querystring formatieren: field1=data&field2=data usw.

Für JSON-Daten den content-type richtig setzen, und nach den Parametern einfach das JSON anhängen.

content-type

content-type:application/json;charset=UTF-8

Der String darf keine Leerzeichen enthalten!


Damit wird dem Webserver angekündigt, welche Daten mitgegeben werden. Dies wird in der Regel bei einem POST benötigt, wenn Json-Daten übertragen werden. 

Beispiele

In den Beispielen ist jeweils html/# subscribed.

Einfacher HTTP/HTTPS-Abruf

publish http2mqtt html/wetter https://www.wetter.at/

Das HTML der Wetterseite wird an das Topic html/wetter (bzw. den VTI html_wetter) gesendet. Mittels des Bausteins "Befehlserkennung" können aus dem HTML Werte extrahiert werden.

Einfacher HTTP/HTTPS Abruf mit JSON-Response

publish http2mqtt html/Vornamen https://www.salzburg.gv.at/ogd/c8711f5c-a49f-446d-ad69-6435bbc5a78e/names-szg.json

Ruft die 60 häufigsten Vornamen des Landes Salzburg als json-Datensatz ab. das MQTT Gateway zerlegt die Datensätze auf einzelne VI's.

Einfacher POST-Request mit Authentifizierung

publish http2mqtt html/runhealthcheck http://loxberry:loxberry@loxberry/admin/system/healthcheck.cgi method:post action=check


loxberry:loxberry@loxberry ist die Syntax user:pass@hostname

method:post sagt dem Transformer, dass es sich um einen POST-Request handeln soll.

Danach folgen die POST-Daten.

POST-Request mit JSON-Daten

publish http2mqtt html/sendjson https://url.to/send method:post content-type:application/json { "data":"value", "moredata":"anothervalue" }


Nach den Parametern method:post und dem content-type:application/json folgen die eigentlichen JSON-Daten, die gepostet werden sollen.

Cookies

Der Transformer speichert implizit die Cookies, die von den Webseiten gesetzt werden. Diese liegen in der RAM-Disk, d.h. sie sind nur bis zu einem LoxBerry-Neustart persistiert.

Manche Webseiten setzen beim Login Cookies, die danach zur Prüfung, dass bereits authentisiert ist, verwendet werden. So ist folgendes Szenario möglich:

publish http2mqtt html/somewebsite https://url.to/login length:0 method:post username=franzi&password=LoxBerryIsCool

Sowas kann als erster Request gesendet werden. Wenn die Webseite für diesen Login nun ein Cookie setzt, wird dieses für jeden weiteren Request automatisch gespeichert. length:0 ist gesetzt, weil wir den Response des Logins nicht benötigen (es wird deswegen kein HTML zurückgeliefert).

Nun kann die URL abgerufen werden, die tatsächlich die Daten enthält:

publish http2mqtt html/somewebsite https://url.to/getmydata

JSONP-Daten

JSONP ist eine (veraltete) Technik zur Übertragung von JSON-Daten innerhalb von JavaScript, die ermöglicht, innerhalb des JavaScript-Codes einer Webseite JSON-Daten einer anderen Webseite abzurufen mit Verringerung des Sicherheitsrisikos der Einschleusung fremden JavaScript-Codes (was inzwischen aber dennoch nicht mehr als sicher gilt und durch die Technik CORS ersetzt wurde).

Jedenfalls erkennt der Transformer ein Dataset, das JSONP ist, und wandelt es in einen JSON-Datensatz um. Das JSON wird an das MQTT Gateway weitergegeben und dort extrahiert.