Diese Funktion ermöglicht es Geräten der Board-, Desk- oder Room-Serie, HTTPS-Anfragen mit einem HTTPS-Server zu initiieren und zu empfangen. Diese Geräte unterstützen Methoden wie Post, Put, Patch, Get und Delete, sodass unterschiedliche Interaktionen mit dem Server möglich sind.
Mit Makros können Sie bei Bedarf Daten an einen HTTPS-Server senden. Sie haben die Kontrolle darüber, welche Daten gesendet werden und wie sie organisiert werden, sodass Sie die Daten einfach für die Verwendung mit bestehenden Diensten anpassen können.
Sicherheitsmaßnahmen:
-
Die HTTP(S)-Client-Anfragefunktion ist standardmäßig deaktiviert. Ein Systemadministrator muss die Funktion explizit aktivieren, indem er HttpClient On ( xConfiguration HttpClient Mode: On
) festlegt. -
Der Systemadministrator kann die Verwendung von HTTP verhindern, indem er HttpClient>AllowHTTP xConfiguration HttpClient AllowHTTP: False ) setzt .
-
Der Systemadministrator kann eine Liste der HTTP(S)-Server angeben, an die das Gerät Daten senden darf. (Siehe die Befehle
xCommand HttpClient Allow Hostname.) -
Die Anzahl der gleichzeitigen HTTP(S)-Anfragen ist beschränkt.
Die in diesem Artikel genannten Konfigurationen sind sowohl über die Weboberfläche des Geräts als auch in der API verfügbar. Befehle sind über die API verfügbar. Lesen Sie den Artikel Erweiterte Einstellungen, um Informationen zum Zugriff auf die Weboberfläche und zur Verwendung der API zu erhalten.
Liste der zugelassenen HTTP(S)-Server
Der Systemadministrator kann diese Befehle verwenden, um eine Liste von bis zu zehn zulässigen HTTP(S)-Servern (Hosts) einzurichten und aufrechtzuerhalten:
-
xCommand HttpClient Allow Hostname Add Expression: <Regulärer Ausdruck, der dem Hostnamen oder der IP-Adresse des HTTP(S)-Servers entspricht> -
xCommand HttpClient Allow Hostname Clear -
xCommand HttpClient Allow Hostname List -
xCommand HttpClient Allow Hostname Remove Id: <ID eines Eintrags in der Liste>
Wenn die Liste Servereinträge enthält, können Sie nur HTTPS-Anfragen an diese Server senden. Wenn die Liste jedoch leer ist, können Sie Anfragen an einen beliebigen HTTPS-Server senden.
Die Überprüfung der Liste der zulässigen Server wird sowohl bei Verwendung einer unsicheren (HTTP) als auch bei einer sicheren (HTTPS) Datenübertragung ausgeführt.
HTTPS ohne Zertifikatsprüfung
Beim Senden von Anfragen über HTTPS überprüft das Gerät standardmäßig das Zertifikat des HTTPS-Servers. Wenn festgestellt wird, dass das HTTPS-Serverzertifikat nicht gültig ist, erhalten Sie eine Fehlermeldung. Das Gerät sendet keine Daten an diesen Server.
Wir empfehlen die Verwendung von HTTPS mit Zertifikatsprüfung. Wenn die Zertifikatsüberprüfung nicht möglich ist, kann der Systemadministrator HttpClient On ( xConfiguration HttpClient AllowInsecureHTTPS: On ) setzen . Dies ermöglicht die Verwendung von HTTPS ohne Überprüfung des Serverzertifikats.
Senden von HTTPS-Anforderungen
Nachdem die HTTP(S)-Client-Anfragefunktion aktiviert ist, können Sie die folgenden Befehle zum Senden von Anfragen an einen HTTP(S)-Server verwenden. <method> ist entweder Post, Put, Patch, Get oder Delete.
-
xCommand HttpClient <Methode> [AllowInsecureHTTPS: <True/False>] [Kopfzeile: <Header-Text>] [ResponseSizeLimit: <maximale Antwortgröße>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout-Zeitraum>] URL: <URL, an die die Anforderung gesendet werden soll>
Das Hinzufügen von Kopfzeilenfeldern ist optional. Sie können bis zu 20 Felder hinzufügen.
Der AllowInsecureHTTPS-Parameter wirkt sich nur aus, wenn der Systemadministrator die Verwendung von HTTPS ohne Überprüfung des Serverzertifikats zulässt. Wenn dies der Fall ist, können Sie Daten an den Server senden, ohne das Serverzertifikat zu prüfen, wenn der Parameter auf True gesetzt ist. Wenn Sie den Parameter auslassen oder ihn auf False setzen, werden die Daten nicht gesendet, falls die Zertifikatsprüfung fehlschlägt.
Der Parameter ResposenSizeLimit ist die maximale Nutzlastgröße (Byte), die das Gerät als Antwort vom Server akzeptiert. Wenn die Antwortnutzlast größer als diese maximale Größe ist, gibt der Befehl einen Statusfehler zurück. Die Fehlermeldung besagt, dass die maximale Dateigröße überschritten wurde. Dies hat jedoch keine Auswirkungen auf die Serverseite. Der Server hat die Anforderung ordnungsgemäß empfangen und verarbeitet.
Verwenden Sie den Parameter ResultBody, um zu entscheiden, wie der Text der HTTP-Antwort vom Server im Befehlsergebnis formatiert werden soll. Sie können zwischen drei Optionen wählen:
-
None: Der Text der HTTP-Antwort wird nicht in das Befehlsergebnis eingefügt. -
Base64: Der Text wird Base64-codiert, bevor er in das Ergebnis eingefügt wird. -
PlainText: Der Text wird als Klartext in das Ergebnis eingefügt. Wenn die Antwort nicht druckbare Buchstaben enthält, gibt der Befehl einen Statusfehler mit der Meldung zurück, dass nicht druckbare Daten gefunden wurden.
Verwenden Sie den Parameter Timeout, um einen Zeitraum für die Zeitüberschreitung (Sekunden) festzulegen. Wenn die Anforderung während dieses Zeitraums nicht abgeschlossen wird, gibt die API einen Fehler zurück.
Geben Sie direkt die Nutzlast (Daten) ein, nachdem Sie den Befehl ausgegeben haben. Alles, was Sie eingeben, einschließlich der Zeilenumbrüche, ist Teil der Nutzlast. Beenden Sie die Eingabe zum Schluss mit einem Zeilenumbruch (“\n”) und einer separaten Zeile mit nur einem Punkt, gefolgt von einem Zeilenumbruch (“.\n”). Jetzt wird der Befehl ausgeführt und die Daten werden an den Server gesendet.
Beispiele
Der Nachrichtentext entspricht in beiden Beispielen JSON. Es kann ein beliebiges Format sein, je nach dem erwarteten Format des Service, der die Nachrichten erhält.
Beispiel 1: IoT-Gerätesteuerung mit HTTP-Post
Hier gibt es eine Makrofunktion, mit der eine LED eingeschaltet wird, die mit einer Philips Hue Bridge verbunden ist:
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); } Sie können gleichermaßen über die Befehlszeile mithilfe der API vorgehen:
xcommand HttpClient Put-Header: "Content-Type: application/json" URL: "http://192.0.2.10/API/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state" {"on":true} . Beispiel 2: Übermittlung von Daten an ein Überwachungstool mit HTTP Post
xcommand HttpClient Post Header: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"Ein Benutzer hat ein Problem mit diesem System gemeldet","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} . Weitere Informationen
Weitere Informationen zur Verwendung von HTTP-Client-Anfragen erhalten Sie im Anpassungsleitfaden. Wählen Sie die neueste Version.
Cisco Support (TAC) unterstützt nicht das Debuggen von Drittanbietercode, einschließlich Makros. Bitte überprüfen Sie https://roomos.cisco.com , wenn Sie Hilfe mit Makros und Code von Drittanbietern benötigen.
