À l'aide de macros, vous pouvez envoyer des données vers un serveur HTTP(S) chaque fois que vous le souhaitez. Vous pouvez choisir les données à envoyer et les structurer comme vous le souhaitez. En procédant de cette façon, vous pouvez adapter les données à un service déjà établi.

Mesures de sécurité :

  • La fonction de requêtes client HTTP(S) est désactivée par défaut. Un administrateur système doit activer explicitement la fonctionnalité en définissant HttpClient > Mode à Activé (xConfiguration HttpClient Mode : Activé).

  • L'administrateur système peut empêcher l'utilisation de HTTP en définissant > httpclient AllowHTTP à faux(xConfiguration httpclient AllowHTTP:false).

  • L'administrateur système peut spécifier une liste des serveurs HTTP(S) auxquels le périphérique est autorisé à envoyer des données. (Reportezvous aux comandes xCommand httpclient allow).

  • Le nombre de demandes HTTP(S) simultanées est limité.

Les configurations dont il est question dans cet article, sont disponibles à la fois à partir de l'interface web du périphérique et de l'API. Les commandes sont disponibles dans l'API. Lire l'article paramètres avancés pour plus d'informations sur comment accéder à l'interface web et utiliser l'API.

Liste des serveurs HTTP(S) autorisés

L'administrateur système peut utiliser ces commandes pour configurer et gérer une liste des jusqu'à dix serveurs HTTP(S) autorisés (hôtes) :

  • xCommand HttpClient Allow Hostname Add Expression: : < expression régulière qui correspond au nom d'hôte ou à l'adresse IP du serveur HTTP(S) >

  • xCommand HttpClient Allow Hostname Clear

  • xCommand HttpClient Allow Hostname List

  • xCommand HttpClient Allow Hostname Remove Id : < id d'une entrée dans la liste >

Si la liste n'est pas vide, vous pouvez envoyer des demandes HTTP(S) uniquement aux serveurs de la liste. Si la liste est vide, vous pouvez envoyer les demandes à n'importe quel serveur HTTP(S).

Le contrôle par rapport à la liste des serveurs autorisés est effectué à la fois lors de l'utilisation d'un transfert de données non sécurisé (HTTP) et sécurisé (HTTPS).

HTTPS sans validation de certificat

Lors de l'envoi de demandes via HTTPS, le périphérique vérifie le certificat du serveur HTTPS par défaut. Si le certificat du serveur HTTPS n'est pas valide, un message d'erreur s'affiche. Le périphérique n'envoie pas de données pour ce serveur.

Nous vous recommandons d'utiliser HTTPS avec la validation de certificat. Si la validation de certificat n'est pas possible, l'administrateur système peut configurer HttpClient > AllowInsecureHTTPS à Activé (xConfiguration HttpClient AllowInsecureHTTPS : Avtivé). Cela permet l'utilisation de HTTPS sans validation du certificat du serveur.

Envoi de demandes HTTP(S)

Une fois que la fonction Demande du Client HTTP(S) est activée, vous pouvez utiliser les commandes suivantes pour envoyer les demandes vers un serveur HTTP(S) : La <méthode> est Post, Put, Patch, Getou 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>

Ajouter des champs d'en-tête est facultatif, mais vous pouvez ajouter jusqu'à 20 champs.

Le paramètre AllowInsecureHTTPS ne prend effet que si l'administrateur système a autorisé l'utilisation de HTTPS sans validation du certificat du serveur. Si c'est le cas, vous pouvez envoyer des données sur le serveur sans valider le certificat du serveur, si le paramètre est défini sur True. Si vous laissez le paramètre vide, ou le définissez à la valeur False, les données ne sont pas envoyées en cas d'échec de la validation de certificat.

Le paramètre ResposenSizeLimit est la taille maximale de la charge utile (octets) que le périphérique accepte comme réponse du serveur. Si la charge utile de réponse est supérieure à cette taille maximale, la commande renvoie une erreur d'état. Le message d'erreur indique que la taille maximale du fichier est dépassée. Toutefois, cela n'a aucun effet sur le côté serveur. le serveur a reçu et traité correctement la demande.

Utilisez le paramètre ResultBody pour décider comment formater le corps de la réponse HTTP à partir du serveur dans le résultat de la commande. Trois options sont disponibles :

  • Aucun : ne pas contenir le corps de la réponse HTTP dans le résultat de la commande.

  • Base64 : coder le corps en base64 avant de l'inclure dans le résultat.

  • Texte brut : ajoutez le corps dans le résultat en texte brut. Si la réponse contient des lettres non imprimables, la commande renvoie une erreur d'état avec un message indiquant que des données non imprimables ont été rencontrées.

Utilisez le paramètre Timeout pour définir un délai d'attente (en secondes). Si la demande ne se termine pas au cours de cette période, l'API renvoie une erreur.

Entrez directement la charge utile (les données) une fois que vous avez émis la commande. Tout ce que vous saisissez, y compris les sauts de ligne, fait partie de la charge utile. Lorsque vous avez terminé, terminez par un saut de ligne (“\n”) et une ligne distincte contenant seulement un point suivi par un saut de ligne (".\n"). Maintenant la commande est exécutée, et les données sont envoyées au serveur.

Exemples

Le corps du message est au format JSON dans ces deux exemples. Il pourrait s'agir de n'importe quel format, selon le format attendu par le service qui reçoit les messages.

Exemple 1 : Contrôle de périphérique IoT à l'aide de HTTP Post

Voici une fonction macro qui allume une lumière connectée à un pont philips Hue :

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

Vous pouvez faire la même chose sur la ligne de commande en utilisant l'API :

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

Exemple 2 : Envoi de données vers un outil de surveillance à l'aide de 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"}
.

Pour en savoir plus

Pour en savoir plus sur l'utilisation des demandes client HTTP, reportez-vous au guide de personnalisation. Choisissez la version la plus récente.

L'assistance technique de Cisco (TAC) ne prend en charge le débogage du code de fabricants tiers, y compris les macros. Veuillez vérifier la Communauté des développeurs de collaboration Cisco si vous avez besoin d'aide à propos des macros et du code de fabricants tiers. En outre, il existe beaucoup de ressources du développeur et de l'intégrateur sur ce site.