es gibt ein Mega-Update für die Funktion HTTP-/REST-API
Neues Subsystem: Timberwolf Server als HTTP-/REST-API Server
Damit werden nun endlich Webhooks möglich. Dies kann genutzt werden für:
Ereignisse: Bewegungsmelder, Kameras, Smarte-Türklingeln und Zugangssysteme wie eKey können jetzt als externe Client den Timberwolf Server per HTTP über ein neues Ereignis informieren, welches über das Objektsystem und damit Logik, VISU usw. beliebig weiterverarbeitet werden kann.
Messwerte empfangen: Viele smarte Geräte und Sensoren sind in der Lage, nach der Erfassung neuer Werte eine HTTP-Anfrage zu senden. Dabei können sie verschiedene Messwerte, wie beispielsweise Temperatur und Feuchtigkeit, in der Anfrage übertragen. Diese Werte stehen sofort für das Objektsystem, z.B. Visualisierung und Logik zur Verfügung. Hierdurch entfällt die bisherige Notwendigkeit in einem regelmäßigen Intervall externe Gerät von Timberwolf Server aus auf neue Werte zu pollen.
Messwerte bereitstellen: Erstellen Sie mit der neuen Rolle als HTTP-Server eine eigene RESTful API mit der Sie jeden Wert aus dem Objektsystem des Timberwolf Servers für externe Client-Systeme im lokalen Netzwerk bereitstellen. Beispielsweise Temperaturwerte aus KNX, 1-Wire und Modbus kombiniert im selben JSON mit nahezu beliebiger Struktur.
Übersicht
Grundlagen Backup & Restore
NEU! Subsystem für die Rolle als HTTP-/REST-API-Server
Besonderheiten
DOKU
Verfügbarkeit
Grundlagen und wichtige Hinweise zu HTTP-/REST-API
Für die Nutzung des Protokolls HTTP-/REST-API ist das Verständnis diese Parameter essentiell, da diese konfiguriert werden müssen. Bitte beachte, dass die folgenden Ausführungen vereinfacht sind.
- Client-Server Modell: HTTP steht für Hypertext Transfer Protocol und ist ein Client-Server Modell. Ein Client richtet Anfragen an einen Server um Daten zu übertragen. Die Anfrage geht vom Client aus, der die Kommunikation steuert. Der Server antwortet auf nur darauf. Dies ist vergleichbar mit 1-Wire oder Modbus. Hier wird der steuernde Client als "Master" bezeichnet. Ein Server kann keine Übertragung initiieren. Insofern muss der Client für aktuelle Daten den Server (z.B. eine Webseite mit Wetterdaten) regelmäßig pollen.
Hinweis: HTTP/2 und HTTP/3 würden auch Übertragungen ermöglichen, die vom Server initiiert werden, dies wird hier nicht genutzt.
--------------------------------------------------------------------------------------------------------------------- - EINE Anfrage ("Request") - EINE Antwort ("Response"): HTTP ist ein zustandsloses Protokoll, d.h. jeder Anfrage wird unabhängig von vorherigen Anfragen behandelt. Mit der Antwort auf eine Anfrage ist eine Interaktion abgeschlossen. Der Server "erinnert" sich nicht an vorherige Interaktionen mit dem Client. Für jede einzelnen Vorgang der Datenübertragung baut der Client eine neue Verbindung auf und sendet eine Anfrage.
Hinweis: HTTP/2 und HTTP/3 können auch mehrere Abfragen / Antworten in einer Verbindung übertragen, dies wird hier nicht genutzt.
--------------------------------------------------------------------------------------------------------------------- - HTTP / HTTPS / HTTP/2 / HTTP/3: Die erste Version, HTTP/0.9 wurde erstmals 1991 veröffentlicht. Die erste verbreitete Version war HTTP/1.0 von 1996. Wenn heute von HTTP gesprochen wird, dann entweder als Synonym für die gesamte Protokollfamilie oder technisch in der am verbreitetsten Version HTTP/1.1 von 1997. Die verschlüsselte Variante wird mit der Sammelbezeichnung HTTPS bezeichnet, die ab 1994 eingeführt wurde und die HTTP-Kommunikation mit SSL bzw. TLS verschlüsselt. HTTP/2 und HTTP/3 sind optimierte Versionen von HTTP/1.1 und verkürzen Ladezeiten erheblich. Der Timberwolf Server unterstützt die beiden Varianten HTTP/1.1 und HTTP/2 sowie die Verschlüsselungen mit TLS 1.1, TLS 1.2 und TLS 1.3 (als Client) für diese. Das anzuwendende Protokoll wird automatisch zwischen Client und Server ausgewählt.
Wer es genauer wissen will: Basics des HTTP-Protokolls (English)
--------------------------------------------------------------------------------------------------------------------- - REST / REST-API / Restful-API: "REST", "REST-API" und "RESTful" bezieht sich auf den Architekturstil "Representational State Transfer" (REST), der häufig für die Gestaltung von Web-APIs verwendet wird. Die Merkmale sind Client-Server-Architektur, Zustandslosigkeit und die Nutzung von Standard-Kommunikationsmethoden. Deshalb wird zumeist HTTP verwendet. Der Client sendet eine Anfrage an die API, um etwas auszuführen, zu übertragen oder abzufragen. Alle Informationen, die für die Bearbeitung der Anfrage benötigt werden, befinden sich in der Anfrage selbst, der Server speichert keine Informationen über den Benutzer oder die vorherigen Anfragen. Im Timberwolf Server wird REST für den Datenaustausch der im Objektsystem gespeicherten Werte genutzt.
--------------------------------------------------------------------------------------------------------------------- - Unverschlüsselt / Verschlüsselt: Der Timberwolf Server unterstützt grundsätzlich die per TLS verschlüsselten Varianten von HTTP/1.1 oder HTTP/2 (= HTTPS). Fallweise kann die unverschlüsselte Nutzung von HTTP konfiguriert werden, falls der externe Server kein HTTPS unterstützt bzw. der anfragende externe Client nur eine unverschlüsselte HTTP-Verbindung aufbauen kann.
--------------------------------------------------------------------------------------------------------------------- - HTTP Strict Transport Security ("HSTS"): HTTP Strict Transport Security ist ein Sicherheitsmechanismus, der dazu dient, den Zugriff auf HTTP-Server-Ressourcen vor "Man-in-the-Middle"-Angriffen zu schützen, indem er den HTTP-Client (Browser) zwingt, ausschließlich HTTPS-Verbindungen zu nutzen. Damit ist es einem Angreifer schwieriger möglich, eine HTTPS-Verbindung auf eine unsichere HTTP-Verbindung herunterstufen (insbesondere wenn der Client schon einmal diesen Server angefragt und das HSTS Kennzeichen im Cache gespeichert hat). Der HTTP-Server des Timberwolf Servers sendet grundsätzlich das HSTS-Merkmal im Header aus. Auch dann, wenn ein HTTP-Endpunkt konfiguriert ist, zusätzlich HTTP zu erlauben. Üblicherweise beachten ältere Implementierungen eines HTTP-Clients dieses Einstellung nicht, bzw. diese kann z.B. bei wget abgestellt werden.
--------------------------------------------------------------------------------------------------------------------- - Zertifikatsprüfung: Zertifikate dienen der Authentifizierung - in der Regel durch den HTTP-Server. Diese Zertifikate enthalten auch den / die URLs. Browser bauen verschlüsselte Verbindungen nur dann auf, wenn die Gültigkeit des Zertifikat (durch Signatur durch anerkannte Zertifizierungsstellen) geprüft wurde und die URL mit der dieser Server angesprochen wird, mit der / den URLs im Zertifikat übereinstimmt. Die Verschlüsselung wird hier von der Authentifizierung des Server-Zertifikats abhängig gemacht.
--------------------------------------------------------------------------------------------------------------------- - Authentifiziert / Unauthentifiziert: Es stehen mehrere Authentifizierungen zur Verfügung wie "Basic-Authentication"; "Digest-Authentication" (nur als Client, ab IP8); mit Bearer Token und per API-Key. Derzeit nicht unterstützt werden "Mutual" Authentifizierung mit einem Client-Zertifikat, OATH und JWT (für letzteres kann teilweise Bearer-Token genutzt werden).
--------------------------------------------------------------------------------------------------------------------- - Die drei Elemente einer HTTP-Anfrage / Antwort: HTTP Header, Body und URI sind wichtige Bestandteile einer HTTP-Nachricht (in der Abfrage und in der Antwort). Der Header enthält Metadaten über die Anfrage oder Antwort, der Body enthält die eigentlichen Daten und die URI (Uniform Resource Identifier) identifiziert die Ressource, auf die zugegriffen wird.
--------------------------------------------------------------------------------------------------------------------- - URI(Uniform Resource Identifier): Die URI identifiziert die Ressource, auf die zugegriffen werden soll. Sie besteht aus mehreren Teilen, wie z.B. dem Protokoll (http oder https), dem Host (z.B. www.example.com), dem Pfad (z.B. /users/123) und optionalen Parametern (die für die Authentifizierung und die Datenübertragung genutzt werden können). Beispielsweise ist https://www.example.com/users/abc?id=123 eine vollständige URI, die auf eine Benutzerressource mit der ID 123 zugreift.
--------------------------------------------------------------------------------------------------------------------- - HTTP Header: Der Header besteht aus einer Reihe von Feldern, die zusätzliche Informationen über die Nachricht enthalten. Jedes Feld hat einen Namen und einen Wert ("Key / Value"), getrennt durch einen Doppelpunkt. Header können verwendet werden, um Informationen über den Client, den Server, den Inhaltstyp, die Sprache, die Kodierung und vieles mehr zu übermitteln. Üblich genutzte Header-Felder sind Content-Type, Content-Length, User-Agent und Authorization. Es gibt Headerfelder für Anfragen und für Antworten.
Weitere Informationen: https://de.wikipedia.org/wiki/Liste_der ... aderfelder
--------------------------------------------------------------------------------------------------------------------- - HTTP Body: Der Body enthält die eigentlichen Daten der Nachricht, z.B. den Inhalt einer Webseite, Formulardaten oder eine JSON-Datei. Er ist optional und wird nicht immer benötigt bzw. ist nicht immer möglich, z.B. bei GET-Anfragen. Der Header enthält Informationen über den Body, wie z.B. den Content-Type, um dem Empfänger mitzuteilen, wie er den Body interpretieren soll.
--------------------------------------------------------------------------------------------------------------------- - HTTP-Anfragemethoden (GET / PUT / POST): Das HTTP-Protokoll definiert Anfragemethoden ("requests methods") wie GET usw. Der Timberwolf Server unterstützt GET, PUT und POST.
--------------------------------------------------------------------------------------------------------------------- - HTTP-Statuscode: Ein HTTP-Statuscode wird von einem Server auf jede HTTP-Anfrage als Antwort geliefert. Über den HTTP-Statuscode erhält der Client eine Information, ob die Anfrage erfolgreich bearbeitet wurde bzw. über Warnungen und Fehler. Im Fehlerfall gibt der Statuscode Auskunft darüber, wo (beispielsweise über eine Umleitung) oder wie (zum Beispiel mit Authentifizierung) er die gewünschten Informationen erhalten kann. Am bekanntesten sind dabei die Codes 404: „Nicht gefunden“, 403: „Fehlende Zugriffsberechtigung“ und 400: „Fehlerhafte Anfrage“. Die HTTP-Statuscodes werden über automatisch bereitgestellten Statusobjekte als Integer und als Text zur Verfügung gestellt und können mit anderen Objekten verknüpft und z.B. in der Logik ausgewertet werden.
Liste der HTTP-Statuscodes: https://de.wikipedia.org/wiki/HTTP-Statuscode
--------------------------------------------------------------------------------------------------------------------- - Nur Triggern (Webhook): Damit kann ein HTTP-Server durch den Client auf ein Ereignis aufmerksam gemacht werden. Hierfür müssen oft keine weiteren Daten übertragen werden, es genügt der Aufruf der URI.
--------------------------------------------------------------------------------------------------------------------- - Daten übergeben und / oder abfragen: Das HTTP-/REST-API System des Timberwolf Servers erlaubt die Übertragung von Daten, abhängig von der Anfragemethode, in der URI, im Header und im Body.
Liste der Datenaustauschoptionen im Wiki: https://elabnet.atlassian.net/wiki/x/AYCsx
--------------------------------------------------------------------------------------------------------------------- - Eine Anfrage auslösen: Im Timberwolf Server ist für das Ausführen von Anfragen an einen HTTP-Server ein Auslöser zu konfigurieren, damit auch eine Anfrage ausführt wird (in der Rolle als HTTP-Client). In der Rolle als HTTP-Server wartet der Timberwolf Server auf hereinkommende Anfragen, hier ist kein Auslöser notwendig.
Die möglichen Auslöser Liste der Datenaustauschoptionen im Wiki: https://elabnet.atlassian.net/wiki/x/AYCsx
--------------------------------------------------------------------------------------------------------------------- - Systemobjekte: Eine Besonderheit der Implementierung des HTTP-/REST-API Systems des Timberwolf Servers sind die automatisch angelegten Systemobjekte bei jeder Ressource. Hierüber lassen sich die Statuscodes anzeigen und diese auch zu nutzen, z.B. als Trigger für eingehende Requests.
NEU! Subsystem für die Rolle als HTTP-/REST-API-Server
HTTP-/REST-API Server Subsystem initalisieren
Um das neue "HTTP-/REST-API Server" Subsystem zu nutzen muss man hierfür eine Instanz aktivieren.
1. Unter Menupunkt HTTP-API-> Subsysteme die Schaltfläche [+ HTTP-API Server hinzufügen} klicken:
2. Bezeichnung für dieses Subsystem eingeben und Timeout setzen (oder Vorgabe übernehmen):
Hinweis: Die Bezeichnung kann man auch nachträglich ändern, zum Beispiel unter Objektsystem -> Subsystem Manager
Wichtiger Hinweis:
- Vom Subsystem "HTTP-/REST-API Client" können mehrere Instanzen angelegt werden
- Vom neuen Subsystem "HTTP-/REST-API Server" kann NUR EINE Instanz angelegt werden
Endpunkt einrichten
Damit der Timberwolf Server HTTP-Requests empfangen kann, muss ein Endpunkt angelegt werden.
1. Das richtige Subsystem auswählen (hier das SERVER-Subsystem)
2. Die Schaltfläche [+ Neuer Endpunkt hinzufügen]
3. Bezeichnung eingeben
4. Pfad der URI angeben (für jeden Endpunkt kann eine anderer Pfad gewählt werden
5. Autorisierung auswählen (Konto und Passwort kann man sich zufällig hinzufügen lassen)
6. Server hinzufügen betätigen
Ressource zum Endpunkt hinzufügen
1. Schaltfläche [+ Ressource hinzufügen] betätigen
2. Bezeichnung eingeben
3. Pfad für diese Ressource angeben (dieser wird an die Basis-URL & Endpunkt angehängt, dies wird oben beim Eingeben angezeigt)
4. Abfragemethode auswählen (so wie vom Client unterstützt, bei GET werden keine Daten im Body der Anfrage ausgewertet)
5. Bei PUT & POST den Inhaltstyp für vom Client bei der Anfrage übergebene Daten auswählen (sonst reicht GET)
6. Inhaltstyp für zurückgegebene Daten auswählen (damit können Sie Daten mit der Antwort zurück geben)
7. Die Schaltfläche [Ressource hinzufügen] betätigen
Statusobjekte per Default - Eines für Trigger
Sobald eine Ressource - beim HTTP-/REST-API Server Subsystem - einem Endpunkt hinzugefügt wurde, werden die Statusobjekte automatisch generiert.
Die Bezeichnung dieser Objekte richtet sich nach der vergebenen Bezeichnung für den Endpunkt und die Ressource. Bei späteren Änderungen dieser Bezeichnungen werden die autom. generierten Objektbezeichnungen nicht mehr geändert (kann aber manuell vorgenommen werden).
Der Aufbau der Statusobjekte ist beim HTTP-/REST-API Server Subsystem KOMPLETT UNTERSCHIEDLICH von den Statusobjekte bei bisherigen HTTP-/REST-API Client Subsystem
Unterschiede:
HTTP-/REST-API Client Subsystem: Die Statusobjekte zeigen die Status (Mehrzahl) an, die der TWS als Client vom externen Server zurückbekommen hat.
HTTP-/REST-API Server Subsystem (wie auf dem Bild unten): Die Statusobjekte enthalten die Statuscodes, die der TWS als Server dem zuletzt anfragenden externen Client (es könnten auch mehrere sein) zurückgegeben hat plus Boolesche Objekte für Warning und Error und einem Objekt, das für Trigger genutzt werden kann.
Statusobjekt "Trigger" nutzen
Dieses Statusobjekt kann genutzt werden, um an verknüpfte Objekte einen Trigger zu senden.
Beispiel hierfür ist die Nutzung mit eKey New Generation. Der Fingerprint Reader kann über seinen Controller kann bei Erkennung eines Fingers so einen Trigger auslösen (man kann zwar auch weitere Daten, wie Bezeichnung des Fingers usw. übertragen, aber wenn das nicht erforderlich ist, kann ein Trigger pro erkennbarem Finger durchaus ausreichend sein).
Wichtig:
- Dieser Trigger sendet ausschließlich TRUE. Jeder Aktualisierung des Objektwertes wird immer nur TRUE enthalten
- Im Fall eines nicht erfolgreichen Aufrufs (z.B. falscher Username / Passwort, Inkompatibilität usw.) wird dieser Trigger nicht aktualisiert (stattdessen die anderen Statusobjekte).
1. Einfach nur Verknüpfung hinzufügen
Auswertung HTTP Anfrage hinzufügen
Um die bei der Anfrage übergebenen Daten auszuwerten (= einem oder mehreren Objekten zuzuweisen) können Auswertungs-Transaktionen hinzugefügt werden.
Die Auswahlmöglichkeiten in diesem Assistenten hängen von der beim Anlegen der Ressource gewähltem Ort des Inhaltes (URL, Header, Body) und bei Body auch vom dort angegebenen Inhaltstyp ab.
1. Schaltfläche [+ Auswertung HTTP Anfrage hinzufügen] betätigen
2. Eine Bezeichnung eingeben
3. Ort der Datenübermittlung auswählen
4. Abhängig davon Feldname oder Selektor angeben (wählt aus mehrere Datenfeldern das richtige aus)
5. Das Datenformat wählen (mit diesem Datentyp wird das Format des erstellten Objektes bestimmt, dies kann später nicht mehr geändert werden, außer über Löschen und Neuanlage dieser Transaktion).
6. GGfls. noch die Objekteinheit angeben
7. Die Schaltfläche [Transktion hinzufügen] betätigen
Antwortende Transaktion auf HTTP Anfrage hinzufügen
Um bei einer Anfrage auch Daten an den anfragenden Client übergeben zu können (= Werte aus einem oder mehreren Objekten zurückgeben) können ein oder mehrere antwortende Transaktionen hinzugefügt werden.
1. Schaltfläche [+ Objekt zur HTTP Antwort hinzufügen] betätigen
2. Eine Bezeichnung eingeben
3. Ort der Datenübermittlung auswählen
4. Abhängig davon Feldname oder Selektor angeben (wählt aus mehrere Datenfeldern das richtige aus)
5. Das Datenformat wählen (mit diesem Datentyp wird das Format des erstellten Objektes bestimmt, dies kann später nicht mehr geändert werden, außer über Löschen und Neuanlage dieser Transaktion).
6. GGfls. noch die Objekteinheit angeben
7. Die Schaltfläche [Transktion hinzufügen] betätigen
Besonderheiten
Symbole angepasst
Wir haben die Symbole für das bisherige "Subsystem HTTP-/REST-API Client" geändert, um deutlicher zu machen, dass dieses das Client Subsystem ist:
Änderung: Zuvor stand enthielt das Symbol nur drei Punkte in der Mitte
Das Symbol für das "Subsystem HTTP-/REST-API Client" ist neu hinzugekommen:
Es setzt sich durch Form (eckig), Farbe und Bezeichnung deutlich ab
Mouse-Over mit allen Host-Adressen
Der Timberwolf Server ist - je nach Konfiguration - über mehrere Netzwerkschnittstellen erweiterbar.
Diese sind
- Ethernet, mehrere Namensauflösungen möglich
- Ethernet über die lokale IP-Adresse
- interne Docker-Schnittstelle (hier aus Docker zu erreichen)
Mouseover, der die URLs anzeigt, über welche ein Client den Server erreichen kann:
Konfigurationsübersicht & Datenfluss
Damit man schneller sieht, welche Form des Zugriffes, Methoden und Inhaltstypen konfiguriert wurden und wie der Datenfluss insgesamt ist, gibt es eine neue Darstellung.
Neue Übersicht über den Datenfluss
Hier sieht man nun, der externe Client sendet eine HTTP-Anfrage vom Typ POST und übergibt Daten, die form-urlencodet sind an den Timberwolf Server. Dieser antwortet mit Daten, die als json formatiert sind zurück an den Client.
Darunter sieht man die URL des Endpunktes und dieser Ressourcen
Kein Auslöser beim Server-Subsystem
Beim bisherigen "Subsystem HTTP-/REST-API Client" musste ein Auslöser konfiguriert werden, um die Anfrage an den externen Server zu starten.
Bei dem neuen "Subsystem HTTP-/REST-API Server" wird jegliche Aktion durch externe Clients (es dürften auch mehrere parallel sein) gesteuert, welche die Anfrage selbst auslösen, daher ist hier kein Auslöser zu konfigurieren.
Doku
Doku im Wiki (wird noch erweitert): https://elabnet.atlassian.net/wiki/x/AQAXbg
Verfügbarkeit
Diese neuen Funktionen stehen mit der IP 8 zur V 4.5 seit 31. Juli 2025 zur Verfügung.
Über die Verfügbarkeit dieser neuen Funktionen in einer Hauptversion können wir im Moment keine belastbaren Angaben treffen.
lg
Das Team von ElabNET
