Met macro's kunt u gegevens op elk gewenst moment naar een HTTP(S)-server sturen. U kunt kiezen welke gegevens er moeten worden verzonden en ze naar wens structureren. Als u op deze manier te werk gaat, kunt u de gegevens aan een reeds bestaande service aanpassen.

Beveiligingsmaatregelen:

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

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

  • 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 beschikbaar vanaf de webinterface van het apparaat als in de API. Commando's zijn beschikbaar in 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 niet leeg is, kunt u alleen HTTP(S)-verzoeken naar de servers in de lijst sturen. Als de lijst leeg is, kunt u de verzoeken naar alles HTTP(S)-servers sturen.

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

HTTPS zonder validering van het certificaat

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 de validering van het certificaat 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.

HTTP(S)-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>] [Timeout: <Timeout period>] Url: <URL to send the request to>

De toevoeging van koptekstvelden is optioneel. U kunt maximum 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:

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

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

xcommand HttpClient Put Header: "Content-Type: application/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 reported an issue with this system","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. Raadpleeg de Cisco Collaboration-ontwikkelaarsgemeenschap als u hulp nodig hebt met macro's en code van een derde partij. U vindt op deze site ook veel ontwikkelaars- en integratorbronnen.