Avec les macros, vous pouvez envoyer des données à un serveur HTTP chaque fois que vous en avez besoin. Vous avez le contrôle sur les données envoyées et leur organisation, ce qui simplifie l'adaptation des données pour une utilisation avec les services existants.

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 Mode> HttpClient sur Activé ( xConfiguration Mode HttpClient : Activé ).

  • Pour empêcher l'utilisation de HTTP, l'administrateur système peut empêcher l'utilisation de HTTP en attribuant la valeur >False ( 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 mentionnées dans cet article sont disponibles à la fois à partir de l'interface Web de l'appareil et dans le API. Les commandes sont disponibles via le 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 contient des entrées de serveur, vous ne pouvez envoyer des requêtes HTTP qu'à ces serveurs. Cependant, si la liste est vide, vous pouvez envoyer des demandes à n'importe quel serveur HTTPs.

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 définir HttpClient>AllowInsecureHTTPS sur On ( xConfiguration HttpClient AllowInsecureHTTPS : On ). Cela permet l'utilisation de HTTPS sans validation du certificat du serveur.

Envoi de requêtes HTTP

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 <Méthode> [AllowInsecureHTTPS : <True/False>] [En-tête : <Texte d'en-tête>] [ResponseSizeLimit : <Taille maximale de la réponse>] [ResultBody : <None/PlainText/Base64>] [Timeout : <Timeout period>] URL : <URL à laquelle envoyer la demande>

L'ajout de champs d'en-tête est facultatif, vous pouvez en ajouter jusqu'à 20.

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" :"Un utilisateur a signalé un problème avec ce système","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 https://roomos.cisco.com si vous avez besoin d'aide avec les macros et le code tiers.