Présentation

Les tests HTTP vous permettent d’envoyer des requêtes HTTP aux endpoints d’API de vos applications pour vérifier les réponses et les conditions définies, y compris le temps de réponse global, le code de statut attendu, l’en-tête ou le contenu du corps.

Les tests HTTP peuvent être exécutés à partir d’emplacements gérés et privés selon que vous préférez exécuter le test depuis l’extérieur ou l’intérieur de votre réseau. Les tests HTTP peuvent être exécutés selon un planning, à la demande ou directement au sein de vos pipelines CI/CD.

Configuration

Vous pouvez créer un test en utilisant l’une des options suivantes :

• Créer un test à partir d’un modèle :

  1. Survolez l’un des modèles pré-remplis et cliquez sur View Template. Cela ouvre un panneau latéral affichant des informations de configuration pré-remplies, notamment : Test Details, Request Details, Assertions, Alert Conditions et Monitor Settings.

  2. Cliquez sur +Create Test pour ouvrir la page Define Request, où vous pouvez examiner et modifier les options de configuration pré-remplies. Les champs présentés sont identiques à ceux disponibles lors de la création d’un test à partir de zéro.

  3. Cliquez sur Save Details pour soumettre votre test d’API.
     
     

• Créer un test à partir de zéro :

  1. Pour créer un test à partir de zéro, cliquez sur le modèle

     • Start from scratch
     , puis sélectionnez le type de requête HTTP et spécifiez l’URL à interroger. Les méthodes disponibles sont : GET, POST, PATCH, PUT, HEAD, DELETE et OPTIONS. Les URL http et https sont toutes deux prises en charge.
     Consultez Options avancées pour plus d'options.

  2. Name votre test HTTP.

  3. Add Environment Tags ainsi que tout autre tag à votre test HTTP. Vous pouvez ensuite utiliser ces tags pour filtrer vos tests Synthetic sur la page Synthetic Monitoring & Continuous Testing.

  4. Click Send pour essayer la configuration de la requête. Un aperçu de la réponse s’affiche sur le côté droit de votre écran.
     
     

  5. Click Create Test to submit your API test.

Extraits

When setting up a new Synthetic Monitoring API test, use snippets to automatically fill in basic auth, performance, and regions, rather than selecting these options manually. The following snippets are available:

• Basic Auth: Automatically test your APIs using pre-populated basic auth headers, JavaScript, bearer token, and API/app key auth variables.

• Performance: Automatically configure a test with the shortest frequency (one minute), perform a gRPC health check, and test for overall response time latency with a breakdown of network timing.

• Regions: Automatically test your API endpoint against a location in each of the three primary geographic regions (AMER, APAC and EMEA).
  
  

  

Options avancées

• HTTP version : Sélectionnez HTTP/1.1 only, HTTP/2 only ou HTTP/2 fallback to HTTP/1.1.

  Pour les endpoints utilisant un CDN (comme Akamai, CloudFront ou Fastly), définissez la version HTTP sur HTTP/2 only ou HTTP/1.1 only au lieu de la valeur par défaut HTTP/2 with fallback to HTTP/1.1. La prise en charge de la version HTTP varie selon les sondes, et le paramètre par défaut peut entraîner des erreurs HTTP intermittentes telles que :

  • MALFORMED_RESPONSE: Unable to parse HTTP response
  • Session closed without receiving a SETTINGS frame
  • Error HTTP2: Error performing HTTP/2 request

• Follow redirects : Sélectionnez cette option pour que votre test HTTP suive jusqu’à dix redirections lors de l’exécution de la requête.

• Ignore server certificate error : Sélectionnez cette option pour que votre test HTTP poursuive la connexion même en cas d’erreurs lors de la validation du certificat SSL.

• Timeout : Spécifiez la durée en secondes avant l’expiration du test.

• 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 utilisant le format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.

• Client Certificate : Authentifiez-vous via mTLS en téléchargeant votre certificat client (.crt) et la clé privée associée (.key) au format PEM. Vous pouvez utiliser la bibliothèque openssl pour convertir vos certificats. Par exemple, convertissez un certificat PKCS12 en clés privées et certificats au format PEM.

  openssl pkcs12 -in <CERT>.p12 -out <CERT_KEY>.key -nodes -nocerts
  openssl pkcs12 -in <CERT>.p12 -out <CERT>.cert -nokeys
  

• HTTP Basic Auth : Ajoutez des identifiants d’authentification HTTP de base.

• Digest Auth : Ajoutez des identifiants d’authentification Digest.

• NTLM : Ajoutez des identifiants d’authentification NTLM. Prend en charge NTLMv2 et NTLMv1.

• AWS Signature v4 : Saisissez votre ID de clé d’accès et votre clé d’accès secrète. Datadog génère la signature pour votre requête. Cette option utilise l’implémentation de base de SigV4. Les signatures spécifiques telles qu’Amazon S3 ne sont pas prises en charge nativement. Pour les requêtes de transfert « Single Chunk » vers des buckets Amazon S3, ajoutez x-amz-content-sha256 contenant le corps de la requête encodé en sha256 en tant qu’en-tête (pour un corps vide : x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855).

• OAuth 2.0 : Choisissez entre l’octroi d’identifiants client ou d’un mot de passe de propriétaire de ressource et saisissez une URL de jeton d’accès. Selon votre sélection, saisissez un identifiant client et un secret, ou un nom d’utilisateur et un mot de passe. Dans le menu déroulant, sélectionnez une option pour envoyer le jeton API en tant qu’en-tête d’authentification de base, ou pour envoyer les identifiants client dans le corps. En option, vous pouvez fournir des informations supplémentaires telles que l’audience, la ressource et le périmètre (ainsi que l’identifiant client et le secret, si vous avez sélectionné Resource Owner Password).

• JWT : Générez un jeton JWT Bearer signé pour l’authentification. Sélectionnez un algorithme de signature (HS256, RS256 ou ES256) et fournissez une clé de signature : saisissez un secret textuel pour HS256, ou téléchargez une clé privée au format PEM pour RS256 et ES256. Tous deux acceptent {{ GLOBAL_VARIABLE }} references. Enter payload claims as a JSON object; claims can be strings, numbers, Booleans, arrays, or nested objects. The iat (issued at) and exp (expiration) claims are auto-added by default. If you include iat or exp in the payload JSON, those values take precedence over the auto-generated ones. Optionally, set the expiration window in seconds (default: 3600), add custom JWT header fields such as kid or x5t, and customize the token prefix in the Authorization header (default: Bearer).

• Encode parameters : Ajoutez le nom et la valeur des paramètres de requête qui nécessitent un encodage.

• Body type : Sélectionnez le type de corps de requête (application/json, application/octet-stream, application/x-www-form-urlencoded, multipart/form-data, text/html, text/plain, text/xml, GraphQL ou None) que vous souhaitez ajouter à votre requête HTTP.
• Request body : Ajoutez le contenu du corps de votre requête HTTP.
  • Le corps de la requête est limité à une taille maximale de 50 kilo-octets pour application/json, application/x-www-form-urlencoded, text/html, text/plain, text/xml, GraphQL.
  • Le corps de la requête est limité à un fichier de 3 méga-octets pour application/octet-stream.
  • Le corps de la requête est limité à trois fichiers de 3 méga-octets chacun pour multipart/form-data.

• Proxy URL : Spécifiez l’URL du proxy par lequel la requête HTTP doit passer (http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>).
• Proxy header : Ajoutez des en-têtes à inclure dans la requête HTTP vers le proxy.

• Do not save response body : Sélectionnez cette option pour empêcher l’enregistrement du corps de la réponse lors de l’exécution et pour tronquer le message d’erreur des assertions JavaScript ayant échoué. Cela permet de garantir qu’aucune donnée sensible n’est affichée dans vos résultats de test, mais cela peut rendre le dépannage des échecs plus difficile. Pour obtenir des recommandations de sécurité complètes, consultez Synthetic Monitoring Data Security.

Définissez des variables pour vos tests d’API HTTP avec JavaScript :

Les fonctionnalités JavaScript ne sont pas prises en charge pour les tests d'API dans les emplacements privés Windows.

Définissez des assertions

Les assertions définissent ce qu’est un résultat de test attendu. Après avoir cliqué sur Test URL, des assertions de base sur response time, status code et header content-type sont ajoutées en fonction de la réponse obtenue. Vous devez définir au moins une assertion pour que votre test puisse effectuer une surveillance.

Type	Opérateur	Type de valeur
corps	contains, does not contain, is, is not, matches, does not match, jsonpath, xpath, jsonschema	Chaîne Regex Chaîne, Regex Chaîne
hachage du corps	md5, sha1, sha256	Chaîne
en-tête	contains, does not contain, is, is not, matches, does not match, does not exist, is less than, is less than or equal, is more than, is more than or equal	Chaîne Regex Aucun Entier
temps de réponse	is less than	Entier (ms)
code d’état	is, is not, matches, does not match	Entier Regex

Les tests HTTP peuvent décompresser les corps avec les en-têtes content-encoding suivants : br, deflate, gzip et identity.

Vous pouvez créer jusqu’à 20 assertions par test d’API en cliquant sur New Assertion ou en cliquant directement sur l’aperçu de la réponse :

Pour effectuer une logique OR dans une assertion, utilisez le comparateur matches regex pour définir une expression régulière avec plusieurs valeurs attendues comme (200|302). Par exemple, vous pouvez souhaiter que votre test HTTP réussisse lorsqu’un serveur doit répondre avec un code d’état 200 ou 302. L’assertion status code réussit si le code d’état est 200 ou 302. Vous pouvez également ajouter une logique OR sur une assertion body ou header avec le comparateur matches regex.

Si un test ne contient pas d’assertion sur le corps de la réponse, la charge utile du corps est abandonnée et le temps de réponse associé à la requête est renvoyé, dans la limite du délai d’expiration défini par le Synthetics Worker.

Le corps de la réponse n’est renvoyé que si vous avez ajouté des assertions sur son contenu et que ces assertions ont échoué. Si un test contient une assertion sur le corps de la réponse et réussit, la charge utile du corps est supprimée et seul un extrait des 50 premiers caractères du corps de la réponse est affiché.

Si un test contient une assertion sur le corps de la réponse et que la limite de délai d’attente est atteinte, une erreur Assertions on the body/response cannot be run beyond this limit apparaît.

Utilisez les assertions JavaScript lorsque les assertions de réponse standard ne répondent pas à vos besoins de validation. Synthetic Monitoring utilise la bibliothèque d’assertion Chai, qui fournit dd.expect(), dd.should et dd.assert() pour des styles d’assertion flexibles.

Lorsque vous travaillez avec des réponses JSON, utilisez JSON.parse(dd.response.body) pour analyser le corps de la réponse avant d’accéder à ses propriétés. Ceci est requis pour toutes les méthodes d’assertion (dd.assert(), dd.expect() et dd.should) lors de la validation de données JSON.

• Les fonctionnalités JavaScript ne sont pas prises en charge pour les tests d'API dans les emplacements privés Windows.
• Si le message d'erreur d'une assertion JavaScript échouée peut contenir des données sensibles, sous Advanced Options > Privacy, activez Do not save response body. Ceci tronque le message d'erreur de l'assertion.

Utilisation de dd.assert()

Utilisez dd.assert() pour une syntaxe d’assertion traditionnelle :

Par exemple, pour affirmer qu’un champ status.code fait partie de plusieurs valeurs autorisées :

Copy

const response = JSON.parse(dd.response.body);
// Assert that the status code is 200, 210, 320, or 330
dd.assert.include([200, 210, 320, 330], response.status.code);

Exemple de réponse :

{
  "status": {
    "code": 200,
    "message": "Success"
  }
}

Cette assertion :

• Analyse le corps de la réponse JSON
• Vérifie que status.code est inclus dans le tableau des valeurs autorisées (200, 210, 320 ou 330)

Le test réussit car status.code est 200, ce qui est inclus dans le tableau des valeurs autorisées.

Pour plus d’informations sur assert.include(), consultez la documentation de Chai assert.include().

Utilisation de dd.expect()

Utilisez dd.expect() pour les assertions avec validation de propriété imbriquée.

Par exemple, pour affirmer qu’un champ status.indicator correspond à l’une des valeurs attendues :

Copy

const response = JSON.parse(dd.response.body);
const regex = /^(major|critical|minor|none)$/;

dd.expect(response)
  .to.have.nested.property('status.indicator')
  .that.matches(regex);

Exemple de réponse :

{
  "status": {
    "indicator": "none"
  }
}

Cette assertion :

• Analyse le corps de la réponse JSON
• Valide que la propriété imbriquée status.indicator existe
• Vérifie que la valeur correspond au motif regex (l’un des suivants : major, critical, minor ou none)

Avec le regex /^(major|critical|minor|none)$/, le test réussit car status.indicator est "none", ce qui correspond au motif.

Avec le regex /^(major|critical|minor)$/, le test échoue car "none" n’est pas inclus dans les valeurs autorisées.

Pour plus d’informations sur expect(), consultez la documentation de Chai expect().

Utilisation de dd.should

Utilisez dd.should pour écrire des assertions avec une syntaxe en langage naturel :

Par exemple, pour affirmer qu’un champ status.indicator existe et est égal à une valeur spécifique :

Copy

const response = JSON.parse(dd.response.body);
response.status.should.exist();
const indicator = response.status.indicator;
indicator.should.equal('none');

Exemple de réponse :

{
  "status": {
    "indicator": "none"
  }
}

Cette assertion :

• Analyse le corps de la réponse JSON
• Vérifie que la propriété status existe
• Extrait la valeur de l’indicateur dans une variable
• Vérifie que status.indicator est égal à "none"

Le test réussit car status existe et status.indicator est "none".

Pour plus d’informations sur should(), consultez la documentation de Chai should().

Sélectionnez des emplacements

Sélectionnez le Locations à partir duquel exécuter votre test HTTP. Les tests HTTP peuvent être exécutés à partir d’emplacements gérés et privés selon que vous préférez exécuter le test depuis l’extérieur ou l’intérieur de votre réseau.

Datadog’s out-of-the-box managed locations allow you to test public-facing websites and endpoints from regions where your customers are located.

AWS:

GCP:

Azure:

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

Spécifiez la fréquence du test

Les tests HTTP peuvent être exécutés :

• Selon un planning pour garantir que vos endpoints les plus importants sont toujours accessibles à vos utilisateurs. Sélectionnez la fréquence à laquelle vous souhaitez que Datadog exécute votre test HTTP.
• Au sein de vos pipelines CI/CD pour commencer à livrer sans craindre qu’un code défectueux n’impacte l’expérience de vos clients.
• À la demande pour exécuter vos tests au moment le plus opportun pour votre équipe.

Define alert conditions

Set alert conditions to determine the circumstances under which you want a test to fail and trigger an alert.

Alerting rule

When you set the alert conditions to: An alert is triggered if any assertion fails for X minutes from any n of N locations, an alert is triggered only if these two conditions are true:

• At least one location was in failure (at least one assertion failed) during the last X minutes;
• At one moment during the last X minutes, at least n locations were in failure.

Fast retry

Your test can trigger retries X times after Y ms in case of a failed test result. Customize the retry interval to suit your alerting sensibility.

Location uptime is computed on a per-evaluation basis (whether the last test result before evaluation was up or down). The total uptime is computed based on the configured alert conditions. Notifications sent are based on the total uptime.

Configure the test monitor

A notification is sent by your test based on the alerting conditions previously defined. Use this section to define how and what to message your team.

1. Similar to how you configure monitors, select users and/or services that should receive notifications either by adding an @notification to the message or by searching for team members and connected integrations with the dropdown menu.

2. Enter the notification message for your test or use pre-filled monitor messages. This field allows standard Markdown formatting and supports the following conditional variables:

Notification messages include the message defined in this section and information about the failing locations. Pre-filled monitor messages are included in the message body section:

3. Specify how often you want your test to re-send the notification message in case of test failure. To prevent renotification on failing tests, check the option Stop re-notifying on X occurrences.

4. Click Save & Start Recording to save your test configuration and monitor.

For more information, see Synthetic Monitoring notifications.

Downtimes

To pause test execution during planned maintenance windows, select an existing Scheduled downtime in the Downtimes section. The test automatically pauses during the downtime’s scheduled time slots.

Note: You cannot create a new downtime from the test creation form. To create one, navigate to Settings > Downtimes.

En un clic

La création de test d’API suggère des endpoints à partir du Catalogue et des tests d’API existants pour préremplir votre formulaire de test avec des options pertinentes. Utilisez des sources de données Datadog existantes telles que les traces APM, la découverte d’endpoints du Catalogue et des tests Synthetic similaires existants créés par les utilisateurs.

Commencez à saisir dans le champ URL de test d’API pour obtenir des suggestions d’endpoints ou des tests similaires dans Synthetic Monitoring :

Ensuite, sélectionnez une suggestion pour préremplir votre configuration de test (options de requête et en-têtes, authentification et variables) :

Create local variables

To create a local variable, click + All steps > Variables. You can select one of the following available builtins to add to your variable string:

{{ numeric(n) }}

Generates a numeric string with n digits.

{{ alphabetic(n) }}

Generates an alphabetic string with n letters.

{{ alphanumeric(n) }}

Generates an alphanumeric string with n characters.

{{ date(n unit, format) }}

Generates a date in one of Datadog’s accepted formats with a value corresponding to the UTC date the test is initiated at + or - n units.

{{ timestamp(n, unit) }}

Generates a timestamp in one of Datadog’s accepted units with a value corresponding to the UTC timestamp the test is initiated at +/- n units.

{{ uuid }}

Generates a version 4 universally unique identifier (UUID).

{{ public-id }}

Injects the Public ID of your test.

{{ result-id }}

Injects the Result ID of your test run.

To obfuscate local variable values in test results, select Hide and obfuscate variable value. After you have defined the variable string, click Add Variable.

Apply filters to variable values

When you reference a variable, you can transform its resolved value by appending a filter with a pipe (|). Use the syntax {{ VARIABLE_NAME | filter }} anywhere a variable is accepted, such as the URL, request body, headers, and assertions. The following filters are available:

{{ VARIABLE_NAME | urlEncode }}

URL-encodes the variable’s value. For example, hello world becomes hello%20world.

{{ VARIABLE_NAME | urlDecode }}

URL-decodes the variable’s value. For example, hello%20world becomes hello world.

{{ VARIABLE_NAME | base64Encode }}

Base64-encodes the variable’s value. For example, hello becomes aGVsbG8=.

{{ VARIABLE_NAME | base64Decode }}

Base64-decodes the variable’s value. For example, aGVsbG8= becomes hello.

Filters apply to both local and global variables. You can apply one filter per reference, and filter names are case-sensitive.

Utilisez des variables

Vous pouvez utiliser les variables globales définies sur la page Settings 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 du test

Un test est considéré comme FAILED s’il ne satisfait pas une ou plusieurs assertions ou si la requête a échoué prématurément. Dans certains cas, le test peut échouer sans tester les assertions par rapport à l’endpoint.

Résumé de la chronologie

Le panneau Summary identifie les problèmes uniques provoquant des échecs lors des exécutions de test dans la période sélectionnée. Pour chaque problème, le panneau affiche :

• First seen : moment où le problème est apparu pour la première fois dans les exécutions de test.
• Last seen : moment où le problème est apparu le plus récemment dans les exécutions de test.
• Classification: indique si le problème est un True failure (un vrai problème avec votre application) ou un Test Misconfiguration (un problème avec la configuration du test), basé sur le résumé d’échec par IA.
• Description : une brève description de l’erreur.
• Latest alerts : une liste des alertes les plus récentes liées au problème.

Pour obtenir une liste complète des codes d’erreur HTTP et SSL, consultez API Testing Errors.

Lancer Bits Investigation

Pour identifier la cause première d’un test HTTP Synthetic en échec, lancez Bits Investigation. Bits Investigation analyse les résultats de test, les traces, les logs et les métriques pour faire ressortir une cause première et signaler si l’échec est dû à une régression ou à une mauvaise configuration.

Autorisations

Par défaut, seuls les utilisateurs disposant des rôles Datadog Admin et Datadog Standard peuvent créer, modifier et supprimer des tests HTTP Synthetic. Pour obtenir un accès de création, de modification et de suppression aux tests HTTP Synthetic, mettez à niveau votre utilisateur vers l’un de ces deux rôles par défaut.

Si vous utilisez la fonctionnalité de rôle personnalisé, ajoutez votre utilisateur à tout rôle personnalisé incluant les autorisations synthetics_read et synthetics_write.

Restreindre l’accès

Use granular access control to limit who has access to your test based on roles, teams, or individual users:

1. Open the permissions section of the form.
2. Click Edit Access.

3. Click Restrict Access.
4. Select teams, roles, or users.
5. Click Add.
6. Select the level of access you want to associate with each of them.
7. Click Done.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Présentation de Datadog Synthetic MonitoringBLOG Présentation des tests SyntheticCENTRE D'APPRENTISSAGE Débuter avec les tests HTTPDOCUMENTATION Exécuter des tests HTTP sur des endpoints internesDOCUMENTATION Exécuter des tests HTTP à plusieurs étapesDOCUMENTATION En savoir plus sur les monitors de test SyntheticDOCUMENTATION