Konfiguration

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.

• Methode: Hier kann festgelegt werden, ob die Authentifizierung über GET oder POST gesendet wird.
• Login URL: Hier kann der Pfad für die Anmeldung angegeben werden. Dieser ist unabhängig von der Basis URL.
• Header: Hier können Header für die Login-Anfrage angegeben werden. Diese müssen als JSON-String angegeben werden.
• Token: Hier kann festgelegt werden, ob der benötigte Token in der Antwort des REST Services im Header oder im Body enthalten ist.
• Position: Hier wird die Position des Tokens in der Antwort angegeben, z. B. „login-token“ im Header.
• Inkludieren in: Hier kann festgelegt werden, ob der ausgelesene Token bei weiteren Anfragen im Header oder im Body mitgesendet wird.
• Position: Hier wird die Position angegeben, an der der Token bei weiteren Anfragen eingefügt wird, z. B. „x-token“ im Header.
• Periodisch Einloggen: Hier kann festgelegt werden, ob eine periodische Anmeldung erfolgen soll und in welchem Abstand.

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:

• Default: Hier können die im Smart Building Automation System angelegten Benutzer verwendet werden. Siehe REST Service Authentifizierung
• Basic: Hier können die im Smart Building Automation System angelegten Benutzer verwendet werden. Siehe Basic Authentication
• Digest: Hier können ein eigener Benutzername und ein eigenes Passwort vergeben werden. Siehe Digest Authentication
• Keine: Für die Verwendung des Webhooks ist keine Authentifizierung erforderlich.

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.

Ü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:

• REST Anfrage: Ermöglicht das Senden von Befehlen und allgemeinen Anfragen an einen REST Service, ohne die Rückmeldung weiterzuverarbeiten.
• REST Boolean: Ermöglicht das Abfragen von Boolean-Werten eines REST Services, die anschließend im System weiterverwendet werden können.
• REST Nummer: Ermöglicht das Abfragen von Zahlenwerten eines REST Services, die anschließend im System weiterverwendet werden können.
• REST Text: Ermöglicht das Abfragen von Textwerten eines REST Services, die anschließend im System weiterverwendet werden können.

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.

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.