Kann HyperVisu Werte aus einer HTTP-API lesen?

Ja. Es fragt die konfigurierte URL ab und extrahiert einen Wert über einen JSON-Pfad oder ein Textmuster.

Wie mache ich einen HTTP-Endpunkt nur beschreibbar?

Setzen Sie das Abfrageintervall der Verbindung auf 0. Ausgehende Anfragen funktionieren weiterhin, regelmäßige Leseabfragen werden jedoch gestoppt.

Wie füge ich den Widgetwert in eine Anfrage ein?

Verwenden Sie den Platzhalter ${value} in der Vorlage für den Anfrageinhalt. HyperVisu ersetzt ihn durch den gesendeten Wert.

Wo wird die HTTP-Authentifizierung konfiguriert?

An der Verbindung. Zur Auswahl stehen API-Schlüssel, Basic-Authentifizierung, Bearer-Token und benutzerdefinierte Header.

HTTP-Integration

Das HTTP-Protokoll integriert Geräte und Dienste, die gewöhnliches HTTP verwenden: REST-APIs, Cloud-Dienste mit lokaler API oder einfache Netzwerkrelais. Es arbeitet in zwei Richtungen:

Ausgehende Anfragen — wenn sich der Wert eines Widgets ändert, sendet HyperVisu eine Anfrage (Gerätesteuerung oder Webhook-Aufruf).
Regelmäßige Abfragen — HyperVisu fragt regelmäßig eine URL ab und übernimmt einen aus der Antwort extrahierten Wert in ein Widgetobjekt.

Verbindungen. Aktivieren Sie zuerst HTTP Protocol auf der Seite Services (siehe „Dienste und Protokolle“); auf einem neuen Server ist es deaktiviert. HTTP unterstützt mehrere Verbindungen: eine Verbindung pro Base URL, jeweils mit eigenem Poll Interval (seconds), Timeout (ms) und eigener Authentifizierung (siehe „Verbindungen“). Das Zeitlimit wird in Millisekunden angegeben, von 1000 bis 120000; bleibt das Feld leer, wartet eine Anfrage 30 Sekunden.

Wählen Sie den von der API benötigten Authentication Type. Ein Wechsel des Typs leert alle Felder für Zugangsdaten.

Authentication Type	Einzutragende Angaben	Übertragung
None	Keine Zugangsdaten.	Es wird nichts hinzugefügt.
API Key (Header)	Header Name und API Key.	Ein Header mit diesem Namen und dem Schlüssel.
API Key (Query Parameter)	Query Parameter und API Key.	Wird der URL jeder Anfrage hinzugefügt.
Basic Authentication	Username und Password.	Der standardmäßige Basic-Autorisierungsheader.
Bearer Token	Bearer Token.	Der standardmäßige Bearer-Autorisierungsheader.
Custom Headers	Eine Zeile pro Header mit Name und Wert; Add Header fügt eine Zeile hinzu.	Jede Zeile bei jeder Anfrage.

Füllen Sie beide Felder eines Paares aus: Ein Paar mit einem leeren Feld wird nicht gesendet. API Key, Password und Bearer Token werden im Editor maskiert; unter Custom Headers eingegebene Werte werden im Klartext angezeigt.

Eine HTTP-Verbindung hat keine Schaltfläche Test. Ihr Status bleibt State unknown, bis ein gebundenes Objekt eine Anfrage ausgetauscht hat; Connected bedeutet dann, dass die letzte Anfrage akzeptiert wurde, und No reply since erscheint nach einer fehlgeschlagenen Anfrage.

📘 Hinweis: Ein Abfrageintervall von 0 macht die Verbindung nur beschreibbar — es erfolgen keine Abfragen, sondern nur ausgehende Anfragen. Ein leeres Abfrageintervall bedeutet ebenfalls, dass der Endpunkt niemals abgefragt wird: Geben Sie den Wert ein, die graue 60 ist nur ein Hinweis.

Ein Objekt binden. Stellen Sie je Objekt Path und HTTP Method ein und legen Sie für abgefragte Werte mit Parse Method und Parse Path fest, wie der Messwert aus der Antwort extrahiert wird:

JSON — ein Pfad mit Punkt- und Arraysyntax, z. B. data.sensors[0].temperature. Ein negativer Index wie [-1] liest das letzte Element; Filter und Platzhalter werden nicht unterstützt.
Pattern Matching — für Antworten ohne JSON. Parse Path muss mit PATTERN= beginnen, beispielsweise PATTERN=Temp:\s\v. Ein Wechsel der Auswertungsmethode leert Parse Path; geben Sie den Pfad daher nach der Methodenwahl ein.

Für ausgehende Anfragen setzen Sie HTTP Method auf POST oder PUT und wählen Content Type. Request Body Template ist eine Vorlage, in der ${value} durch den gesendeten Wert ersetzt wird, z. B. {"state": ${value}}.

📘 Hinweis: Regelmäßige Abfragen senden immer ein GET an den Path des Objekts. Ein POST- oder PUT-Objekt sendet nur dann eine Anfrage, wenn sich sein Wert ändert.

Praxisbeispiel — Außenluftqualität über die API eines lokalen Sensors

Ein lokaler Luftqualitätsmonitor stellt GET http://192.168.1.140/api/current bereit, liefert {"pm25": 8.4, "aqi": 35} zurück und benötigt den API-Schlüssel in einem X-Api-Key-Header.

Erstellen Sie eine HTTP-Verbindung: Base URL http://192.168.1.140, Poll Interval (seconds) 60, Timeout (ms) 5000, Authentication Type API Key (Header), Header Name X-Api-Key, den Schlüssel in API Key (siehe „Verbindungen“).
Fügen Sie unter Devices ein Analog Input-Widget „Luftqualität“ hinzu. Wählen Sie unter Protocol Ihre HTTP-Verbindung aus, die mit dem vergebenen Namen aufgeführt wird.
Setzen Sie am Wertobjekt Path auf /api/current, lassen Sie HTTP Method auf GET und Parse Method auf JSON, und tragen Sie aqi in Parse Path ein.
Klicken Sie auf Save object, dann auf Apply changes in der Seitenleiste und bestätigen Sie. Der Messwert wird jede Minute aktualisiert; stellen Sie Einheiten und Dezimalstellen am Objekt ein (siehe „Objekteinstellungen, Protokollierung und Benachrichtigungen“).
Prüfen Sie nach der nächsten Abfrage, ob die Verbindung auf der Seite Connections den Status Connected zeigt, und vergleichen Sie das Widget anschließend mit der tatsächlichen API-Antwort.

HTTP-Bindung

HTTP-Objekte werden auch im Dialog für die Objekteinstellungen konfiguriert (siehe „Objekteinstellungen, Protokollierung und Benachrichtigungen“). Der HTTP-Bereich definiert eine Anfrage je Objekt:

Feld	Beschreibung
Path	Wird an die Basis-URL der Verbindung angehängt (z. B. `weather?q=London`).
HTTP Method	GET, POST oder PUT.
Content Type	Für POST/PUT: JSON, TEXT oder FORM. JSON und FORM setzen den passenden Content-Type-Header; TEXT sendet keinen.
Parse Method	JSON — die Antwort ist JSON und Parse Path bezeichnet den Wert. Pattern Matching — die Antwort ist Text und Parse Path enthält ein Muster. Die integrierte Syntaxhilfe beschreibt beides. Ein Wechsel der Auswertungsmethode leert Parse Path; wählen Sie daher zuerst die Methode.
Parse Path	Mit JSON: ein einfacher Pfad — Punktnotation (`data.power`), ein Array-Index (`sensors[0]`), ein negativer Index (`[-1]` für das letzte Element) und ein optionales vorangestelltes `$.`. Filter und Platzhalter werden nicht unterstützt. Mit Pattern Matching: das Muster, das mit `PATTERN=` beginnen muss — z. B. `PATTERN=Temp:\s\v`.
Request Body Template	Für POST/PUT: der zu sendende Inhalt mit `${value}` als Platzhalter für den geschriebenen Wert — z. B. `{"state":${value}}`.

Für das Lesen wird das Abfrageintervall der Verbindung verwendet; ein Abfrageintervall von 0 macht den Endpunkt nur beschreibbar (siehe „Verbindungen“). Regelmäßige Abfragen senden immer ein GET an den Path des Objekts; ein POST- oder PUT-Objekt sendet seine Anfrage nur bei einer Wertänderung. Ein Praxisbeispiel steht im HTTP-Kapitel.

HTTP-Integration