Mit der App "REST Client" können Sie auch Funktionen auf Geräten auslösen, für welche es keine eigene evon Smart Home App gibt, welche jedoch über eine REST Schnittstelle verfügen.
Für die Verwendung von REST benötigen Sie ein Verständnis für die Funktionsweise von REST und die Schnittstellen die Ihnen das Gerät bietet, welches Sie anbinden wollen.
Eine kurze Beschreibung zu REST finden Sie hier.
Sie finden die "REST Client" App unter Alle Apps.
Um einen neuen REST Client zu erstellen, navigieren Sie zur App und wählen Sie "Client hinzufügen".
In den Einstellungen können Sie Allgemeine Einstellungen für den Client vergeben, wie zum Beispiel die Verbindungsdaten.
Verbindung
HTTP / HTTPS
Hier können Sie angeben ob der REST Service über eine Verschlüsselte Verbindung (HTTPS) zur Verfügung steht oder nicht.
Host
Hier können Sie die IP-/Web-Adresse des REST Services angeben.
Port
Hier können Sie den Port des REST Services angeben.
Basis URL
Viele REST Services haben einen fixen Basis Pfad von welchem ausgehend alle weiteren Anfragen angehängt werden, diesen können Sie hier mitangeben. Z.B.: "/api".
Self-Signed Zertifikate zulassen
Wenn diese Option gesetzt wurde, werden Zertifikatsfehler ignoriert. So ist es möglich auf APIs zuzugreifen, welche ein Self-Signed Zertifikat haben oder das Zertifikat bereits abgelaufen ist.
Globale Header
Hier können Sie Header angeben welche mit jeder Anfrage mitgesendet werden sollen. Diese müssen als JSON String angegeben werden.
Authentifizierung
Es gibt drei vorhandene Authentifizierungsmethoden welche unterstützt werden: keine, Basic, Benutzerdefiniert.
keine
Wenn "keine" gewählt ist wird keine Authentifizierung vor dem Senden von Anfragen geschickt.
Basic
Bei "Basic" können Sie einen Benutzernamen und ein Passwort mitschicken. Diese Authentifizierungsmethode kann gewählt werden wenn der REST Service Basic Authentifizierung unterstützt.
Benutzerdefiniert
Für andere Authentifizierungsmethoden gibt es die Möglichkeit einer Benutzerdefinierten Authentifizierung.
Webhooks
Webhooks können genutzt werden, um Events für Szenen in evon Smart Home auszulösen. Zum Beispiel um von der 2n Innensprechstelle einen Button zu definieren, der die Eingangstür im evon Smart Home System öffnet. Hierfür wird z.B. in der 2n Innensprechstelle die URL hinterlegt, welche im REST Client in den Anfragen angezeigt wird, wenn Webhooks aktiviert wurden.
Um Webhooks für den REST Client zu aktivieren muss die Option "Webhooks aktivieren" aktiviert werden.
Unter dem Punkt "Webhook Authentifizierung" kann die Authentifizierungsmethode gewählt werden.
Hier stehen folgende Optionen zur Verfügung:
Damit die Webhooks genutzt werden können, müssen diese noch in den Anfragen aktiviert werden. Siehe weiter unten.
Damit die Einstellungen übernommen werden muss der Button "Einstellungen übernehmen" gedrückt werden.
Über den Button "Anfragen bearbeiten" kommen Sie auf die Ansicht der Anfragen für den REST Client. Hier können Sie neue Anfragen anlegen und bestehende bearbeiten.
Mit "Anfrage hinzufügen" können Sie eine neue Anfrage erstellen.
Hier haben Sie die Auswahl zwischen folgenden Typen:
In den Einstellungen von Anfragen können Sie definieren was in der Anfrage gesendet werden soll.
Methode
Hier können Sie auswählen mit welcher HTTP Methode die Anfrage gesendet werden soll.
Url
Hier können Sie angeben auf welchen Pfad die Anfrage gesendet werden soll. Dieser wird dann zusätzlich zum Host und Basis Pfad angehängt.
Header
Hier können Sie Header angeben welche mit der Anfrage mitgesendet werden sollen. Diese müssen als JSON String angegeben werden.
Body
Hier können Sie angeben was im Body der Anfrage gesendet werden soll. Der Body muss als JSON String angegeben werden.
Zyklisch
Hier können Sie angeben ob die Anfrage Zyklisch gesendet werden soll und in welchem Abstand.
Bei Fehler erneut versuchen
Wenn diese Option gesetzt wurde, kann angegeben werden wie oft bei einem Fehler (keine Rückmeldung eines Statuscodes zwischen 200 und 299) ein erneuter Versuch der Anfrage gesendet werden soll.
Benutzerdefiniertes Timeout
Wenn diese Option gesetzt wurde kann ein Timeout in Millisekunden angegeben werden, nach welcher die Anfrage abgebrochen werden soll.
Verwende JSON Parse
Sollten die Rückgabedaten im JSON-Format sein, kann mit dieser Funktion auf jedes Property im JSON-Object gesucht werden. Sollte das Object aus mehreren Ebenen oder Arrays bestehen kann der Selektor beliebig erweitert werden (z.B.: id.name, id[3].value, ...)
Einheit
Bei Nummer Abfragen können Sie zusätzlich eine Einheit angeben, welche dann in der Anzeige zum Wert hinzugefügt wird
Sie können Ihre Anfrage mit "Anfrage schicken" senden, um zu testen ob alle Einstellungen richtig gesetzt sind und bekommen die Antwort angezeigt.
Zum Testen der Funktion des REST-Clients kann die Webseite "https://jsonplaceholder.typicode.com/" empfohlen werden. Dieser Webserver bietet JSON-Testdaten in verschiedenen Formaten an (z.B.: https://jsonplaceholder.typicode.com/users)
Webhook
Wenn im REST Client Webhooks aktiviert wurden, kann pro Anfrage der Webhook aktiviert werden. Hier wird pro Anfrage eine eigene URL angelegt, womit unterschiedliche Events umgesetzt werden können.
Um den Webhook zu aktivieren muss die Option "Webhook aktivieren" aktiviert werden.
Danach kann die Methode angegeben werden, diese entscheidet darüber mit welcher HTTP Methode die Anfrage an das evon Smart Home System gestellt werden soll.
Um die Änderungen zu übernehmen müssen diese mit dem Button "Speichern" gespeichert werden.
Danach kann der Link kopiert werden und im entsprechenden Service eingetragen werden.
In den Szenen steht dann der Auslöser (Wenn ...) "Webhook wurde aufgerufen" zur Verfügung.
Aktuell stehen Webhooks nur im lokalen Netzwerk zur Verfügung.
In der Bedienung des REST Clients werden Ihnen die Anfragen angezeigt und können gleich gesendet werden.
Auch unter "Anfragen bearbeiten" können Sie die Anfragen senden.
Außerdem können die Anfragen auch an anderen Stellen Ihres evon Smart Home verwendet werden, wie zum Beispiel in den Szenen.
