Integrazione HTTP
Il protocollo HTTP integra dispositivi e servizi che utilizzano HTTP semplice: API REST, servizi cloud con un’API locale o semplici relè di rete. Funziona in due direzioni:
- Richieste in uscita — quando cambia il valore di un widget, HyperVisu invia una richiesta (controllo del dispositivo o chiamata webhook).
- Interrogazione periodica — HyperVisu richiede periodicamente un URL ed estrae un valore dalla risposta in un oggetto del widget.
Connessioni. Attiva prima HTTP Protocol nella pagina Services (vedi «Servizi e protocolli»); su un nuovo server è disattivato. HTTP supporta più connessioni: una per Base URL, ciascuna con i propri Poll Interval (seconds), Timeout (ms) e autenticazione (vedi «Connessioni»). Il timeout è in millisecondi, da 1000 a 120000; lasciandolo vuoto, una richiesta attende 30 secondi.
Scegli l’Authentication Type richiesto dall’API. Cambiare il tipo svuota tutti i campi delle credenziali.
| Authentication Type | Dati da fornire | Modalità di invio |
|---|---|---|
| None | Nessuna credenziale. | Non viene aggiunto nulla. |
| API Key (Header) | Header Name e API Key. | Un’intestazione con quel nome e la chiave. |
| API Key (Query Parameter) | Query Parameter e API Key. | Aggiunti all’URL di ogni richiesta. |
| Basic Authentication | Username e Password. | L’intestazione di autorizzazione Basic standard. |
| Bearer Token | Bearer Token. | L’intestazione di autorizzazione Bearer standard. |
| Custom Headers | Una riga per intestazione, con nome e valore; Add Header aggiunge una riga. | Ogni riga, con ogni richiesta. |
Compila entrambi i campi di una coppia: una coppia con un campo vuoto non viene inviata. API Key, Password e Bearer Token sono mascherati nell’editor; i valori inseriti in Custom Headers sono mostrati in chiaro.
Una connessione HTTP non ha un pulsante Test. Il suo stato rimane State unknown finché un oggetto associato non ha scambiato una richiesta; Connected indica quindi che l’ultima richiesta è stata accettata e No reply since compare dopo una richiesta non riuscita.
📘 Nota: Un intervallo di interrogazione di
0rende la connessione di sola scrittura — non viene interrogato nulla, vengono inviate solo richieste in uscita. Anche un intervallo vuoto significa che l’endpoint non viene mai interrogato: inserisci il valore, il60grigio è solo un suggerimento.
Associazione di un oggetto. Per ogni oggetto imposta Path e HTTP Method e, per i valori interrogati, come estrarre la lettura dalla risposta con Parse Method e Parse Path:
- JSON — un percorso con sintassi a punti e array, ad esempio
data.sensors[0].temperature. Un indice negativo come[-1]legge l’ultimo elemento; filtri e caratteri jolly non sono supportati. - Pattern Matching — per risposte non JSON. Parse Path deve iniziare con
PATTERN=, ad esempioPATTERN=Temp:\s\v. Cambiare il metodo di analisi svuota Parse Path, quindi inseriscilo dopo aver scelto il metodo.
Per le richieste in uscita, imposta HTTP Method su POST o PUT e scegli Content Type. Request Body Template è un modello in cui ${value} viene sostituito con il valore inviato, ad esempio {"state": ${value}}.
📘 Nota: L’interrogazione periodica invia sempre un GET al Path dell’oggetto. Un oggetto POST o PUT invia una richiesta solo quando il suo valore cambia.
Esempio pratico — qualità dell’aria esterna dall’API di un sensore locale
Un monitor locale della qualità dell’aria espone GET http://192.168.1.140/api/current, restituisce {"pm25": 8.4, "aqi": 35} e richiede la chiave API in un’intestazione X-Api-Key.
- Crea una connessione HTTP: Base URL
http://192.168.1.140, Poll Interval (seconds)60, Timeout (ms)5000, Authentication Type API Key (Header), Header NameX-Api-Key, la chiave in API Key (vedi «Connessioni»). - In Devices, aggiungi un widget Analog Input «Qualità dell’aria». In Protocol, seleziona la tua connessione HTTP, elencata con il nome che le hai assegnato.
- Sul suo oggetto valore imposta Path su
/api/current, lascia HTTP Method su GET e Parse Method su JSON e inserisciaqiin Parse Path. - Fai clic su Save object, poi su Apply changes nella barra laterale e conferma. La lettura si aggiorna ogni minuto; imposta unità e decimali sull’oggetto (vedi «Impostazioni degli oggetti, registrazione e notifiche»).
- Dopo l’interrogazione successiva, verifica che la connessione mostri Connected nella pagina Connections, quindi confronta il widget con la risposta effettiva dell’API.
Associazione HTTP
Gli oggetti HTTP si configurano anche nella finestra di impostazione dell’oggetto (vedi «Impostazioni degli oggetti, registrazione e notifiche»). La sezione HTTP definisce una richiesta per oggetto:
| Campo | Descrizione |
|---|---|
| Path | Aggiunto all’URL di base della connessione (ad esempio weather?q=London). |
| HTTP Method | GET, POST o PUT. |
| Content Type | Per POST/PUT: JSON, TEXT o FORM. JSON e FORM impostano l’intestazione del tipo di contenuto corrispondente; TEXT non ne invia alcuna. |
| Parse Method | JSON — la risposta è JSON e Parse Path identifica il valore. Pattern Matching — la risposta è testo e Parse Path contiene un modello. La guida alla sintassi integrata documenta entrambi. Cambiare il metodo di analisi svuota Parse Path, quindi scegli prima il metodo. |
| Parse Path | Con JSON: un percorso semplice — notazione a punti (data.power), indice di array (sensors[0]), indice negativo ([-1] per l’ultimo elemento) e prefisso facoltativo $.. Filtri e caratteri jolly non sono supportati. Con Pattern Matching: il modello, che deve iniziare con PATTERN= — ad esempio PATTERN=Temp:\s\v. |
| Request Body Template | Per POST/PUT: il corpo da inviare, con ${value} come segnaposto per il valore scritto — ad esempio {"state":${value}}. |
La lettura utilizza l’intervallo di interrogazione della connessione; un intervallo di 0 rende l’endpoint di sola scrittura (vedi «Connessioni»). L’interrogazione periodica invia sempre un GET al Path dell’oggetto; un oggetto POST o PUT invia la propria richiesta solo quando il suo valore cambia. Un esempio pratico si trova nel capitolo HTTP.