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

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 la modalità HttpClient > su On (xConfiguration HttpClient: On).

  • L'amministratore di sistema può impedire l'utilizzo del protocollo HTTP impostandoHttpClient > 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 che vengono definite in questo articolo, sono disponibili sia dall'interfaccia Web del dispositivo sia nell'API. I comandi sono disponibili nell'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 non è vuoto, è possibile inviare le richieste HTTP(S) solo ai server presenti nell'elenco. Se l'elenco è vuoto, è possibile inviare le richieste a qualunque 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 non è possibile la convalida del certificato, 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 delle richieste HTTP(S)

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>] [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 dell'intestazione è facoltativa, ma è possibile aggiungere un massimo di 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":"A user reported an issue with this system","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. Consultare la community Cisco Collaboration Developer se si desidera assistenza relativamenete a macro e codice di terze parti. Inoltre, su questo sito sono presenti molte risorse per sviluppatori e integratori.