Débuter avec les tests API

Docs > Getting Started > Débuter avec la surveillance Synthetic > Débuter avec les tests API

Présentation

Les tests API vérifient de façon proactive que vos services essentiels sont disponibles en tout temps et tout lieu. Il existe huit sous-types de tests API uniques. Ces tests vous permettent de lancer des requêtes sur différentes couches réseau de vos systèmes (HTTP, SSL, DNS, WebSocket, TCP, UDP, ICMP et gRPC). Avec les tests API à plusieurs étapes, vous pouvez exécuter une série de tests API afin de surveiller la disponibilité de parcours clés au niveau de l’API.

Créer un test API unique

Les tests HTTP surveillent les endpoints de votre API. Ils génèrent des alertes lorsque la latence des réponses est élevée ou si l’une des conditions que vous avez définies n’est pas respectée, par exemple un code de statut attendu, des en-têtes de réponse ou le contenu d’un corps de réponse.

L’exemple ci-dessous décrit la marche à suivre pour créer un test HTTP, à savoir un sous-type des tests API uniques.

Définir la requête

Sur le site Datadog, survolez Digital Experience et sélectionnez Tests (sous Synthetic Monitoring & Testing).
Cliquez sur New Test > New API test.
Sélectionnez le type de requête HTTP.
Définissez votre requête :
- Ajoutez l’URL de l’endpoint à surveiller. Si vous n’avez pas d’endpoint, vous pouvez utiliser https://www.shopist.io/. Il s’agit d’une application Web d’e-commerce utilisable pour des tests. Lorsque vous définissez l’endpoint pour un test, le nom de votre test est automatiquement rempli : ici, Test on www.shopist.io.
- Vous pouvez sélectionner Advanced Options pour définir des options de requête personnalisées, des certificats, des identifiants d’authentification, etc.
  Remarque : vous pouvez créer des variables globales sécurisées pour stocker des identifiants et créer des variables locales pour générer des timestamps dynamiques afin de les utiliser dans la charge utile de votre requête. Une fois ces variables créées, saisissez {{ dans un champ pertinent, puis sélectionnez la variable pour injecter sa valeur dans les options de vos tests.
  Pour cet exemple, aucune option avancée n’est requise.
- Vous pouvez ajouter des tags, comme env:prod et app:shopist, à votre test. Les tags vous permettent d’organiser votre collection de tests et d’accéder rapidement à ceux qui vous intéressent sur la page d’accueil.
Cliquez sur Test URL pour lancer l’exécution de l’exemple de test.

Définir des assertions

Lorsque vous cliquez sur Test URL, des assertions de base sont automatiquement ajoutées à la réponse de votre endpoint. Les assertions définissent les critères de réussite d’un test.

Ici, trois assertions par défaut sont ajoutées après l’exécution de l’exemple de test :

Les assertions sont entièrement personnalisables. Pour ajouter une assertion personnalisée, cliquez sur des éléments de l’aperçu de réponse, comme les en-têtes, ou cliquez sur New Assertion pour définir une nouvelle assertion de toute pièce.

Sélectionner des emplacements

Sélectionnez un ou plusieurs emplacements gérés ou emplacements privés à partir desquels vous souhaitez exécuter votre test. Datadog’s out-of-the-box managed locations allow you to test public-facing websites and endpoints from regions where your customers are located.

Americas	APAC	EMEA
Canada Central (AWS)	Hong Kong (AWS)	Cape Town (AWS)
Northern California (AWS)	Mumbai (AWS)	Frankfurt (AWS)
Northern Virginia (AWS)	Seoul (AWS)	Ireland (AWS)
Ohio (AWS)	Singapore (AWS)	London (AWS)
Oregon (AWS)	Sydney (AWS)	Paris (AWS)
São Paulo (AWS)	Tokyo (AWS)	Stockholm (AWS)
Virginia (Azure)	Osaka (AWS)	Milan (AWS)
	Jakarta (AWS)	Bahrain (AWS)

The Datadog for Government site (US1-FED) uses the following managed location:

Americas
US-West

L’application Shopist est accessible au public à l’adresse https://www.shopist.io/, vous pouvez donc choisir n’importe quel emplacement géré pour exécuter votre test. Pour tester des applications internes ou simuler le comportement d’utilisateurs dans des régions géographiques distinctes, utilisez plutôt les emplacements privés.

Indiquer la fréquence du test

Sélectionnez la fréquence à laquelle vous souhaitez exécuter votre test. Vous pouvez conserver la fréquence par défaut d’une minute.

Vous pouvez non seulement planifier l’exécution de votre test Synthetic, mais également le déclencher manuellement, ou directement depuis vos pipelines CI/CD.

Définir des conditions d’alerte

Vous pouvez définir des conditions d’alerte afin de veiller à ce que votre test n’échoue pas en cas d’erreur réseau isolée. Ainsi, vous recevez uniquement des alertes lorsque votre endpoint rencontre un réel problème.

Vous pouvez spécifier le nombre d’échecs consécutifs avant qu’un emplacement ne soit considéré comme défaillant :

Retry test 2 times after 300 ms in case of failure

Vous pouvez également configurer votre test de façon à ce qu’il envoie uniquement une notification lorsque l’endpoint n’est plus disponible pendant une certaine durée, et pour un certain nombre d’emplacements. La règle d’alerte ci-dessous stipule qu’une notification est envoyée lorsque le test échoue pendant trois minutes, sur deux emplacements différents :

An alert is triggered if your test fails for 3 minutes from any 2 of 13 locations

Configurer le monitor de test

Indiquez un message dans votre alerte et ajoutez les adresses e-mail auxquelles vous souhaitez envoyer des alertes. Vous pouvez également utiliser des intégrations de notification, comme Slack, PagerDuty, Microsoft Teams ou encore des webhooks. Pour déclencher une alerte Synthetic avec ces outils, vous devez auparavant configurer l’intégration correspondante.

Lorsque vous êtes prêt à enregistrer votre configuration de test et votre monitor, cliquez sur Create.

Créer un test API à plusieurs étapes

Les tests API à plusieurs étapes vous permettent de surveiller des transactions commerciales essentielles au niveau de l’API.

Présentation d'un test API à plusieurs étapes Synthetic

Tout comme les tests API, les tests API à plusieurs étapes vous envoient des alertes lorsque vos endpoints sont trop lents ou lorsqu’ils ne répondent pas aux conditions que vous avez définies. Vous pouvez créer des variables à partir des réponses d’une étape, puis réinjecter leurs valeurs dans les étapes ultérieures. Ainsi, les étapes s’enchaînent et reproduisent le comportement de votre application ou service.

L’exemple ci-dessous vous explique comment créer un test API à plusieurs étapes afin de surveiller l’ajout d’un article à un panier. Il inclut trois étapes :

Création d’un panier
Récupération d’un produit
Ajout du produit au panier

Si vous ne savez pas quels endpoints d’API utiliser pour créer votre test API à plusieurs étapes, utilisez les exemples d’endpoint ci-dessous :

Pour créer un test API à plusieurs étapes, cliquez sur New Test > Multistep API test. Attribuez un nom à votre test, par exemple Ajout de produit au panier, ajoutez des tags et sélectionnez des emplacements.

Création d’un panier

Dans Define steps, cliquez sur Create Your First Step.
Attribuez un nom à votre étape, par exemple Création d'un panier.
Indiquez la méthode HTTP et l’URL à interroger. Saisissez par exemple POST et https://api.shopist.io/carts.
Cliquez sur Test URL. Cela crée un panier dans le backend de l’application Shopist.
Conservez les assertions par défaut ou modifiez-les.
Vous avez également la possibilité de définir des paramètres d’exécution.
Pour vous assurer que le test s’applique à l’ensemble de la collecte de données de l’endpoint ou pour vérifier que la dernière étape de nettoyage est bien exécutée, peu importe le résultat des étapes précédentes, cochez la case Continue with test if this step fails. La fonctionnalité Retry peut s’avérer utile si l’endpoint de votre API n’est pas toujours très réactif.
Pour cet exemple, aucun paramètre d’exécution n’est requis.
Pour créer une variable à partir de la valeur de l’ID du panier situé à la fin de l’en-tête location :
- Cliquez sur Extract a variable from response content.
- Définissez le nom de votre variable sur CART_ID.
- Pour Response Header, sélectionnez location.
- Ajoutez une expression régulière, par exemple (?:[^\\/](?!(\\|/)))+$ dans le champ Parsing Regex.
Cliquez sur Save Variable.
Une fois votre étape terminée, cliquez sur Save Step.

Récupération d’un produit

Sous Define another step, cliquez sur Add Another Step. Par défaut, vous pouvez créer jusqu’à 10 étapes.
Attribuez un nom à votre étape, par exemple Récupération d'un produit.
Indiquez la méthode HTTP et l’URL à interroger. Saisissez par exemple GET et https://api.shopist.io/products.json.
Cliquez sur Test URL. La liste des produits disponibles dans l’application Shopist est alors récupérée.
Conservez les assertions par défaut ou modifiez-les.
Vous avez la possibilité de définir des paramètres d’exécution. Pour cet exemple, aucun paramètre d’exécution spécifique n’est requis.
Pour créer une variable à partir de l’ID de produit situé dans le corps de la réponse :
- Cliquez sur Extract a variable from response content.
- Définissez le nom de votre variable sur PRODUCT_ID.
- Cliquez sur l’onglet Response Body.
- Cliquez sur la clé $oid de l’un des produits pour générer un chemin JSON. Exemple : $[0].id['$oid'].
Cliquez sur Save Variable.
Une fois votre étape terminée, cliquez sur Save Step.

Ajout du produit au panier

Cliquez sur Add Another Step pour ajouter la dernière étape, à savoir l’ajout du produit au panier.
Attribuez un nom à votre étape, par exemple Ajout du produit au panier.
Indiquez la méthode HTTP et l’URL à interroger. Saisissez par exemple POST et https://api.shopist.io/add_item.json.

Dans l’onglet Request Body, choisissez le type de corps application/json et ajoutez ce qui suit :

    {
      "cart_item": {
        "product_id": "{{ PRODUCT_ID }}",
        "amount_paid": 500,
        "quantity": 1
      },
      "cart_id": "{{ CART_ID }}"
    }
    

Cliquez sur Test URL. Cela ajoute le produit extrait lors de l’étape 2 au panier créé lors de l’étape 1 et renvoie une URL de paiement.
Sous Add assertions (optional), cliquez sur Response Body et sur la clé url pour que votre test vérifie que le parcours s’est terminé avec une réponse contenant l’URL de paiement.
Aucun paramètre d’exécution ni aucune extraction de variables ne sont requis lors de cette dernière étape.
Une fois votre étape terminée, cliquez sur Save Step.

Vous pouvez ensuite configurer les autres conditions de votre test, notamment sa fréquence, ses conditions d’alerte et le monitor de test. Une fois que vous êtes prêt à enregistrer la configuration de votre test et votre monitor, cliquez sur Create.

Pour en savoir plus, consultez la section Utiliser des monitors de test Synthetic.

Visualiser les résultats du test

Les pages de détails des tests API et tests API à plusieurs étapes comprennent une vue d’ensemble de la configuration du test, l’uptime global associé aux endpoints testés pour chaque emplacement, des graphiques sur les temps de réponse et les délais réseau, ainsi que la liste des résultats et des événements du test.

Pour découvrir le motif d’un échec de test, faites défiler la page jusqu’à la section Test Results et cliquez sur les résultats d’un test ayant échoué. Afin de résoudre le problème, passez en revue les assertions qui ont échoué et les détails de la réponse, tels que le code de statut, le temps de réponse ainsi que les en-têtes et le corps associés.

Grâce à l’intégration de la solution APM Datadog à la surveillance Synthetic, vous pouvez identifier la cause de l’échec d’un test en consultant les traces générées par l’exécution du test dans l’onglet Traces.