HttpUtils: Unterschied zwischen den Versionen
Zeile 195: | Zeile 195: | ||
''mandatory'' | ''mandatory'' | ||
|| Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten.<br><br> | || Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt.<br><br> | ||
Beispiel: | Beispiel: | ||
* ''<nowiki>http://www.myhost.com/directory/</nowiki>'' | * ''<nowiki>http://www.myhost.com/directory/</nowiki>'' | ||
* ''<nowiki>https://www.myhost.com/</nowiki>'' | |||
* ''<nowiki>http://www.myhost.com:8080/</nowiki>'' | * ''<nowiki>http://www.myhost.com:8080/</nowiki>'' | ||
* ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>'' | * ''<nowiki>http://foo:bar@www.myhost.com/</nowiki>'' |
Version vom 31. Mai 2014, 12:07 Uhr
Allgemein
Das Modul HttpUtils.pm ist sowohl für Modulentwickler, als auch Endanwender gedacht um Daten via HTTP auszutauschen. Es stellt dabei eine Reihe von Funktionen bereit, auf die in diesem Artikel näher eingegangen werden soll.
Erstellt wurde HttpUtils.pm von Rudolf König.
Die Funktionen im Einzelnen
Es ist zu beachten, dass bei den Funktionen
- GetHttpFile
- GetFileFromURL
- GetFileFromURLQuiet
- HttpUtils_BlockingGet
ein sogenannter "blockierender" Aufruf durchgeführt wird. Dass bedeutet, dass FHEM bei einem Aufruf einer dieser Funktionen solange wartet und dabei absolut nichts macht solange bis die Antwort vom HTTP Server eintrifft und die Funktion damit beendet ist. Das kann bei Verbindungsproblemen evtl. dazu führen, dass FHEM für die gesamte Wartezeit (Timeout) steht und nichts verarbeitet. Problematisch ist so etwas gerade bei Anwendungen oder Hardware die eine zeitnahe Reaktion von FHEM erwarten (z.B. HomeMatic Geräte).
Es wird daher empfohlen die Funktionen so sparsam wie möglich zu verwenden und die Timeouts so niedrig wie möglich zu halten um ein längeres Einfrieren von FHEM möglichst zu verhindern.
Alternativ kann man die Funktion
- HttpUtils_NonblockingGet
verwenden, welche ein Blockieren von FHEM verhindert. Wie das genau funktioniert, wird in dem entsprechenden Kapitel beschrieben.
Folgende Funktionen sind für Modulentwickler/Endanwender zur direkten Nutzung gedacht:
GetHttpFile
Die Funktion GetHttpFile ist die denkbar einfachste Variante um eine URL aufzurufen.
Aufruf: GetHttpFile($server, $file)
Parameter | Bedeutung |
---|---|
$server
mandatory |
Der DNS Name oder die IP-Adresse des HTTP-Servers Beispiel:
|
$file
mandatory |
Die Datei, welche auf dem HTTP-Server aufgerufen werden soll. Beispiel:
|
Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.
GetFileFromURL
Die Funktion GetFileFromURL ruft die HTTP URL auf und gibt als Funktionsergebnis den Seiteninhalt zurück. Im Gegensatz zu GetHttpFile beinhaltet GetFileFromURL einige Zusatzoptionen in Form von Funktionsparametern.
Aufruf: GetFileFromURL($url, [$timeout], [$data], [$noshutdown], [$loglevel])
Parameter | Bedeutung |
---|---|
$url
mandatory |
Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Beispiel:
|
$timeout
optional |
Die maximale Dauer in Sekunden für die HTTP-Anfrage
Standardwert: 4 Sekunden |
$data
optional |
Wenn man Daten via HTTP POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.
|
$noshutdown
optional |
Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abwartet.
|
$loglevel
optional |
Das Loglevel in dem sämtliche Logmeldungen zu dieser HTTP Abfrage erzeugt werden sollen.
|
Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.
GetFileFromURLQuiet
Diese Funktion funktioniert ähnlich wie GetFileFromURL. Allerdings wird die tatsächliche URL in allen erzeugten Log-Meldungen unkenntlich gemacht um z.B. Zugangsdaten nicht preiszugeben. Die aufgerufene Seite wird ebenfalls als Funktionsergebnis zurückgegeben.
Aufruf: GetFileFromURLQuiet($url, [$timeout], [$data], [$noshutdown], [$loglevel])
Parameter | Bedeutung |
---|---|
$url
mandatory |
Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Beispiel:
|
$timeout
optional |
Die maximale Dauer in Sekunden für die HTTP-Anfrage
Standardwert: 4 Sekunden |
$data
optional |
Wenn man Daten via HTTP POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.
|
$noshutdown
optional |
Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abwartet.
|
$loglevel
optional |
Das Loglevel in dem sämtliche Logmeldungen zu dieser HTTP Abfrage erzeugt werden sollen.
|
Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.
HttpUtils_BlockingGet
Wenn die bisher genannten Funktionen nicht ausreichen um die gewünschte Abfrage durchzuführen, so kann man diese Funktion verwenden. Aufgrund zahlreicher Parameter ermöglicht sie viele Anpassungsmöglichkeiten. Diese Funktion hat dabei nicht wie üblich eine Liste an Funktionsparametern, sondern lediglich einen Parameter, welcher ein Hash mit allen Funktionsparametern darstellt. Dieser Hash enthält sämtliche Parameter inkl. Werten.
Aufruf: HttpUtils_BlockingGet($param)
Der Hash $param kann folgende Optionen beinhalten:
Parameter | Bedeutung |
---|---|
$param->{url}
mandatory |
Die HTTP URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. Beispiel:
|
$param->{timeout}
optional |
Die maximale Dauer in Sekunden für die HTTP-Anfrage
Standardwert: 4 Sekunden |
$param->{data}
optional |
Wenn man Daten via HTTP POST übertragen möchte, so kann man die Nutzdaten über $param{data} übergeben. Die Daten werden dabei als Formulardaten übertragen. Die Daten können dabei auf zwei Arten übergeben werden:
1. Daten als String:
2. Daten als Hash:
|
$param->{noshutdown}
optional |
Wenn $param->{noshutdown} auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abwartet.
|
$param->{loglevel}
optional |
Das Loglevel in dem sämtliche Logmeldungen zu dieser HTTP Abfrage erzeugt werden sollen.
|
$param->{hideurl}
optional |
Wenn dieser Parameter den Wert 1 trägt, wird die URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies ist nützlich um z.B. Zugangsdaten geheim zu halten.
|
$param->{method}
optional |
Die HTTP Methode, welche zur Abfrage verwendet werden soll. Sofern keine Daten übertragen werden ist dies standardmäßig "GET", ansonsten "POST". Es können aber auch andere Methoden verwendet werden.
|
$param->{header}
optional |
Eigene HTTP-Header Zeilen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. den Content-Type festzulegen, oder einfach nur zusätzliche Header-Felder zu setzen. Mehrere Header-Zeilen müssen dabei mit "\r\n" getrennt werden.
|
Als Rückgabewert von HttpUtils_BlockingGet wird ein Array mit 2 Rückgabewerten zurückgegeben:
($err, $data) = HttpUtils_BlockingGet( … )
Diese 2 Rückgabewerten haben folgende Bedeutung:
Rückgabewert | Bedeutung |
---|---|
$err |
Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.
|
$data |
Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben.
|
HttpUtils_NonblockingGet
Diese Funktion arbeitet ähnlich wie HttpUtils_BlockingGet. Allerdings wird das Ergebnis nicht als Funktionsergebnis zurückgegeben. Die Funktion HttpUtils_NonblockingGet initiert den Verbindungsaufbau und übergibt alles weitere an FHEM interne Routinen. Sobald eine Antwort vom HTTP-Server eintrifft, wird eine Callback-Funktionen mit verschiedenen Parametern (unter anderem auch das Ergebnis) aufgerufen, um die Antwort entgegenzunehmen und weiter zu verarbeiten.
Der Aufruf ist daher ähnlich zu HttpUtils_BlockingGet mit nur einem Parameter-Hash:
Aufruf: HttpUtils_NonblockingGet($param)
Parameter | Bedeutung |
---|---|
Alle Hash-Parameter, welche für HttpUtils_BlockingGet gelten, sind auch für HttpUtils_NonblockingGet gültig | |
$param->{callback}
mandatory |
Eine Funktion (oder eine Referenz auf eine Funktion), welche die Ergebnisdaten entgegen nimmt und die Antwort entsprechend weiterverarbeitet. Die Callback-Funktion muss dabei 3 Parameter erwarten. Die Funktionsparameter der Callback-Funktion werden im nachfolgenden Abschnitt näher erläutert.
|
Benutzerdefinierte Parameter | Es können im Hash weitere benutzerdefinierte Parameter gesetzt werden, welche evtl. in der Callback-Funktion benötigt werden, um die Antwort korrekt zu verarbeiten.
Zum Beispiel bei der Modul-Programmierung währe das $hash des aktuellen Devices. Alle gesetzten Parameter sind in der Callback-Funktion direkt abrufbar und können ausgewertet werden.
|
Ein Funktionsrückgabewert von HttpUtils_NonblockingGet existiert nicht, da die eigentliche Rückgabe der Daten über die Callback-Funktion erfolgt. Die Callback-Funktion wird aufgerufen, sobdald der HTTP-Request abgeschlossen ist, oder ein Fehler aufgetreten ist. Der Funktionsaufruf erfolgt mit den folgenden Parametern:
CallbackFunction ( $param, $err, $data )
Diese 3 Parameter haben dabei folgende Bedeutung:
Parameter | Bedeutung |
---|---|
$param |
Der Parameter-Hash, mit allen Argumenten die beim Aufruf der Funktion übergeben worden sind.
Es ist möglich, dass der Parameter-Hash nach erfolgter Abfrage zusätzliche oder veränderte Elemente enthält:
|
$err |
Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.
|
$data |
Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben.
|
Die Callback-Funktion kann nun die Daten aus der HTTP Antwort verarbeiten oder bei Fehler entsprechende Log-Meldungen ausgeben.