Mithilfe von Makros können Sie zu einem beliebigen Zeitpunkt Daten an einen HTTP(S)-Server senden. Sie können auswählen, welche Daten gesendet werden, und sie wie gewünscht strukturieren. Auf diese Weise können Sie die Daten an einen bereits eingerichteten Dienst anpassen.

Sicherheitsmaßnahmen:

  • Die HTTP(S)-Client-Anfragefunktion ist standardmäßig deaktiviert. Ein Systemadministrator muss die Funktion explizit aktivieren, indem HttpClient > Modus auf Ein (xConfiguration HttpClient Mode: On) festgelegt wird.

  • Der Systemadministrator kann die Verwendung von HTTP verhindern, indem er HttpClient > AllowHTTP aufFalse (xConfiguration HttpClient AllowHTTP: False) festlegt

  • 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 Konfigurationen, auf die in diesem Artikel Bezug genommen wird, stehen sowohl über die Weboberfläche des Geräts als auch über die API zur Verfügung. Die Befehle sind in der 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 nicht leer ist, können Sie HTTP(S)-Anfragen nur an die Server in der Liste senden. Wenn die Liste leer ist, können Sie die Anfragen an einen beliebigen HTTP(S)-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 Zertifikatsprüfung nicht möglich ist, kann der Systemadministrator HttpClient > AllowInsecureHTTPS auf Ein (xConfiguration HttpClient AllowInsecureHTTPS: On) festlegen. Dies ermöglicht die Verwendung von HTTPS ohne Überprüfung des Serverzertifikats.

Senden von HTTP(S)-Anfragen

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 <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>

Das Hinzufügen von Header-Feldern ist optional, aber 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":"A user reported an issue with this system","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. Schauen Sie in der Cisco Collaboration Developer-Community nach, wenn Sie Hilfe bei Makros und Drittanbietercodes benötigen. Darüber hinaus finden Sie auf dieser Website viele Ressourcen für Entwickler und Integratoren.