Con le macro puoi inviare dati a un server HTTP ogni volta che ne hai bisogno. Hai il controllo su quali dati vengono inviati e su come sono organizzati, semplificando l'adattamento dei dati per l'utilizzo con i servizi esistenti.

Misure di sicurezza:

  • La funzione di richiesta client HTTP(S) è disabilitata per impostazione predefinita. Un amministratore di sistema deve abilitare esplicitamente la funzionalità impostando HttpClient > Modalità su Attivo ( Modalità xConfiguration HttpClient: Attivo ).

  • L'amministratore di sistema può impedire l'uso di HTTP impostando HttpClient > Consenti HTTP su Falso ( xConfiguration HttpClient EnableHTTP: Falso ).

  • L'amministratore di sistema può specificare un elenco di server HTTP(S) a cui il dispositivo può inviare i dati. Vedere i comandi xCommand HttpClient Allow Hostname.

  • Il numero di richieste HTTP(S) simultanee è limitato.

Le configurazioni a cui si fa riferimento in questo articolo sono disponibili sia dall'interfaccia web del dispositivo che nella API. I comandi sono disponibili tramite API. Leggere l'articolo sulle impostazioni avanzate per informazioni su come accedere all'interfaccia Web e utilizzare l'API.

Elenco di server HTTP(S) consentiti

L'amministratore di sistema può utilizzare questi comandi per impostare e gestire un elenco di fino a dieci server HTTP(S) consentiti (host):

  • xCommand HttpClient consente l'espressione di aggiunta del nome host < Espressione regolare che corrisponde al nome host o all'indirizzo IP del server HTTP(S) >

  • xCommand HttpClient consente la cancellazione del nome host

  • xCommand HttpClient consente l'elenco dei nomi host

  • xCommand HttpClient consente l'Id di rimozione del nome host: < id di una voce nell'elenco >

Se l'elenco contiene voci di server, puoi inviare richieste HTTP solo a tali server. Tuttavia, se l'elenco è vuoto, puoi inviare richieste a qualsiasi server HTTP.

Il controllo in base all'elenco dei server consentiti viene eseguito sia quando si utilizza il trasferimento di dati non protetto (HTTP) sia quello protetto (HTTPS).

HTTPS senza convalida del certificato

Quando si inviano le richieste tramite HTTPS, il dispositivo controlla il certificato del server HTTPS per impostazione predefinita. Se il certificato del server HTTPS non è valido, si riceve un messaggio di errore. Il dispositivo non invia dati al server.

Si consiglia di utilizzare l'HTTPS con la convalida del certificato. Se la convalida del certificato non è possibile, l'amministratore di sistema può impostare HttpClient > AllowInsecureHTTPS su Attivo ( xConfiguration HttpClient EnableInsecureHTTPS: Attivo ). Ciò consente l'uso di HTTPS senza convalidare il certificato del server.

Invio di richieste HTTP

Una volta attivata la funzione di richiesta client HTTP(S), è possibile utilizzare i seguenti comandi per inviare richieste a un server HTTP(S): <method> è Post, Put, Patch, Get o Delete.

  • xCommand HttpClient <Metodo> [AllowInsecureHTTPS: <True/False>] [Header: <Testo intestazione>] [ResponseSizeLimit: <Dimensione massima della risposta>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Periodo di timeout>] URL: <URL a cui inviare la richiesta>

L'aggiunta di campi di intestazione è facoltativa e puoi aggiungere fino a 20 campi.

Il parametro AllowInsecureHTTPS ha effetto solo se l'amministratore di sistema ha consentito l'utilizzo di HTTPS senza convalida del certificato del server. In questo caso, è possibile inviare i dati sul server senza convalidare il certificato del server, se il parametro è impostato su Vero. Se si prescinde dal parametro o lo si imposta su Falso, i dati non vengono inviati se la convalida del certificato ha esito negativo.

Il parametro ResposenSizeLimit è la dimensione massima del payload (byte) che il dispositivo accetta come risposta dal server. Se il payload di risposta è più grande di questa dimensione massima, il comando restituisce un errore di stato. Il messaggio di errore indica che la dimensione massima del file è stata superata. Tuttavia, non ha effetto sul lato server. Il server ha ricevuto ed elaborato la richiesta correttamente.

Utilizzare il parametro ResultBody per decidere come formattare il corpo della risposta HTTP dal server nel risultato del comando. Sono disponibili tre opzioni:

  • None: non includere il corpo della risposta HTTP nel risultato del comando.

  • Base64: Base64 codifica il corpo prima di includerlo nel risultato.

  • PlainText: includere il corpo nel risultato come testo normale. Se la risposta contiene lettere non stampabili, il comando restituisce un errore di stato con un messaggio in cui viene indicato che sono stati rilevati dati non stampabili.

Utilizzare il parametro Timeout per impostare un periodo di timeout (secondi). Se la richiesta non viene completata durante questo periodo, l'API restituisce un errore.

Immettere direttamente i (dati) payload dopo aver emesso il comando. Tutto ciò che si immette, tra cui le interruzioni di riga, fa parte del payload. Una volta terminato, completare con un'interruzione di riga ("\n") e un'altra riga che contiene solo un punto seguito da un'interruzione di riga (". \n"). Ora il comando è stato eseguito e i dati vengono inviati al server.

Esempi

Il corpo del messaggio è JSON in entrambi questi esempi. Potrebbe trattarsi di qualsiasi formato, a seconda del formato previsto del servizio che riceve i messaggi.

Esempio 1: Controllo dispositivo IoT utilizzando HTTP Post

Ecco una funzione macro che accende una luce collegata a un dispositivo Philips Hue Bridge:

 function hue_command(data) { var url = 'http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state'; var headers = 'Content-Type: application/json'; var comando = '{"on":true}'; xapi.command('HttpClient Put', { 'Url': url, 'Header': intestazioni }, comando); } 

È possibile fare lo steso in corrispondenza della riga di comando utilizzando l'API:

 xcommand HttpClient Inserisci intestazione: "Content-Type: application/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state" {"on":true} . 

Esempio 2: Pubblicazione di dati su uno strumento di monitoraggio tramite HTTP Post

 xcommand HttpClient Intestazione post: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"Un utente ha segnalato un problema con questo sistema","systemName":"BoardRoom 4th floor","softwareVersion": "ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Doppio"} . 

Ulteriori informazioni

È possibile trovare ulteriori informazioni su come utilizzare le richieste client HTTP nella Guida alla personalizzazione. Scegliere la versione più recente.

Il supporto Cisco (TAC) non supporta il debug del codice di terze parti, comprese le macro. Controlla https://roomos.cisco.com se hai bisogno di aiuto con macro e codice di terze parti.