Dans une configuration de la surveillance API multi-étapes, les variables sont généralement utilisées pour stocker temporairement des valeurs extraites de vos réponses HTTP afin de les réutiliser ultérieurement. Cela vous permet de relier des étapes : chaque fois que vous voulez récupérer une information d'une réponse HTTP et utiliser cette information dans l'exécution de la prochaine requête HTTP, vous avez besoin d'une variable. Autrement dit : l'étape 1 reçoit une valeur de votre serveur et la stocke dans une variable. L'étape 2 prend alors la valeur que nous venons de stocker et l'utilise pour construire une nouvelle requête. Vous pouvez utiliser autant de variables que vous souhaitez et les utiliser en autant d'étapes que vous souhaitez.

Une deuxième raison d'utiliser des variables est de définir certaines valeurs une seule fois et de les réutiliser dans plusieurs étapes. Ces valeurs seront généralement rajoutées dans la section Variables prédéfinies : ces variables sont disponibles à n'importe quelle étape du scénario multi-étapes. Voir la section Variables prédéfinies pour plus d'informations.

Toutes les variables que vous définissez dans une étape sont évaluées dès que la requête HTTP a été exécutée et que la réponse a été traitée. À ce stade, si la variable existait déjà (soit par le biais d'une étape précédente, soit parce que vous l'avez prédéfinie), sa valeur sera mise à jour avec la nouvelle valeur. Sinon, une nouvelle variable est créée et ajoutée à la liste. Cette liste de variables et de valeurs correspondantes sera ensuite transmise à l'étape suivante.

Définir des variables

Si vous voulez utiliser des variables, vous devez nous indiquer quelle valeur nous devrions stocker dans ces variables. Comme pour la définition les assertions, les variables sont définies de la façon suivante :

Source property variable name
par exemple :
Response body as JSON access_token access_token
  • La source de la variable : ce champ définit l'attribut de la réponse HTTP que vous voulez extraire. Chaque option disponible est décrite dans cet article.
  • La propriété de la variable : certaines options de source (en particulier l'extraction de contenu et les options liées à l'en-tête) vous obligent à spécifier le contenu ou l'en-tête à vérifier. Ceci est expliqué plus en détail ici pour chaque type de source.
  • Le nom de la variable : c'est l'identifiant qui sera utilisé dans les étapes suivantes pour se référer à cette variable, en utilisant une notation spéciale.


Si un problème survient lors de l'évaluation d'une variable (par exemple, parce que vous essayez d'extraire une valeur qui n'est pas présente dans le contenu de la réponse), l'étape échouera et une erreur sera signalée.

Utiliser les variables dans d'autres étapes

Une fois qu'une variable a été évaluée avec succès, sa valeur peut être réutilisée dans la définition de la requête des étapes suivantes, et également à l'intérieur des assertions (vérification du contenu de la réponse). Il faut toujours faire référence à une variable en entourant son nom d'accolades doubles: {{variable-name}}.

  • Dans l'URL d'une étape : https://myapi.customer.com/ProductInfo/{{ProductId}}
  • Dans un en-tête de requête : Authorization: Bearer {{access_token}}
  • Dans le contenu du corps de la requête :

    { "ProductId": "{{ProductId}}", "Code": "P123456" }
  • Dans la valeur cible d'une assertion. Par exemple, si vous avez une variable {{ProductId}} (évaluée dans une étape précédente ou en tant que variable prédéfinie), vous pouvez l'utiliser pour vérifier qu'une réponse contient la valeur réelle contenue dans cette variable :

    Response body as JSON Products[0].Id Equals {{ProductId}}
  • Dans la valeur de propriété d'une assertion. Si vous avez une {{ProductId}}, vous pouvez vous référer à cette variable dans une expression JSON ou requête XPath pour sélectionner le contenu que vous cherchez à vérifier :

    Response body as XML //Product[@Id="{{ProductId}}"]/Name/text() Equals Chocolate chip cookie

Variables prédéfinies

En dessous de l'éditeur d'étape, vous trouverez une section supplémentaire où vous pouvez spécifier davantage de variables. Ces variables sont disponibles dès le début du scénario. Si vous avez besoin d'une valeur particulière plusieurs fois de suite, vous pouvez définir cette valeur à l'avance ici et l'utiliser dans les différentes étapes. Il peut s'agir d'un identifiant de produit que vous souhaitez utiliser tout au long de votre scénario, d'une clé d'API ou d'autres valeurs spéciales dont votre API a besoin.

Un cas particulier consiste à utiliser une variable qui contient le nom de domaine pour chaque API. En utilisant cette variable dans chaque URL, vous n'avez pas besoin de répéter le nom de domaine à chaque étape, ce qui vous permet de la modifier très facilement pour l'ensemble du scénario.

Pour ce faire, créez une variable nommée BaseUrl avec valeur https://test.yourapi.com. En utilisant une référence à cette variable, l'URL de chaque étape de l'API pourrait alors prendre la forme {{BaseURL}}/UserService/GetUserInfo. Cette approche vous permet de modifier votre scénario multi-étapes pour qu'il pointe vers un environnement différent (par exemple, environnement de test ou environnement de production) sans avoir à modifier chaque étape.

Il est important d'utiliser le nom BaseUrl, car il va être traité un peu différemment des autres variables, comme expliqué ci-dessous.

Encodage des valeurs des variables

En fonction de l'endroit où vous utilisez vos variables, nous devons appliquer des règles d'encodage sur les valeurs correspondantes. Cet encodage consiste à convertir les caractères spéciaux dans un format qui convient à une requête HTTP. Par exemple, si vous avez une variable appelée CompanyName avec une valeur Ben & Jerry's, nous le convertirons automatiquement en Ben+%26+Jerry's si besoin.

Nous suivrons ces règles :

  • Seront encodés les valeurs de variables qui apparaissent dans le champ URL de l'étape
  • Seront encodés les valeurs de variables qui apparaissent dans le corps de requête de l'étape, seulement si un en-tête Content-Type a été spécifié avec la valeur application/x-www-forme-urlencoded..
  • Ne sera PAS encodé la valeur de la variable appelée BaseUrl, car la partie du nom de domaine d'une URL ne doit pas être encodée.

Cette dernière règle explique pourquoi l'exemple du BaseUrl est spécial : les caractères ‘deux points’ et ‘barre oblique’ d'une valeur https://test.yourapi.com/Products ne doivent jamais être encodés.

Variables automatiques

En plus des variables que vous définissez dans la configuration de votre moniteur, vous avez également accès à un certain nombre de variables automatiques que nous créons pour vous. La plupart d'entre elles sont en fait des fonctions qui génèrent une valeur que vous pouvez utiliser dans vos requêtes HTTP, et lors de l'évaluation de vos réponses HTTP en utilisant des assertions.

Les variables automatiques suivantes sont disponibles :

  • @DateTime(format, offset) : La variable @DateTime génère des valeurs de date et d'heure dynamiques, en fonction du format que vous spécifiez. La date/heure est toujours l'heure actuelle dans le fuseau horaire UTC. Il est possible de générer des dates, heures et fuseaux horaires grâce à un paramètre optionnel de décalage qui ajoute ou soustrait le nombre de secondes spécifié. Par exemple, pour convertir l'heure UTC actuelle en heure normale EST (UTC-5), spécifiez -18000 (-5 * 60 * 60) comme décalage. De même, pour calculer "cette heure demain" en UTC, précisez 86400 (24 * 60 * 60). Si vous omettez la valeur de décalage, aucun décalage n'est appliqué. Par exemple, si nous sommes le 24 février 2018, 22 h 30 UTC, les expressions dans le tableau à gauche donneraient les résultats montrés à droite :
    {{@DateTime(dd-MM-yyyy HH:mm)}} 24-02-2018 22:30
    Maintenant
    {{@DateTime(ISO)}} 2018-02-24T22:30:00.0000000Z
    ISO 8601 format
    {{@DateTime(UNIX)}} 1519511400
    L'heure UNIX (ou POSIX)
    {{@DateTime(MM/dd/yyyy,-86400)}} 02/23/2018
    Hier
    {{@DateTime(MM/dd/yyyy,86400)}} 02/25/2018
    Demain
  • @RandomGuid : Cette variable génère une valeur aléatoire sous la forme AB0AD14D-9611-41A8-9C25-7D94B895CFF1. Vous pouvez utiliser cette variable si vous devez inclure une valeur aléatoire dans votre URL, vos données POST ou votre en-tête HTTP.
    Si vous utilisez la variable @RandomGuid dans plusieurs étapes, chaque étape aura une valeur aléatoire différente. À chaque exécution du moniteur, vous obtiendrez de nouvelles valeurs aléatoires.
  • @RandomInt(min,max): Cette variable produit un nombre entier aléatoire entre les valeurs minimum et maximum que vous spécifiez (min et max inclus). Par exemple, si vous spécifiez {{@RandomInt(0,100}}, cette variable produit un nombre dans la plage 0..100.
  • @ServerId: Lors de l'exécution d'un moniteur d'API multi-étapes, cette variable génère une valeur numérique identifiant l'emplacement du point de contrôle Uptrends qui exécute cette vérification.
    Par exemple, si la vérification est en cours d'exécution sur notre point de contrôle à Sydney, en Australie, la variable affichera la valeur 30. La liste des serveurs de points de contrôle et leurs Server IDs (Identifiants du serveur) correspondants est disponible via l'API Uptrends ici Checkpointservers.
  • @RedirectUrl: Dans le cas où l'une des étapes de votre moniteur renvoyait un code de redirection et que vous souhaitez capturer et tester cette réponse de redirection plutôt que de la suivre automatiquement, cette variable automatique contiendra l'URL à laquelle la redirection fait référence. Ceci ne se produira que si vous choisissez de ne pas suivre automatiquement les redirections, et que vous configurez une assertion qui vérifie le code de redirection approprié. Cette procédure est expliquée plus en détail ici : Comment gérer les redirections dans le Monitoring multi-étapes.

Comment utiliser plusieurs fois de suite une valeur générée automatiquement

Certaines de ces fonctions variables (en particulier celles produisant des valeurs aléatoires ou des valeurs date/heure) sont réévaluées chaque fois que vous les utilisez, et généreront donc une nouvelle valeur à chaque fois. Si vous voulez générer une valeur particulière et l'utiliser plusieurs fois dans votre scénario multi-étapes, vous pouvez définir une variable prédéfinie (comme indiqué dans l'une des sections précédentes) avec comme valeur celle d'une variable automatique.

Exemples de variables prédéfinies utilisant des variables automatiques

Nom Valeur Utilisation
SearchDate {{@DateTime(dd-MM-yyyy)}} Une valeur de date à utiliser comme entrée pour une requête de recherche.
UniqueEmail {{@RandomGuid}}@mycompany.com Une valeur aléatoire guid combinée avec un texte fixe pour générer une adresse e-mail différente à chaque fois.
OrderAmount {{@RandomInt(1, 10)}} Un nombre aléatoire compris entre 1 et 10 à utiliser comme nombre de produits à commander. Lors d'un appel ultérieur, vous pouvez réutiliser cette variable pour vérifier le contenu d'un panier et voir s'il contient effectivement ce nombre d'articles.