Mit dieser Funktion können beliebige HTTP(S)-Anforderungen von einem Board,-Raum- oder -Tischgerät an einen HTTP(S)-Server gesendet werden. Außerdem erhält das Gerät die Antwort, die der Server zurücks sendet. Das Gerät unterstützt die Methoden Post, Put, Patch, Get und Delete.
Mit Makros können Sie Daten jederzeit an einen HTTP(S)-Server senden. Sie können auswählen, welche Daten gesendet werden sollen, und sie so strukturieren, wie Sie möchten. Auf diese Weise können Sie die Daten an einen bereits eingerichteten Dienst anpassen.
Sicherheitsmaßnahmen:
Die ANFORDERUNGsfunktion für den HTTP(S)-Client ist standardmäßig deaktiviert. Ein Systemadministrator muss die Funktion explizit aktivieren, indem er den
(xConfiguration HttpClient Mode: On
).Der Systemadministrator kann die Verwendung von HTTP verhindern, indem er
(xConfiguration HttpClient AllowHTTP: False
).Der Systemadministrator kann eine Liste der HTTP(S)-Server angeben, an die das Gerät Daten senden darf. (Siehe
xCommand HttpClient Allow Hostname
Befehle.)Die Anzahl der gleichzeitigen HTTP(S)-Anfragen ist begrenzt.
Die in diesem Artikel genannten Konfigurationen sind sowohl über die Weboberfläche des Geräts als auch in der API verfügbar. Befehle sind in der API verfügbar. Lesen Sie den Artikel Erweiterte Einstellungen, um zu erfahren, wie Sie auf die Weboberfläche zugreifen und die API verwenden können.
Liste zulässiger HTTP(S)-Server
Der Systemadministrator kann mithilfe dieser Befehle bis zu zehn erlaubte HTTP(S)-Server (Hosts) einrichten und verwalten:
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>
Wenn die Liste nicht leer ist, können Sie HTTP(S)-Anforderungen 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 zulässiger Server wird sowohl bei unsicherer (HTTP) als auch bei sicherer (HTTPS) Datenübertragung durchgeführt.
HTTPS ohne Zertifikatvalidierung
Wenn Anfragen über HTTPS gesendet werden, überprüft das Gerät standardmäßig das Zertifikat des HTTPS-Servers. Wenn 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 für die Zertifikatvalidierung. Wenn keine Zertifikatvalidierung möglich ist, kann der Systemadministrator httpClient
xConfiguration HttpClient AllowInsecureHTTPS: On
). Dies ermöglicht die Verwendung von HTTPS, ohne das Zertifikat des Servers zu validieren.
SENDEN VON HTTP(S)-Anforderungen
Nachdem die HTTP(S)-Client-Anforderungsfunktion aktiviert wurde, können Sie die folgenden Befehle verwenden, um Anfragen an einen HTTP(S)-Server zu senden.
<method>
ist entweder
Post
,
Put
,
Patch
,
Get
oder
Delete
definiert.
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 Kopfzeilenfeldern ist optional, Sie können jedoch bis zu 20 Felder hinzufügen.
Das Symbol
AllowInsecureHTTPS
parameter hat nur Auswirkungen, wenn der Systemadministrator die Verwendung von HTTPS ohne Validierung des Servers-Zertifikats zugelassen hat. Wenn ja, können Sie Daten an den Server senden, ohne das Serverzertifikat zu validieren, wenn der Parameter auf
True
definiert. Wenn Sie den Parameter nicht verwenden oder ihn auf
False
werden keine Daten gesendet, wenn die Zertifikatvalidierung fehlschlägt.
Das Symbol
ResposenSizeLimit
Parameter ist die maximale Nutzdatenladungsgröße (Bytes), die das Gerät als Antwort vom Server akzeptiert. Wenn die Antwort-Nutzlast größer ist als diese maximale Größe, gibt der Befehl einen Statusfehler zurück. Die maximale Dateigröße wird in der Fehlermeldung überschritten. Dies wirkt sich jedoch nicht auf die Serverseite aus; der Server hat die Anforderung ordnungsgemäß empfangen und verarbeitet.
Benutzen Sie
ResultBody
Parameter, um zu entscheiden, wie der Text der HTTP-Antwort vom Server in der Befehlsergebnis formatiert wird. Sie haben drei Möglichkeiten:
None
: Fügen Sie den Text der HTTP-Antwort nicht in das Befehlsergebnis ein.Base64
: Base64 verschlüsseln Sie den Text, bevor Sie ihn in das Ergebnis eingeben.PlainText
: Fügen Sie den Text als Untext in das Ergebnis ein. Wenn die Antwort nicht druckbare Buchstaben enthält, gibt der Befehl einen Statusfehler mit der Meldung zurück, dass nicht druckbare Daten angetroffen wurden.
Benutzen Sie
Timeout
Parameter zum Festlegen einer Zeitüberschreitungsperiode (Sekunden). Wenn die Anforderung während dieses Zeitraums nicht abgeschlossen wird, gibt die API einen Fehler zurück.
Geben Sie die Nutzlast (Daten) direkt nach der Befehlsaufforderung ein. Alles, was Sie eingeben, einschließlich Zeilenumbrüche, ist Bestandteil der Nutzlast. Wenn Sie fertig sind, schließen Sie eine Leitungspause ("\n") und eine separate Zeile ab, die nur einen Zeitraum enthält, gefolgt von einer Leitungspause (".\n"). Jetzt wird der Befehl ausgeführt und die Daten werden an den Server gesendet.
Beispiele
Der Text der Nachricht ist JSON in beiden Beispielen. Je nach dem erwarteten Format des Diensts, der die Nachrichten empfängt, kann es sich um ein beliebiges Format handelt.
Beispiel 1: IoT-Gerätesteuerung mit HTTP Post
Dies ist eine Makrofunktion, die ein Licht ein aktiviert, das mit einer Farbfarbenbrücke 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); }
Dies können Sie an der Befehlszeile mithilfe der API tun:
xcommand HttpClient Put Header: "Content-Type: application/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state" {"on":true} .
Beispiel 2: Posten von Daten in ein Überwachungstool mithilfe von 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-Anforderungen finden Sie im Customization Guide . Wählen Sie die aktuelle Version.
Cisco-Support (TAC) unterstützt kein Debugging von Drittanbietercode, einschließlich Makros. Wenden Sie sich an die Cisco Collaboration Developer Community , wenn Sie Hilfe bei Makros und Drittanbietercode benötigen. Außerdem gibt es viele Entwickler- und Integratorressourcen auf dieser Site.