Utilisation de variables dans les moniteurs d’API multi-étapes

Pour vous familiariser avec les variables, nous vous recommandons de lire notre article Gestion des réponses d’API dans les moniteurs multi-étapes où vous trouverez une vue d’ensemble des principales fonctionnalités du moniteur en lien avec les réponses.

Cet article présente les différents types de variables que vous pouvez utiliser pour extraire et stocker les valeurs de la réponse d’API.

Variables

Dans un moniteur d’API multi-étapes, les variables sont utilisées pour extraire des valeurs des réponses HTTP et les stocker temporairement en vue de leur réutilisation.

Imaginez que vous deviez utiliser un ID de produit ou une clé d’API tout au long d’un scénario d’API. Il est aussi possible que vous souhaitiez définir une seule fois d’autres valeurs pour ensuite les réutiliser dans plusieurs étapes, par exemple un domaine pour chaque API. Dans ce cas, vous pouvez créer une variable appelée BaseUrl avec la valeur https://test.yourapi.com. Vous pourrez ensuite faire référence à cette variable dans vos URL d’API, par exemple {{BaseUrl}}/UserService/GetUserInfo ou {{BaseUrl}}/UserService/GetProductInfo. En définissant cette variable, vous pouvez facilement basculer entre les environnements (par exemple, simulation et production) en mettant simplement à jour la variable, sans devoir modifier chaque étape individuellement.

Dans ce type de scénario, les variables permettent :

• d’extraire une information d’une réponse HTTP et d’utiliser cette valeur spécifique pour construire la requête HTTP suivante ;
• de définir une valeur une seule fois et de la réutiliser dans plusieurs étapes tout au long d’un scénario d’API ;
• d’actualiser la valeur d’une variable à un seul endroit et de propager automatiquement cette modification dans les étapes suivantes.

Toutes les variables définies dans une étape sont évaluées après l’exécution de la requête HTTP et le traitement de la réponse. À ce moment-là, si une variable existait déjà dans une étape précédente ou en tant que variable prédéfinie, sa valeur existante est remplacée.

Autrement, une nouvelle variable est créée et ajoutée à la liste des variables. Cette liste de variables et leurs valeurs correspondantes seront ensuite transmises à l’étape suivante. Les variables peuvent être créées et réutilisées aussi souvent que nécessaire.

Définition des variables

Dans l’exemple ci-dessous, deux variables sont définies afin de stocker le prix du produit et l’ID du produit tirés de la réponse. Selon un motif similaire à celui utilisé pour définir les assertions, les variables s’articulent autour de trois champs : source propriété nom de la variable. Chaque champ correspond à une valeur spécifique, qui montre comment les valeurs d’API sont stockées et comment la variable est créée.

Voici ci-dessous les champs de variable que vous pouvez définir selon vos besoins de surveillance.

Source de la variable

Ce champ définit l’origine ou la source des données à vérifier. Les données peuvent provenir d’un corps de réponse en tant que JSON, d’un corps de réponse en tant que texte ou d’un attribut d’une réponse HTTP, comme un code de statut, ainsi que d’autres nombreux attributs. Pour en savoir plus, vous pouvez lire notre article sur les sources.

Propriété de la variable

Certaines sources, telles que Corps de réponse en tant que JSON et En-tête de réponse, nécessitent d’effectuer une vérification de contenu pour valider la réponse. Pour vérifier des données spécifiques dans la réponse, vous devez fournir la valeur de propriété appropriée pour le type de source. Dans l’exemple ci-dessus, [0].ProductId est la valeur de la propriété.

Pour en savoir plus, vous pouvez lire la section sur la propriété.

Nom de la variable

Ce champ est l’identifiant utilisé pour faire référence à la variable à chaque étape. Pour employer des variables, utilisez la syntaxe : {{VariableName}}.

Si un problème survient lors de l’évaluation d’une variable, par exemple, si vous essayez d’extraire une valeur qui n’est pas présente dans le contenu de la réponse, l’étape échoue et une erreur est signalée.

Types de variables

Selon votre besoin, vous pouvez créer différents types de variables.

Variables prédéfinies

Sous l' éditeur d’étapes, vous trouverez une section où vous pouvez spécifier les variables prédéfinies. Ces variables sont disponibles dès le début du scénario d’API. Si vous devez utiliser une valeur particulière à plusieurs reprises, vous pouvez définir cette valeur à l’avance et l’utiliser à différentes étapes.

Comme indiqué dans l’image, vous pouvez utiliser la variable {{BaseUrl}} pour cibler différents endpoints à chaque étape, comme {{BaseUrl}}/Products et {{BaseUrl}}/Status. Pour en savoir plus, vous pouvez lire l’article sur l’utilisation des variables prédéfinies dans les moniteurs d’API multi-étapes.

Variables de métriques personnalisées

Lorsque votre moniteur d’API multi-étapes récupère des données auprès de vos API, il est possible que vous ayez besoin de surveiller des données numériques qui ne font pas partie des métriques standard. Par exemple, vous pouvez vouloir utiliser des valeurs personnalisées autres que le code de statut, la durée de réponse, etc. afin d’évaluer le comportement de votre API.

Les variables de métriques personnalisées vous permettent de créer une variable définie par l’utilisateur pour stocker des données numériques extraites de la réponse d’API. Cette fonctionnalité vous est utile si vous voulez suivre vos stocks de produit, vos ventes et d’autres indicateurs.

Pour en savoir plus, vous pouvez lire notre article sur les métriques personnalisées.

Variables automatiques

En plus des variables que vous définissez dans votre moniteur, vous pouvez aussi utiliser plusieurs variables automatiques que nous avons créées pour vous. Ces variables sont déjà configurées de façon à générer des valeurs que vous pouvez utiliser dans vos requêtes HTTP et pendant l’évaluation de vos réponses HTTP, au moyen des assertions. Voici certains exemples de variables automatiques : {{@DateTime(format,offset)}} et {{@RedirectUrl}}.

Pour en savoir plus, vous pouvez lire notre article sur les variables automatiques.

Fonctions définies par l’utilisateur

Dans certaines situations, les valeurs extraites de la réponse d’API doivent être converties dans un format particulier avant de pouvoir être utilisées. Cette fonction est notamment utile pour extraire des valeurs d’un tableau de chaînes de caractères ou utiliser une expression régulière pour obtenir le nom de fichier à partir d’un chemin complet. Uptrends vous permet de définir des fonctions personnalisées, qui peuvent convertir en une nouvelle valeur les valeurs de variables issues d’une étape précédente ou d’une variable système.

Pour en savoir plus, vous pouvez lire notre article sur les fonctions définies par l’utilisateur.

Utilisation des variables dans d’autres étapes

Une fois qu’une variable a été récupérée et évaluée correctement, sa valeur peut être réutilisée dans la définition de la requête des étapes suivantes, ainsi qu’à l’intérieur des assertions. Vous pouvez faire référence à une variable en plaçant le nom de la variable entre des accolades doubles : {{Nom de la variable}}.

Les exemples suivants vous montrent comment faire référence à une variable dans différents cas d’usage :

• 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 d’un corps de requête : { "ProductId": "{{ProductId}}", "Code": "P123456" }

• Dans la valeur cible d’une assertion. Si vous avez une variable {{ProductId}} issue d’une étape précédente ou existant en tant que variable prédéfinie, vous pouvez l’utiliser pour comparer la réponse et la valeur de la variable :

  Corps de réponse en tant que JSON Products[0].Id"/Name/text() Est égal à {{ProductId}}

• Dans la valeur propriété d’une assertion. Si vous avez une variable {{ProductId}}, vous pouvez faire référence à cette variable dans une expression JSON ou une requête XPath pour sélectionner le contenu que vous souhaitez vérifier :

  Corps de réponse en tant que XML //Product[@Id="{{ProductId}}"]/Name/text() Est égal à Chocolate chip cookie

Encodage des valeurs des variables

En fonction de l’endroit où vous utilisez vos variables, il est parfois nécessaire d’encoder leurs valeurs. L’encodage consiste à convertir les caractères spéciaux dans un format qui convient à des requêtes HTTP. Généralement, les variables utilisées dans une URL doivent être encodées.

Imaginons que vous vouliez construire une URL contenant un paramètre de nom, et que vous souhaitiez utiliser une variable appelée CompanyName pour spécifier une valeur pour ce paramètre. Sans encodage, le résultat serait le suivant :

https://my.api.com/GetCompanyInfo?name={{CompanyName}}

Supposons que la variable CompanyName contienne la valeur Ben & Jerry's. Cette valeur contient des espaces et un caractère “&”, qui ont une signification particulière dans une URL. Sans encodage, la valeur reçue sur le serveur serait incorrecte.

En appliquant d’abord l’encodage, la valeur sera convertie en Ben\+%26\+Jerry's, que le serveur interprétera comme la valeur d’origine. Pour encoder une variable, utilisez la fonction {{@UrlEncode(...)}} et incluez le nom complet de la variable entre les parenthèses.

Dans notre cas, la variable ressemblera à ceci :

https://my.api.com/GetCompanyInfo?name={{@UrlEncode({{CompanyName}})}}

Si une variable contient uniquement des valeurs numériques et aucun caractère spécial, il n’est pas nécessaire d’utiliser la fonction @UrlEncode. Nous encodons automatiquement les valeurs de variables qui apparaissent dans le corps de requête de l’étape si un en-tête Content-Type a été spécifié avec la valeur application/x-www-forme-urlencoded. Les autres types de contenu ne nécessitent généralement pas d’encodage d’URL.