Met macro's kunt u wanneer u dat nodig hebt gegevens naar een HTTPs-server verzenden. U hebt zelf controle over welke gegevens worden verzonden en hoe deze worden ingedeeld. Het is eenvoudig om de gegevens aan te passen voor gebruik met bestaande services.

Beveiligingsmaatregelen:

  • De HTTP(S)-clientverzoekfunctie is standaard uitgeschakeld. Een systeembeheerder moet de functie expliciet inschakelen door HttpClient>Mode in te stellen op Aan ( xConfiguratiemodus HttpClient: Aan ).

  • De systeembeheerder kan het gebruik van HTTP voorkomen door HttpClient > AllowHTTP in te stellen op False ( xConfiguratie HttpClient AllowHTTP: Onwaar ).

  • De systeembeheerder kan een lijst met HTTP(S)-servers opgeven waarnaar het apparaat gegevens mag sturen. (zie de commando's xCommand HttpClient Allow Hostname.)

  • Het aantal gelijktijdige HTTP(S)-verzoeken is beperkt.

De configuraties waarnaar in dit artikel wordt verwezen, zijn zowel via de webinterface van het apparaat als in de API beschikbaar. Opdrachten zijn beschikbaar via de API. Lees het artikel met betrekking tot de geavanceerde instellingen voor meer informatie over de toegang tot de webinterface en het gebruik van de API.

Lijst met toegestane HTTP(S)-servers

De systeembeheer kan deze commando's gebruiken om een lijst met maximum tien toegestane HTTP(S)-servers (hosts) op te stellen en bij te houden:

  • xCommand HttpClient Allow Hostname Add Expression: <Gewone uitdrukking die overeenstemt met de hostnaam of het IP-adres van de HTTP(S)-server>

  • xCommand HttpClient Allow Hostname Clear

  • xCommand HttpClient Allow Hostname List

  • xCommand HttpClient Allow Hostname Remove Id: <id van een item in de lijst>

Als de lijst serververmeldingen bevat, kunt u alleen HTTP-verzoeken naar deze servers sturen. Als de lijst echter leeg is, kunt u verzoeken naar elke HTTPs-server sturen.

De controle van de lijst met toegestane servers wordt uitgevoerd bij zowel een onbeveiligde (HTTP) als een beveiligde (HTTPS) gegevensoverdracht.

HTTPS zonder certificaatvalidatie

Als u verzoeken via HTTPS verzendt, controleert het apparaat standaard het certificaat van de HTTPS-server. Als het HTTPS-certificaat niet geldig wordt bevonden, krijgt u een foutmelding. Het apparaat stuurt geen gegevens naar die server.

Wij raden aan om HTTPS met validering van het certificaat te gebruiken. Als een certificaatvalidatie niet mogelijk is, kan de systeembeheerder HttpClient >AllowInsecureHTTPS instellen op On ( xConfiguration HttpClient AllowInsecureHTTPS: On ). Dit maakt het gebruik van HTTPS zonder validering van het certificaat van de server mogelijk.

HTTPs-verzoeken verzenden

Van zodra de HTTP(S)-clientverzoekfunctie is ingeschakeld, kunt u de volgende commando's gebruiken om verzoeken naar een HTTP(S)-server te sturen. <method> is Post, Put, Patch, Get of Delete.

  • xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <Header text>] [ResponseSizeLimit: <Maximum response size>] [ResultBody: <None/PlainText/Base64>] [Time-out: <Tijdperiode>] Url: <URL om het verzoek te verzenden naar>

Het toevoegen van koptekstvelden is optioneel en u kunt maximaal 20 velden toevoegen.

De parameter AllowInsecureHTTPS heeft alleen invloed als de systeembeheerder het gebruik van HTTPS zonder validering van het certificaat van de server heeft toegestaan. Als dit het geval is, kunt u de gegevens zonder validering van het servercertificaat verzenden als de parameter is ingesteld op True. Als u de parameter weglaat of als hij is ingesteld op False, worden de gegevens niet verzonden als de validering van het certificaat ontbreekt.

De parameter ResposenSizeLimit is de maximale grootte (bytes) die het apparaat als antwoord van de server aanvaardt. Als het antwoord groter is dan deze maximale grootte, stuurt het commando een statusfout terug. De foutmelding geeft aan dat de maximale bestandsgrootte is overschreden. Dit heeft echter geen invloed aan de kant van de server; de server heeft het verzoek correct ontvangen en verwerkt.

Gebruik de parameter ResultBody om te bepalen hoe de hoofdtekst van het HTTP-antwoord van de server in het commandoresultaat moet worden opgemaakt. U hebt drie opties:

  • None: de hoofdtekst van het HTTP-antwoord wordt niet in het commandoresultaat opgenomen.

  • Base64: Base64 codeert de hoofdtekst alvorens die in het resultaat op te nemen.

  • PlainText: de hoofdtekst wordt als gewone tekst in het resultaat opgenomen. Als het antwoord niet-afdrukbare letters bevat, geeft het commando een statusfout met een melding dat er niet-afdrukbare gegevens werden gevonden.

Gebruik de parameter Timeout om een time-outperiode (seconden) in te stellen. Als het verzoek niet tijdens deze periode wordt voltooid, geeft de API een fout.

Voer de lading (gegevens) in nadat u het commando hebt gegeven. Alles wat u invoert, inclusief regeleindes, maakt deelt uit van de lading. Als u klaar bent, eindig dan met een regeleinde (“\n”) en een afzonderlijke regel met alleen een punt gevolgd door een regeleinde (“.\n”). Nu wordt het commando uitgevoerd en worden de gegevens naar de server gestuurd.

Voorbeelden

De hoofdtekst van het bericht is in beide voorbeelden JSON. De hoofdtekst kan in eender welke indeling staan, afhankelijk van de verwachte indeling van de service die de berichten ontvangt.

Voorbeeld 1: IoT-apparaatbesturing met HTTP Post

Hier volgt een macrofunctie die een lamp inschakelt die met een Philips Hue Bridge is verbonden:

 functie 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); }

U kunt op de commandoregel hetzelfde doen aan de hand van de API:

 xcommand HttpClient Put Header: "Inhoudstype: toepassing/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state" {"on":true} .

Voorbeeld 2: gegevens naar een controlehulpprogramma sturen met HTTP Post 

 xcommand HttpClient Post Header: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"A user heeft een probleem gemeld met dit systeem","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} .

Meer informatie

Meer informatie over het gebruik van de HTTP-verzoeken vindt u in de Customization guide. Kies de meest recente versie.

De support van Cisco (TAC) biedt geen ondersteuning voor de debugging van code van een derde partij, inclusief macro's. Schakel# https://roomos.cisco.com in als u hulp nodig hebt met macro's en code van derden.