Mit der App „REST Client“ können Funktionen auf Geräten ausgeführt werden, für die keine eigene App im Smart Building Automation System zur Verfügung steht, welche jedoch über eine REST-Schnittstelle verfügen.
Für die Verwendung des REST Clients sind grundlegende Kenntnisse über die Funktionsweise von REST sowie über die Schnittstelle des anzubindenden Geräts erforderlich.
Eine kurze Einführung in REST ist hier zu finden.
Die App „REST Client“ ist unter „Alle Apps“ zu finden.
Um einen neuen REST Client zu erstellen, navigieren Sie zur App und wählen Sie „Client hinzufügen“.
In den Einstellungen können allgemeine Einstellungen für den REST Client konfiguriert werden, beispielsweise die Verbindungsdaten.
Verbindung
HTTP / HTTPS
Hier kann festgelegt werden, ob der REST Service über eine verschlüsselte Verbindung (HTTPS) zur Verfügung steht.
Host
Hier kann die IP- oder Webadresse des REST Services angegeben werden.
Port
Hier kann der Port des REST Services angegeben werden.
Basis URL
Viele REST Services verwenden einen festen Basispfad, an den alle weiteren Anfragen angehängt werden. Dieser kann hier angegeben werden, z. B. „/api“.
Self-Signed Zertifikate zulassen
Ist diese Option aktiviert, werden Zertifikatsfehler ignoriert. Dadurch kann auch auf APIs mit einem selbstsignierten oder abgelaufenen Zertifikat zugegriffen werden.
Globale Header
Hier können Header angegeben werden, die bei jeder Anfrage mitgesendet werden sollen. Diese müssen als JSON-String angegeben werden.
Authentifizierung
Es stehen drei Authentifizierungsmethoden zur Verfügung: keine, Basic und Benutzerdefiniert.
Keine
Bei der Auswahl „Keine“ erfolgt vor dem Senden von Anfragen keine Authentifizierung.
Basic
Bei der Authentifizierungsmethode „Basic“ können ein Benutzername und ein Passwort mitgesendet werden. Diese Methode kann verwendet werden, wenn der REST Service Basic Authentication unterstützt.
Benutzerdefiniert
Für andere Authentifizierungsmethoden steht eine benutzerdefinierte Authentifizierung zur Verfügung.
Webhooks
Webhooks können verwendet werden, um Ereignisse als Auslöser für Szenen im Smart Building Automation System zu verwenden. Beispielsweise kann über eine 2N Innensprechstelle ein Button definiert werden, der die Eingangstür öffnet. Dazu wird in der Innensprechstelle die URL hinterlegt, die bei aktivierten Webhooks in den Anfragen des REST Clients angezeigt wird.
Um Webhooks für den REST Client zu aktivieren, muss die Option „Webhooks aktivieren“ ausgewählt werden.
Unter „Webhook Authentifizierung“ kann die gewünschte Authentifizierungsmethode festgelegt werden.
Folgende Optionen stehen zur Verfügung:
Damit die Webhooks verwendet werden können, müssen diese zusätzlich bei den jeweiligen Anfragen aktiviert werden. Weitere Informationen dazu sind weiter unten zu finden.
Damit die Einstellungen übernommen werden, muss der Button „Einstellungen übernehmen“ ausgewählt werden.
Über den Button „Anfragen bearbeiten“ wird die Ansicht der Anfragen für den REST Client geöffnet. Hier können neue Anfragen angelegt und bestehende Anfragen bearbeitet werden.
Über „Anfrage hinzufügen“ kann eine neue Anfrage erstellt werden.
Folgende Typen stehen zur Auswahl:
In den Einstellungen einer Anfrage kann festgelegt werden, welche Daten gesendet werden sollen.
Methode
Hier kann die HTTP-Methode für die Anfrage ausgewählt werden.
Url
Hier kann der Pfad angegeben werden, an den die Anfrage gesendet wird. Dieser wird an den Host und die Basis URL angehängt.
Header
Hier können Header angegeben werden, die mit der Anfrage gesendet werden sollen. Diese müssen als JSON-String angegeben werden.
Body
Hier kann der Inhalt angegeben werden, der im Body der Anfrage gesendet werden soll. Der Body muss als JSON-String angegeben werden.
Zyklisch
Hier kann festgelegt werden, ob die Anfrage zyklisch gesendet werden soll und in welchem Abstand.
Bei Fehler erneut versuchen
Ist diese Option aktiviert, kann festgelegt werden, wie oft die Anfrage bei einem Fehler erneut gesendet werden soll. Als Fehler gilt dabei eine Antwort ohne Statuscode zwischen 200 und 299.
Benutzerdefiniertes Timeout
Ist diese Option aktiviert, kann ein Timeout in Millisekunden festgelegt werden, nach dessen Ablauf die Anfrage abgebrochen wird.
Verwende JSON Parse
Liegen die Rückgabedaten im JSON-Format vor, kann mit dieser Funktion auf einzelne Properties im JSON-Objekt zugegriffen werden. Besteht das Objekt aus mehreren Ebenen oder Arrays, kann der Selektor entsprechend erweitert werden (z. B. id.name, id[3].value, ...).
Einheit
Bei Zahlenwerten kann zusätzlich eine Einheit angegeben werden, die bei der Anzeige des Werts ergänzt wird.
Über „Anfrage schicken“ kann die Anfrage testweise gesendet werden. Dadurch kann geprüft werden, ob die Einstellungen korrekt sind. Die Antwort wird anschließend angezeigt.
Zum Testen des REST Clients kann die Webseite „https://jsonplaceholder.typicode.com/“ verwendet werden. Dieser Webserver stellt JSON-Testdaten in verschiedenen Formaten zur Verfügung (z. B. https://jsonplaceholder.typicode.com/users).
Webhook
Sind Webhooks im REST Client aktiviert, kann für jede Anfrage ein eigener Webhook aktiviert werden. Für jede Anfrage wird eine eigene URL erzeugt, wodurch unterschiedliche Ereignisse umgesetzt werden können.
Zum Aktivieren muss die Option „Webhook aktivieren“ ausgewählt werden.
Anschließend kann die Methode festgelegt werden. Diese bestimmt, mit welcher HTTP-Methode die Anfrage an das Smart Building Automation System gesendet wird.
Die Änderungen müssen anschließend über den Button „Speichern“ gespeichert werden.
Danach kann der erzeugte Link kopiert und im entsprechenden Service hinterlegt werden.
In Szenen steht anschließend der Auslöser (Wenn ...) „Webhook wurde aufgerufen“ zur Verfügung.
Webhooks stehen derzeit nur im lokalen Netzwerk zur Verfügung.
Im Operator Panel des REST Clients werden alle angelegten Anfragen angezeigt. Diese können direkt gesendet werden.
Auch unter „Anfragen bearbeiten“ können die angelegten Anfragen direkt gesendet werden.
Die Anfragen können auch in anderen Bereichen des Smart Building Automation Systems verwendet werden, beispielsweise in Szenen.
