Utilizzando le macro, è possibile inviare dati a un server HTTP(S) ogni volta che si desidera. È possibile scegliere quali dati inviare e strutturarli come si desidera. In questo modo, è possibile adattare i dati a un servizio già stabilito.

Misure di sicurezza:

  • La funzione di richiesta del 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 del sistema può impedire l'uso di HTTP impostando HttpClient > ConsentiHTTP su False ( xConfiguration HttpClient AllowHTTP: False ).

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

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

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

Elenco di server HTTP(S) consentiti

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

  • xCommand HttpClient Allow Hostname Add Expression: <Regular expression that matches the host name or IP address of the HTTP(S) server>

  • xCommand HttpClient Allow Hostname Clear

  • xCommand HttpClient Allow Hostname List

  • xCommand HttpClient Allow Hostname Remove Id: <id of an entry in the list>

Se l'elenco non è vuoto, è possibile inviare richieste HTTP(S) solo ai server nell'elenco. Se l'elenco è vuoto, è possibile inviare le richieste a qualsiasi server HTTP(S).

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

HTTPS senza convalida certificato

Quando si inviano richieste su HTTPS, il dispositivo controlla per impostazione predefinita il certificato del server HTTPS. Se il certificato del server HTTPS non è valido, viene visualizzato un messaggio di errore. Il dispositivo non invia dati a tale server.

Si consiglia di utilizzare 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(s)

Una volta abilitata la funzione di richiesta del 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>] [Header: <Header text>] [ResponseSizeLimit: <Maximum response size>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout period>] Url: <URL to send the request to>

L'aggiunta di campi di intestazione è opzionale, ma è possibile aggiungere fino a 20 campi.

L'icona AllowInsecureHTTPS il parametro ha effetto solo se l'amministratore di sistema ha consentito l'uso di HTTPS senza convalidare il certificato del server. In tal caso, è possibile inviare dati al server senza convalidare il certificato del server se il parametro è impostato su True . Se si abbandona il parametro o lo si imposta su False , i dati non vengono inviati se la convalida del certificato non riesce.

L'icona ResposenSizeLimit il parametro è la dimensione massima del carico utile (byte) che il dispositivo accetta come risposta dal server. Se il carico utile per la risposta è superiore a questa dimensione massima, il comando restituisce un errore di stato. Il messaggio di errore indica che la dimensione massima del file è stata superata. Tuttavia, questo non ha effetto sul lato server; il server ha ricevuto ed elaborato correttamente la richiesta.

Utilizzare la freccia ResultBody parametro 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 a conferma che sono stati rilevati dati non stampabili.

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

Inserire il carico utile (dati) subito dopo aver emesso il comando. Qualsiasi valore inserito, incluse le interruzioni di riga, fa parte del carico utile. Al termine, terminare con un'interruzione di riga ("\n") e una riga separata contenente solo un punto seguito da un'interruzione di riga (".\n"). A questo punto, il comando viene eseguito e i dati vengono inviati al server.

Esempi

Il corpo del messaggio è JSON in entrambi questi esempi. Può essere in qualsiasi formato, in base al formato previsto dal servizio che riceve i messaggi.

Esempio 1: Controllo dispositivo IoT tramite HTTP Post

Di seguito è una funzione macro che attiva una spia che è collegata a un bridge Philips Hue:


     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 effettuare le stesse operazione sulla 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 dei dati in uno strumento di monitoraggio tramite HTTP Post


     xcommand HttpClient Post Header: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"A user reported an issue with this system","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} . 
   

Ulteriori informazioni

Per ulteriori informazioni sull'utilizzo delle richieste del client HTTP, vedere la Guida per la personalizzazione . Scegliere l'ultima versione.

Il supporto Cisco (TAC) non supporta il debug di codice di terze parti, incluse le macro. Controllare la comunità degli sviluppatori di Cisco Collaboration se occorre assistenza con macro e codice di terze parti. Inoltre, su questo sito esistono molte risorse di sviluppo e integrazione.