HTTP-integratie
Het HTTP-protocol integreert apparaten en diensten die gewoon HTTP gebruiken: REST-API’s, clouddiensten met een lokale API of eenvoudige netwerkrelais. Het werkt in twee richtingen:
- Uitgaande verzoeken — wanneer de waarde van een widget verandert, verstuurt HyperVisu een verzoek (apparaatbediening of webhook-aanroep).
- Periodiek opvragen — HyperVisu bevraagt periodiek een URL en haalt een waarde uit het antwoord op voor een widgetobject.
Verbindingen. Schakel eerst HTTP Protocol in op de pagina Services (zie ‘Diensten en protocollen’); dit staat uit op een nieuwe server. HTTP ondersteunt meerdere verbindingen: één verbinding per Base URL, elk met een eigen Poll Interval (seconds), Timeout (ms) en authenticatie (zie ‘Verbindingen’). De time-out is in milliseconden, van 1000 tot 120000; bij een leeg veld wacht een verzoek 30 seconden.
Kies het Authentication Type dat de API vereist. Bij een wijziging van het type worden alle velden met aanmeldgegevens leeggemaakt.
| Authentication Type | Benodigde gegevens | Hoe ze worden verzonden |
|---|---|---|
| None | Geen aanmeldgegevens. | Er wordt niets toegevoegd. |
| API Key (Header) | Header Name en API Key. | Een header met die naam en de sleutel. |
| API Key (Query Parameter) | Query Parameter en API Key. | Toegevoegd aan de URL van elk verzoek. |
| Basic Authentication | Username en Password. | De standaard Basic-autorisatieheader. |
| Bearer Token | Bearer Token. | De standaard Bearer-autorisatieheader. |
| Custom Headers | Eén rij per header, met naam en waarde; Add Header voegt een rij toe. | Elke rij, bij elk verzoek. |
Vul beide velden van een paar in: een paar met één leeg veld wordt niet verzonden. API Key, Password en Bearer Token worden gemaskeerd in de editor; waarden onder Custom Headers worden leesbaar weergegeven.
Een HTTP-verbinding heeft geen Test-knop. De status blijft State unknown totdat een gebonden object een verzoek heeft uitgewisseld; Connected betekent dan dat het laatste verzoek is geaccepteerd, en No reply since verschijnt na een mislukt verzoek.
📘 Opmerking: Een opvraaginterval van
0maakt de verbinding alleen schrijfbaar — er wordt niets opgevraagd, alleen uitgaande verzoeken worden verzonden. Een leeg opvraaginterval betekent ook dat het eindpunt nooit wordt bevraagd: voer de waarde in, de grijze60is slechts een hint.
Een object binden. Stel per object Path en HTTP Method in en geef voor opgevraagde waarden met Parse Method en Parse Path aan hoe de meetwaarde uit het antwoord wordt gehaald:
- JSON — een pad met puntnotatie en arraysyntaxis, bijvoorbeeld
data.sensors[0].temperature. Een negatieve index zoals[-1]leest het laatste element; filters en jokertekens worden niet ondersteund. - Pattern Matching — voor antwoorden zonder JSON. Parse Path moet beginnen met
PATTERN=, bijvoorbeeldPATTERN=Temp:\s\v. Bij wijziging van de parseermethode wordt Parse Path leeggemaakt; voer dit dus in nadat u de methode hebt gekozen.
Stel voor uitgaande verzoeken HTTP Method in op POST of PUT en kies Content Type. Request Body Template is een sjabloon waarin ${value} wordt vervangen door de verzonden waarde, bijvoorbeeld {"state": ${value}}.
📘 Opmerking: Periodiek opvragen verstuurt altijd een GET naar het Path van het object. Een POST- of PUT-object verstuurt alleen een verzoek wanneer de waarde verandert.
Uitgewerkt voorbeeld — buitenluchtkwaliteit via de API van een lokale sensor
Een lokale luchtkwaliteitsmeter biedt GET http://192.168.1.140/api/current aan, geeft {"pm25": 8.4, "aqi": 35} terug en vereist de API-sleutel in een X-Api-Key-header.
- Maak een HTTP-verbinding: Base URL
http://192.168.1.140, Poll Interval (seconds)60, Timeout (ms)5000, Authentication Type API Key (Header), Header NameX-Api-Key, de sleutel in API Key (zie ‘Verbindingen’). - Voeg in Devices een Analog Input-widget ‘Luchtkwaliteit’ toe. Selecteer onder Protocol uw HTTP-verbinding, weergegeven met de naam die u hebt opgegeven.
- Stel op het waardeobject Path in op
/api/current, laat HTTP Method op GET en Parse Method op JSON staan en voeraqiin bij Parse Path. - Klik op Save object, vervolgens op Apply changes in de zijbalk en bevestig. De meetwaarde wordt elke minuut bijgewerkt; stel eenheden en decimalen in op het object (zie ‘Objectinstellingen, logging en meldingen’).
- Controleer na de volgende opvraging of de verbinding Connected toont op de pagina Connections en vergelijk vervolgens de widget met het daadwerkelijke API-antwoord.
HTTP-binding
HTTP-objecten worden ook ingesteld in het dialoogvenster voor objectinstellingen (zie ‘Objectinstellingen, logging en meldingen’). De HTTP-sectie definieert één verzoek per object:
| Veld | Beschrijving |
|---|---|
| Path | Toegevoegd aan de basis-URL van de verbinding (bijvoorbeeld weather?q=London). |
| HTTP Method | GET, POST of PUT. |
| Content Type | Voor POST/PUT: JSON, TEXT of FORM. JSON en FORM stellen de bijbehorende content-type-header in; TEXT verstuurt er geen. |
| Parse Method | JSON — het antwoord is JSON en Parse Path benoemt de waarde. Pattern Matching — het antwoord is tekst en Parse Path bevat een patroon. De geïntegreerde syntaxishulp beschrijft beide. Bij wijziging van de parseermethode wordt Parse Path leeggemaakt; kies dus eerst de methode. |
| Parse Path | Met JSON: een eenvoudig pad — puntnotatie (data.power), een array-index (sensors[0]), een negatieve index ([-1] voor het laatste element) en een optioneel voorvoegsel $.. Filters en jokertekens worden niet ondersteund. Met Pattern Matching: het patroon, dat moet beginnen met PATTERN= — bijvoorbeeld PATTERN=Temp:\s\v. |
| Request Body Template | Voor POST/PUT: de te verzenden inhoud, met ${value} als plaatsaanduiding voor de geschreven waarde — bijvoorbeeld {"state":${value}}. |
Lezen gebruikt het opvraaginterval van de verbinding; een opvraaginterval van 0 maakt het eindpunt alleen schrijfbaar (zie ‘Verbindingen’). Periodiek opvragen verstuurt altijd een GET naar het Path van het object; een POST- of PUT-object verstuurt zijn verzoek alleen wanneer de waarde verandert. Een uitgewerkt voorbeeld staat in het HTTP-hoofdstuk.