HTTP- Request

Mittels http-Requests können Inhalte von Webservern abgeholt und verarbeitet werden oder Daten an Server versendet werden. Dazu stehen die Methoden GET, PUT, POST und DELETE zur Verfügung. Der URL (einheitlicher Quellen Anzeiger) wird dabei aus drei verschiedenen Teilen zusammengesetzt, Basis URL, Ziel und Wertobjekt(en) bzw. Inhalten als Content-Type. Pflichtfelder sind Elemente Name, Eingangsobjekt und Basis-URL. Für das Auswerten der Antworten eines Webservers steht ein Modul zur Verfügung welches mittels Regulärer Ausdrücke die Antwort durchsucht und aufgrund dessen Ereignisse im KNX auslösen kann.

Name

Pflichtfeld. Vergeben Sie einen eindeutigen Namen für den Job. Der Name darf maximal 15Zeichen enthalten.

Freigabeobjekt

Durch das Freigabeobjekt wird der Job freigegeben oder gesperrt. Es handelt sich um ein EIS 1 Objekt:

• Gruppenadresse nicht vergeben = Job freigegeben

• Gruppenadresse eingetragen, Wert 1 = Job freigegeben

• Gruppenadresse eingetragen, Wert 0 = Job ist gesperrt

• Gruppenadresse eingetragen, Kein Wert = Job ist gesperrt

Sobald eine Adresse in das Feld eingetragen ist, verhält sich die Freigabe entsprechend dem Wert der Gruppenadresse. Wurde auf die Adresse bisher kein Wert gesendet, ist sie also zurzeit Werte-los, ist der Job gesperrt.

Eingangsobjekt

Pflichtfeld. Das Eingangsobjekt muss EIS14 typisiert sein. Anhand seines Wertes werden die verschiedenen Einträge in den Zielobjekten ausgelöst. Ist in den Zielobjekten die Option „wildcard“ gesetzt spielt der auslösende EIS14 Wert keine Rolle.

Fehler Text

Falls die Anfrage nicht erfolgreich ist wird vom Server in der Regel eine Fehlermeldung ausgegeben. Diese kann der Job als EIS15 Text Nachricht wiedergeben.

Protokoll

Als Protokoll kann „http“, „https“ (http-Secure) verwendet werden. Https überträgt die Daten verschlüsselt. Damit dass realisiert werden kann müssen Server und Client (EIBPORT) Zertifikate und Schlüssel miteinander tauschen. Der Verbindungsaufbau dauert also ungleich länger.

Basis-URL

Pflichtfeld. Hier wird die Adresse des Servers eingetragen, der angesprochen werden soll. Es können DNS-Namen oder IP-Adressen verwendet werden. Wird ein DNS-Name verwendet müssen die DNS-Einstellungen im EIBPORT korrekt sein, bzw. der eingetragene DNS-Server erreichbar sein.

Eine DNS Anfrage kann mitunter verhältnismäßig lange dauern. Um die Ausführung des Jobs zu beschleunigen, kann die IP-Adresse des Servers eingetragen werden. Die DNS-Anfrage würde damit entfallen.

Wechselt die IP-Adresse eines DynDNS Accounts, weicht diese für einen kurzen Zeitraum eventuell von jener ab, die der EIBPORT in seiner internen DNS-Tabelle angelegt hat. In diesem Fall würde der Request an die falsche Adresse gestellt.

Auth. Name und Auth. Passwort

Hier können ggf. Benutzername und Passwort für eine http Authentifizierung eingetragen werden. Ist das Protokoll „http“ aktiviert wird die http- Basic Authentication verwendet. Dabei werden Benutzerdaten und Passwort unverschlüsselt übertragen. Bei „https“ wird die gleiche Anmeldung verwendet, allerdings ist dabei auch die Übertragung der Authentifizierungsdaten verschlüsselt.

Request Type

Ein HTTP-Request kann mit unterschiedlichen Methoden ausgeführt werden. Für den Job können Sie zwischen der Methode „GET“ und „POST“ wählen.

• GET
  Ist die gängigste Methode, um Daten von einem Webserver anzufordern und dient häufig auch zur Übermittlung von Daten oder Steuerbefehlen mittels URL-Parametern (Der technisch richtige Begriff für eine URL wäre eigentlich URI). Der eigentliche Zweck von GET-Abfragen ist jedoch die Abfrage von Daten.

• POST
  Wird benutzt, um Inhalte an einen Server übermitteln zu können. So können z.B. Formulardaten übermittelt werden, die den Server veranlassen neue Daten anzulegen oder Bestehende zu verändern. Die Übermittlung von Daten kann aber auch wie bei der „GET“ Methode durch das Übermitteln per URL-Parametern geschehen. Häufig findet eine Kombination beider Methoden statt. Per URL wird das Ziel der Daten, die mitgeliefert werden, genau adressiert.

• PUT
  Wird ähnlich verwendet wie POST. Wenn streng nach Definition vorgegangen würde, wäre POST für das Verändern vorhandener Daten verantwortlich und PUT für das neu anlegen der Daten. Das Prozedere ist jedoch dasselbe wie bei POST. Aus diesem Grund wird häufig auf PUT verzichtet und alle Befehle zu Datenmanipulation werden per POST übermittelt.

• DELETE
  Wird zum Löschen von Daten verwendet. DELETE unterliegt denselben Beschränkungen wie GET. Es werden keine Daten mitgeliefert. Sämtliche Parametrierung findet per URL statt.

Ist „POST“ ausgewählt darf der URL nicht in den „Zielen“ vervollständigt werden, sondern im Feld „Basis URL“. Das Eingabefeld in der Zieldefinition steht dann mit allen Zeichen (max 256) für die „POST“ –Daten zur Verfügung.

Content Type

Wenn bei „Request Type“ die Methode „POST“ gewählt worden ist, wird die Auswahl zum Content Type freigeschaltet. Die Auswahlbox bestimmt um welche Kodierung es sich bei den Daten handelt, die mittels der „POST“ Methode an den entfernten Server übertragen wird. Dieses Feld dient zur Information dem Server mitzuteilen, in welcher Form der Inhalt zu erwarten ist Folgende Content Types können ausgewählt werden:

• text/plain
  Der Inhalt der „Post-Data“ ist als einfacher Text gekennzeichnet.

• text/xml
  Der Inhalt ist als xml Datei gekennzeichnet.

• text/html
  Der Text ist als HTML Datei gekennzeichnet.

• application/x-www-form-urlencoded
  Dem Server wird mitgeteilt, dass der Text URL encoded ist. Dabei werden Sonderzeichen durch bestimmte Zeichenfolgen ersetzt. Siehe Internet „URL Encoding“.

Manche Server verlangen einen dedizierten Datentyp im Inhalt. Aus diesem Grunde verwerfen sie alle Pakete deren Content-Type Informationen auf einen anderen Typ eingestellt sind, auch wenn dessen tatsächlicher Inhalt dem verlangten Content Type des Servers entspricht.

Anfrage: Ziel-URLs

Anzahl Ziele

Jedem Basic-URL können mehrere Ziele zugeordnet werden. In den Zielen kann der variable Teil der URL eingetragen werden, der sich für die verschiedenen Funktionsaufrufe ändert. Maximal sind 8 Ziele möglich.

Wildcard

Ist diese Option aktiviert, wird das entsprechende Ziel und von einem beliebigen EIS 14 Triggerwert ausgelöst.

Es kann nur einen Wildcard Eintrag pro Job geben.

Auslösewert

Ein EIS 14 Wert der den Request mit dem jeweiligen Ziel auslöst. EIS 14 kann einen Wert von 0-255 haben.

URL

Der Basis-URL wird mit diesem Feld vervollständigt. Um die im folgenden Teil eingetragenen Wertobjekte zu übermitteln, müssen die Variablen „\0“ bis „\9“ verwendet werden. Wobei der „Backslash“ ein Wertobjekt ‚ankündigt’ und die folgende Ziffer die Wertobjekte 1-10 bestimmt. „0“ ist Wertobjekt 1 und „9“ ist Wertobjekt 10

Zwischen Basis URL und URL-Vervollständigung wird nicht automatisch die Trennung durch ein „/“ (Slash)-Zeichen eingefügt. Dieses ist vom Benutzer entweder am Ende des Basis URLs oder am Anfang der URL-Vervollständigung zu setzen.

Werte Senden

Wertobjekte

Es können bis zu zehn Wertobjekte festgelegt werden. Jedes Wertobjekt kann folgende EIS-Typen enthalten:

• EIS 1 (1 Bit)

• EIS 5 (2 Byte FP)

• EIS 6 (1 Byte)

• EIS 9 (4 Byte FP)

• EIS 10s (2 Byte value)

• EIS 10u (2 Byte unsigned)

• EIS 11s (4 Byte value)

• EIS 14s (1 Byte value)

• EIS 14u (1 Byte unsigned)

• EIS 15 (14 Byte Text)

Adresse

Geben Sie hier die Gruppenadresse an, die das entsprechende Wertobjekt übergeben soll.

EIS-Typ

Je nach dem welcher EIS-Typ eingestellt wird, ändert sich das Formatfeld dahinter.

Format

Je nach EIS-Typisierung wird das Formatfeld eingestellt. Das Formatfeld dient dazu, dem eingehenden Wertobjekt die gewünschte Formatierung zu geben. So kann bei EIS 1 anstatt „1“ oder „0“ „EIN“ oder „AUS“ verwendet werden.

• EIS 1: Es kann ein Text für „1“ und „0“ angegeben werden.

• EIS 5 und EIS 9: Faktor und Offset sind einstellbar. Der Wert wird mit „Faktor“ multipliziert und mit „Offset“ addiert.

• EIS 6: Wird als Prozentwert von 0% bis 100% interpretiert. Das Prozentzeichen wird nicht übergeben, dieses muss ggf. in der URL-Vervollständigung eingetragen werden (mittels „%%“).

• EIS 10, EIS 11 und EIS 14: Werden direkt als Textwerte in die URL-Vervollständigung übernommen.

• EIS 15: Diese Werte werden auch direkt als Textwerte übernommen. Dadurch können völlig freie Vervollständigen aus dem EIB realisiert werden. EIS 15 lässt maximal 14 Zeichen zu.

• Leerzeichen einfügen: Soll ein Leerzeichen nach einem Wertobjekt eingefügt werden, muss „%%20“ eingetragen werden.

Antwort: Auswerten

Seit der Firmware Version 0.11.5 besitzt der HTTP Request Job auch die Möglichkeit die Antwort des Webservers auszuwerten. Dabei kann der Text der Antwort Datei mittels Regulären Ausdrücken durchsucht und nach den gewünschten Werten gefiltert werden. Das Ergebnis der Filter kann auf bis zu 4 Ausgängen auf eine KNX-Gruppenadresse gesendet werden.

Gruppen

Um die 4 Ausgänge mit Werten zu belegen, werden im regulären Ausdruck Gruppen definiert. Pro Gruppe wird ein Ausgang genutzt. Die Reihenfolge erfolgt der Leserichtung entsprechend von links nach rechts, bzw. der Syntax des regulären Ausdrucks folgend. Eine Gruppe wird durch () „Klammern“ festgelegt. Exemplarisch dargestellt also:

Ausdruck (Gruppe1=Ausgang1) Ausdruck (Gruppe2=Ausgang2) … usw.

Regulärer Ausdruck

Aufgrund dessen, dass es ein sehr komplexes Thema ist, welches den Rahmen dieser Dokumentation überschreiten würde, wird an dieser Stelle auf die diversen Dokumentationen im Internet verwiesen. Dort sind Funktion und Anwendung von regulären Ausdrucken in ausreichendem Umfang beschrieben.
Um die Anwendung im Job zu verdeutlichen ist etwas weiter unten ein Beispiel beschrieben.

Flags (Checkboxen oberhalb des Ausdrucks)

Die Flags in regulären Ausdrücken dienen dazu das Verhalten des Ausdrucks zu verändern. Bei komplexeren Ausdrücken ist das unter Umständen von Nöten, wie z.B. der Suche über mehrere Zeilen hinweg. Folgende Flags sind nutzbar:

• Case Insensitive:
  Die Groß- und Kleinschreibung wird nicht beachtet.

• Dot All:
  Der Ausdruck „.“ berücksichtig dadurch alle Zeichen. Er würde sonst Zeilenenden nicht erkennen. In anderem Kontext auch „Singleline“ genannt.

• Multiline:
  Muss verwendet werden, wenn der Ausdruck nicht nur innerhalb einer Zeile zutrifft, sondern auf mehrere Zeilen verteilt ist.

• Extended:
  Durch dieses Flag trifft der Ausdruck auch auf erweiterte Zeichen zu. So können z.B. auch auskommentierte Strings durchsucht werden.

• Ungreedy:
  Generell strebt ein regulärer Ausdruck die maximale Trefferanzahl hervorzubringen, man spricht auch von „gierig“ (engl.: „greedy“). In manchen Fällen ist das hinderlich. Das Flag „ungreedy“ bewirkt also, dass der Ausdruck nach der ersten Übereinstimmung stoppt. Wird auch durch „.*?“ im Ausdruck selber gelöst.

Ausgänge

Wie oben beschrieben werden die Ausgänge über die Gruppen im regulären Ausdruck bedient. Es sind maximal 4 Ausgänge möglich. Für jedes Adressfeld steht mittels des Pfeils der Zugriff auf die ESF-Daten zur Verfügung.

EIS Typen

Es können folgenden EIS-Typen in den Ausgängen verwendet werden. Für die EIS Typen EIS 1 und EIS 15 gelten zudem besondere Einstellungen:

• EIS 1 (1 Bit)

• EIS 5 (2 Byte FP)

• EIS 6 (1 Byte)

• EIS 9 (4 Byte FP)

• EIS 10s (2 Byte value)

• EIS 11s (4 Byte value)

• EIS 14u (1 Byte unsigned)

• EIS 15 (14 Byte Text)

EIS 1 (Modus)

Ist dieser Datentyp ausgewählt, können zwei verschiedene Modus gewählt werden.

• Wert einlesen:
  In diesem Modus wird der Wert, der durch den Ausdruck ermittelt wurde eingelesen und gesendet.

• Match Pattern:
  Gibt Auskunft darüber, ob der Ausdruck etwas ermitteln konnte oder nicht („match“).
  Je nachdem ob er „matched“ wird entweder eine „1“ oder eine „0“ gesendet.

EIS 15 (Ausgang: Format)

Ist der Datentyp EIS 15 eingestellt, kann der Ausgang über Steuerzeichen formatiert werden. Folgende Steuerzeichen sind möglich:

• „%f“ = Fließkomma Wert

• „%d“ = Dezimaler Wert

• „%s“ = Text Wert

Daten / Länge

Für die Datentypen EIS 1 bis EIS 14u muss die Datenformatierung und eventuell die Länge der Daten festgelegt werden. Hintergrund ist, dass die Daten in unterschiedlicher Formatierung vom Server zurückkommen können.

• ASCII - Unsigned long decimal: Der Inhalt besteht aus ASCII Zeichen einem 'long' Datentyp ohne Vorzeichen und dezimal codiert.

• ASCII - Signed long decimal: Dezimal mit Vorzeichen

• ASCII - Unsigned long hex: Hexadezimal ohne Vorzeichen.

• ASCII - Signed long hex: Hexadezimal mit Vorzeichen.

• ASCII - Unsigned long octal: Octal ohne Vorzeichen.

• ASCII - Signed long octal: Octal mit Vorzeichen.

• ASCII - Floating Point: Fließkomma Zahl.

• Binary - Unsigned integer little endian: Binär codierte 'integer' (Ganz)-Zahl mit Little Endian Byte Reihenfolge und ohne Vorzeichen.

• Binary - Unsigned integer big endian: Mit Big Endian Byte Reihenfolge.

• Binary - Signed integer little endian: Little Endian mit Vorzeichen.

• Binary - Signed integer big endian: Big Endian mit Vorzeichen.

• Binary - Floating Point little endian: Fließkomma Zahl mit Little Endian.

• Binary - Floating Point big endian: Fließkomma Zahl mit Big Endian.

Für alle Binary Daten muss zudem die Datenlänge festgelegt werden. Die Datenlänge kann von 1 bis 8 Byte lang sein.