Con le macro, è possibile inviare dati a un server HTTP ogni volta che è necessario. Hai il controllo su quali dati vengono inviati e su come sono organizzati, semplificando l'adattamento dei dati per l'uso con i servizi esistenti.

Misure di sicurezza:

  • La funzione di richiesta client HTTP(S) è disabilitata per impostazione predefinita. Un amministratore di sistema deve abilitare in modo esplicito la funzione impostando HttpClient > Mode su On ( xConfiguration HttpClient Mode: On ).

  • L'amministratore di sistema può impedire l'utilizzo di HTTP impostando HttpClient > AllowHTTP su False ( xConfiguration HttpClient AllowHTTP: False ).

  • 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 di cui al presente articolo sono disponibili sia dall'interfaccia web del dispositivo che nel API. I comandi sono disponibili tramite il 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, è possibile inviare richieste HTTP solo a tali server. Tuttavia, se l'elenco è vuoto, è possibile 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 On ( xConfiguration HttpClient AllowInsecureHTTPS: On ). 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 <Method> [AllowInsecureHTTPS: <True/False>] [Intestazione: <testo dell'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 ed è possibile 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 command = '{"on":true}'; xapi.command('HttpClient put', { 'Url': url, 'Header': headers }, command); }

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

 xcommand HttpClient Put Header: "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 Post Header: "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":"Dual"} .

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. Si prega di controllare https://roomos.cisco.com se hai bisogno di aiuto con macro e codice di terze parti.