Tests API à plusieurs étapes
Présentation
Grâce aux tests API à plusieurs étapes, vous pouvez exécuter plusieurs requêtes HTTP à la suite afin d’effectuer une surveillance proactive et de vous assurer que les parcours complexes de vos services clés sont disponibles en tout temps et tout lieu. Si vous souhaitez transmettre à vos services des requêtes individuelles, utilisez plutôt des tests API.
Vous pouvez effectuer les opérations suivantes :
- Exécutez des requêtes HTTP sur des endpoints d’API nécessitant une authentification (par exemple, via un token).
- Surveillez des transactions commerciales essentielles au niveau de l’API.
- Simulez toutes les étapes des parcours utilisateur sur des applications mobiles.
Si l’un de vos services est moins réactif ou si ses réponses ne correspondent pas à vos attentes (corps de réponse ou code de statut inattendu, etc.), votre test peut prévenir votre équipe, bloquer votre pipeline de CI ou même annuler le déploiement à l’origine de l’erreur.
Les tests API à plusieurs étapes peuvent s’exécuter depuis des emplacements gérés par Datadog et des emplacements privés. Ainsi, vous bénéficiez d’une couverture complète de vos systèmes, en interne comme en externe.
Configuration
- Attribuez un nom à votre test API à plusieurs étapes.
- Ajoutez des tags
env et tout autre tag de votre choix à votre test API à plusieurs étapes. Vous pourrez ensuite utiliser ces tags pour filtrer rapidement vos tests Synthetic depuis la page d’accueil de la surveillance Synthetic.
Sélectionner des emplacements
Sélectionnez les emplacements de votre test API à plusieurs étapes. Les tests API peuvent être exécutés depuis des emplacements gérés et des emplacements privés, selon que vous souhaitez exécuter le test à l’extérieur ou à l’intérieur de votre réseau.
Définir des étapes
Pour créer une étape de requête HTTP, cliquez sur Create Your First Step.
Remarque : par défaut, vous ne pouvez pas créer plus de 10 étapes. Pour augmenter cette limite, contactez l’assistance Datadog.
Définir une requête
Donnez un nom à votre étape.
Choisissez une valeur pour HTTP Method et indiquez l’URL à interroger. Les méthodes disponibles sont GET, POST, PATCH, PUT, HEAD, DELETE et OPTIONS. Les URL http et https sont prises en charge.
Enrichissez votre requête HTTP en modifiant les réglages de la section Advanced Options (facultatif) :
- Follow redirects : activez cette option pour que votre test HTTP suive jusqu’à dix redirections lors de l’exécution de la requête.
- Request headers : définissez les en-têtes à ajouter à votre requête HTTP. Vous pouvez également remplacer les en-têtes par défaut (par exemple, l’en-tête
user-agent). - Cookies : définissez les cookies à ajouter à votre requête HTTP. Définissez plusieurs cookies en suivant le format
<COOKIE_NOM1>=<COOKIE_VALEUR1>; <COOKIE_NOM2>=<COOKIE_VALEUR2>.
- HTTP Basic Auth : ajoutez des identifiants d’authentification basique HTTP.
- Digest Auth : ajoutez des identifiants d’authentification Digest.
- NTLM v1 : ajoutez vos identifiants d’authentification NTLM.
- AWS Signature v4 : saisissez votre ID de clé d’accès et votre clé d’accès secrète. Datadog génère alors la signature pour votre requête. Cette option repose sur une implémentation de base de SigV4. Les signatures spécifiques (par exemple pour AWS S3) ne sont pas implémentées.
- Encode parameters : ajoutez le nom et la valeur des paramètres de requête nécessitant un encodage.
- Body type : sélectionnez le type du corps de requête (
text/plain, application/json, text/xml, text/html, application/x-www-form-urlencoded ou None) que vous voulez ajouter à votre requête HTTP. - Request body : ajoutez le contenu du corps de votre requête HTTP. La taille du corps de la requête ne doit pas dépasser 50 Ko.
- Ignore server certificate error : activez cette option pour que votre test HTTP poursuive son processus de connexion même lorsque des erreurs de validation du certificat SSL surviennent.
- Client certificate : authentifiez-vous via mTLS en important votre certificat client et la clé privée associée.
- Proxy URL : indiquez l’URL du proxy que la requête HTTP doit utiliser (
http://<VOTRE_UTILISATEUR>:<VOTRE_MOT_DE_PASSE>@<VOTRE_IP>:<VOTRE_PORT>). - Proxy Header : ajoutez les en-têtes à inclure dans la requête HTTP envoyée au proxy.
- Do not save response body : sélectionnez cette option pour désactiver l’enregistrement du corps de la réponse au moment de l’exécution. Cela vous permet de vous assurer qu’aucune donnée sensible ne figure dans les résultats de test. Utilisez toutefois cette option avec précaution, car elle peut rendre plus difficile le dépannage des problèmes. Pour découvrir d’autres recommandations de sécurité, consultez la section Sécurité de la surveillance Synthetic.
Cliquez sur Test URL pour tester la configuration de requête. Un aperçu de la réponse s’affiche alors.
Ajouter des assertions
Les assertions définissent un résultat de test escompté. Lorsque vous cliquez sur Test URL, les assertions de base pour response time, status code et header content-type sont ajoutées en fonction de la réponse obtenue. Les assertions sont facultatives pour les tests API à plusieurs étapes.
| Type | Opérateur | Type de valeur |
|---|
| body | contains, does not contain, is, is not,
matches, does not match,
jsonpath, xpath | Chaîne
Regex
Chaîne, Regex |
| header | contains, does not contain, is, is not,
matches, does not match | Chaîne
Regex |
| response time | is less than | Nombre entier (ms) |
| status code | is, is not | Nombre entier |
Remarque : les tests HTTP peuvent décompresser les corps de réponse contenant les en-têtes content-encoding suivants : br, deflate, gzip et identity.
Vous pouvez créer jusqu’à 20 assertions par étape en cliquant sur New assertion ou directement sur l’aperçu de la réponse.
Ajouter des paramètres d’exécution
Cliquez sur Continue with test if this step fails pour que votre test passe aux étapes suivantes en cas d’échec d’une étape.
Cette option permet à vos tests de s’auto-nettoyer. Par exemple, un test peut créer une ressource, effectuer un certain nombre d’actions sur cette ressource, puis finir par supprimer cette ressource. Si vous appliquez ce réglage à chaque étape intermédiaire, en cas d’échec d’une de ces étapes, la ressource est supprimée à la fin du test, et aucun faux positif n’est créé.
Activez l’option Consider entire test as failed if this step fails pour chaque étape intermédiaire afin que votre test génère systématiquement une alerte lorsque la réponse de l’un des endpoints est inattendue.
Nouvelles tentatives
Votre test peut déclencher X nouvelles tentatives après Y ms en cas d’échec. Cet intervalle peut être personnalisé en fonction de vos préférences en matière d’alertes.
Vous pouvez également extraire des variables à partir de la réponse de votre requête HTTP en parsant les en-têtes ou le corps de la réponse. La valeur de la variable est mise à jour à chaque fois que l’étape de requête HTTP est exécutée.
Pour parser votre variable :
Donnez un nom à votre variable en renseignant le champ Variable Name. Ce nom doit comporter au moins trois caractères et peut uniquement contenir des lettres majuscules, des chiffres et des underscores.
Indiquez si la variable doit être extraite à partir des en-têtes ou du corps de la réponse :
- Extraire la valeur à partir du Response Header : utilisez l’en-tête de réponse complet de votre requête HTTP comme valeur de variable, ou parsez l’en-tête à l’aide d’une
regex. - Extraire la valeur à partir du Response Body : utilisez le corps de réponse complet de votre requête HTTP comme valeur de variable, ou parsez le corps avec une
regex, une expression JSONPath ou une expression XPath.
Une fois la variable créée, vous pouvez l’utiliser dans les étapes ultérieures de votre test API à plusieurs étapes. Pour en savoir plus, consultez la rubrique Utiliser des variables.
Indiquer la fréquence du test
Les tests API à plusieurs étapes peuvent être exécutés :
- Selon un programme, pour vous assurer que vos utilisateurs peuvent toujours accéder à vos principaux endpoints. Sélectionnez la fréquence à laquelle vous souhaitez que Datadog exécute votre test API à plusieurs étapes.
- Dans vos pipelines de CI/CD, pour déployer votre code sans craindre de dégrader l’expérience de vos utilisateurs.
- À la demande, afin d’exécuter les tests au moment le plus opportun pour vos équipes.
Définir des conditions d’alerte
Définissez des conditions d’alerte afin de spécifier les circonstances dans lesquelles vous souhaitez qu’un test échoue et déclenche une alerte.
Règle d’alerte
Lorsque vous définissez les conditions d’alerte sur An alert is triggered if any assertion fails for X minutes from any n of N locations, une alerte se déclenche uniquement si les deux conditions suivantes se vérifient :
- Au moins un emplacement a donné lieu à un échec (au moins une assertion a échoué) au cours des X dernières minutes
- À un moment au cours des X dernières minutes, au moins n emplacements ont donné lieu à un échec.
Nouvelle tentative rapide
Votre test peut déclencher X nouvelles tentatives après Y ms en cas d’échec. Cet intervalle peut être personnalisé en fonction de vos préférences en matière d’alertes.
La disponibilité d’un emplacement est calculée pour chaque évaluation (quels que soient les résultats du dernier test avant l’évaluation). La disponibilité totale est calculée selon les conditions d’alerte configurées. Les notifications envoyées se basent sur la disponibilité totale.
Votre test envoie une notification selon les conditions d’alerte définies au préalable. Référez-vous à cette section pour définir les conditions et le message à envoyer à vos équipes.
Tout comme pour les monitors, sélectionnez les utilisateurs et/ou services qui doivent recevoir des notifications. Pour ce faire, ajoutez @notification au message, ou cherchez des membres d’équipe ou des intégrations connectées à l’aide de la liste déroulante.
Saisissez un message de notification pour le test. Ce champ accepte le format de mise en forme Markdown standard ainsi que les variables conditionnelles suivantes :
| Variable conditionnelle | Description |
|---|
{{#is_alert}} | S’affiche lorsque le test envoie une alerte. |
{{^is_alert}} | S’affiche lorsque le test n’envoie pas d’alerte. |
{{#is_recovery}} | S’affiche lorsque le test est rétabli depuis un état d’alerte. |
{{^is_recovery}} | S’affiche lorsque le test n’est pas rétabli depuis un état d’alerte. |
Indiquez une fréquence de renvoi du message de notification en cas d’échec d’un test. Si vous ne souhaitez pas renvoyer de notification en cas d’échec, définissez l’option sur Never renotify if the monitor has not been resolved.
Cliquez sur Save pour enregistrer votre test. Datadog se charge alors de son exécution.
Variables
Créer des variables locales
Vous pouvez extraire des variables à partir de n’importe quelle étape de votre test API à plusieurs étapes et réinjecter leurs valeurs dans les étapes suivantes de votre test.
Variables provenant d’un pattern
Vous pouvez créer des variables locales en cliquant sur Create Local Variable en haut à droite du formulaire de configuration de votre test. Vous pouvez définir leurs valeurs sur l’un des builtins disponibles ci-dessous :
{{ numeric(n) }}- Génère une chaîne numérique de
n chiffres. {{ alphabetic(n) }}- Génère une chaîne alphabétique de
n lettres. {{ alphanumeric(n) }}- Génère une chaîne alphanumérique de
n caractères. {{ date(n, format) }}- Génère une date dans l’un des formats acceptés. Sa valeur correspond à la date d’initiation du test +
n jours. {{ timestamp(n, unit) }}- Génère un timestamp dans l’une des unités acceptées. Sa valeur correspond au timestamp d’initiation du test +/-
n unités choisies.
Utiliser des variables
Les variables globales définies sur la page Settings et les variables définies localement peuvent être utilisées dans l’URL, les options avancées et les assertions de vos tests HTTP.
Pour afficher votre liste de variables, tapez {{ dans le champ souhaité.
Échec de test
Un test est considéré comme FAILED si une étape ne répond pas à une ou plusieurs de ses assertions ou si la requête d’une étape a échoué prématurément. Dans certains cas, le test peut en effet échouer sans que les assertions n’aient pu être comparées à l’endpoint. Voici la liste des erreurs concernées :
CONNREFUSED- Aucune connexion n’a pu être établie, en raison d’un refus explicite de la machine cible.
CONNRESET- La connexion a été interrompue de façon soudaine par le serveur à distance. Causes possibles : erreur ou défaillance du serveur Web lors de la réponse ou perte de connectivité du serveur Web.
DNS- L’entrée DNS est introuvable pour l’URL du test. Causes possibles : URL du test mal configurée ou configuration des entrées DNS incorrecte.
INVALID_REQUEST- La configuration du test n’est pas valide (par exemple, en raison d’une faute de frappe dans l’URL).
SSL- La connexion SSL n’a pas pu être établie. Pour en savoir plus, consultez la page relative aux erreurs.
TIMEOUT- La requête n’a pas pu être effectuée dans un délai raisonnable. Deux types d’erreur
TIMEOUT peuvent se produire :TIMEOUT: The request couldn’t be completed in a reasonable time. indique que la durée de la requête a dépassé le délai d’expiration défini (par défaut, 60 secondes).
Pour chaque requête, seules les étapes terminées sont affichées dans la cascade réseau. Par exemple, si rien d’autre que Total response time ne s’affiche, cela signifie que l’expiration est survenue durant la résolution DNS.- Le message
TIMEOUT: Overall test execution couldn't be completed in a reasonable time. indique que la durée de la requête et des assertions a atteint la durée maximale (60,5 secondes).
MALFORMED_RESPONSE- Le serveur à distance a répondu avec une charge utile non conforme aux spécifications HTTP.
Autorisations
Par défaut, seuls les utilisateurs disposant des rôles Admin ou Standard Datadog peuvent créer, modifier et supprimer des tests API Synthetic à plusieurs étapes. Pour que votre utilisateur puisse effectuer ces opérations, vous devez donc lui accorder l’un de ces deux rôles par défaut.
Si vous utilisez la fonctionnalités de rôle personnalisé, ajoutez votre utilisateur à un rôle personnalisé disposant des autorisations synthetics_read et synthetics_write pour la surveillance Synthetic.
Restreindre l’accès
Les clients qui ont configuré des rôles personnalisés sur leur compte peuvent utiliser la fonctionnalité de restriction d’accès.
Vous pouvez limiter l’accès d’un test API à plusieurs étapes à certains rôles de votre organisation. Lors de la création du test API à plusieurs étapes, choisissez les rôles (en plus de votre utilisateur) auxquels vous souhaitez attribuer des autorisations de lecture/écriture pour votre test.
Pour aller plus loin
Documentation, liens et articles supplémentaires utiles:
