Aperçu

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 ou d’emplacements privés selon votre préférence pour 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 calendrier, à la demande, ou directement dans 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 Voir le modèle. Cela ouvre un panneau latéral affichant les informations de configuration pré-remplies, y compris : Détails du test, Détails de la requête, Assertions, Conditions d’alerte et Paramètres de surveillance.

  2. Cliquez sur +Créer un test pour ouvrir la page Définir la requête, 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 Enregistrer les détails pour soumettre votre test API.
     
     

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

  1. Pour construire un test à partir de zéro, cliquez sur le modèle + Commencer à partir de zéro, puis sélectionnez le HTTPtype de requête 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.

     Voir Options avancées pour plus d'options.

  2. Name your HTTP test.

  3. Add Environment Tags as well as any other tag to your HTTP test. You can then use these tags to filter through your Synthetic tests on the Synthetic Monitoring & Continuous Testing page.

  4. Click Send to try out the request configuration. A response preview is displayed on the right side of your screen.
     
     

  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

• Version HTTP : Sélectionnez HTTP/1.1 only, HTTP/2 only ou HTTP/2 fallback to HTTP/1.1.
• Suivre les redirections : Sélectionnez pour que votre test HTTP suive jusqu’à dix redirections lors de l’exécution de la demande.
• Ignorer l’erreur de certificat serveur : Sélectionnez pour que votre test HTTP continue la connexion même s’il y a des erreurs lors de la validation du certificat SSL.
• Délai d’attente : Spécifiez la durée en secondes avant que le test ne dépasse le délai d’attente.
• En-têtes de demande : Définissez les en-têtes à ajouter à votre demande 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 demande HTTP. Définissez plusieurs cookies en utilisant le format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.

• Certificat client : 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
  

• Authentification HTTP Basic : Ajoutez des identifiants d’authentification HTTP Basic.

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

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

• Signature AWS v4 : Entrez votre ID de clé d’accès et votre clé d’accès secrète. Datadog génère la signature pour votre demande. Cette option utilise l’implémentation de base de SigV4. Des signatures spécifiques telles qu’Amazon S3 ne sont pas prises en charge par défaut. Pour les demandes de transfert “Single Chunk” vers les buckets Amazon S3, ajoutez x-amz-content-sha256 contenant le corps de la demande 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 de l’identifiant client ou d’un mot de passe de propriétaire de ressource et entrez une URL de jeton d’accès. Selon votre sélection, entrez 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 soit envoyer le jeton API en tant qu’en-tête d’authentification de base, soit 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é Mot de passe de propriétaire de ressource).

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

• Type de corps : Sélectionnez le type de corps de la demande (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 demande HTTP.
• Corps de la demande : Ajoutez le contenu de votre corps de demande HTTP.
  • Le corps de la demande est limité à une taille maximale de 50 kilooctets pour application/json, application/x-www-form-urlencoded, text/html, text/plain, text/xml, GraphQL.
  • Le corps de la demande est limité à un fichier de 3 mégaoctets pour application/octet-stream.
  • Le corps de la demande est limité à trois fichiers de 3 mégaoctets chacun pour multipart/form-data.

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

• Ne pas enregistrer le corps de la réponse : Sélectionnez cette option pour empêcher le corps de la réponse d’être enregistré à l’exécution et pour tronquer le message d’erreur des assertions JavaScript échouées. Cela aide à 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 des recommandations complètes en matière de sécurité, voir Sécurité des données de surveillance synthétique.

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

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

Définissez des assertions

Les assertions définissent quel est le résultat de test attendu. Après avoir cliqué sur Tester l’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 soit surveillé.

Type	Opérateur	Type de valeur
corps	contains, does not contain, is, is not, matches, does not match, jsonpath, xpath	Chaîne Regex
en-tête	contains, does not contain, is, is not, matches, does not match	Chaîne Regex
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 suivants content-encoding : br, deflate, gzip et identity.

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

Pour appliquer une logique OR dans une assertion, utilisez le comparateur matches regex pour définir une regex comportant plusieurs valeurs attendues, par exemple (200|302). Par exemple, vous pouvez vouloir que votre test HTTP réussisse lorsque le 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 worker Synthetic.

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 temps est atteinte, une erreur Assertions on the body/response cannot be run beyond this limit apparaît.

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

Lors de la manipulation 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 des données JSON.

• Les capacités JavaScript ne sont pas prises en charge pour les tests d'API dans des emplacements privés Windows.
• Si le message d'erreur d'une assertion JavaScript échouée peut inclure des données sensibles, sous Options avancées > Confidentialité, activez Ne pas enregistrer le corps de la réponse. Cela tronque le message d'erreur d'assertion.

Utilisation de dd.assert()

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

Par exemple, pour affirmer qu’un champ status.code est l’une des 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 parce que 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 : major, critical, minor ou none)

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

Avec le regex /^(major|critical|minor)$/, le test échoue parce que "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 parce que status existe et que status.indicator est "none".

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

Sélectionnez les emplacements

Sélectionnez les Emplacements à partir desquels exécuter votre test HTTP. Les tests HTTP peuvent être exécutés à partir d’emplacements gérés et privés selon votre préférence pour exécuter le test de l’extérieur ou de 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 des tests

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

• Selon un calendrier pour garantir que vos points de terminaison les plus importants sont toujours accessibles à vos utilisateurs. Sélectionnez la fréquence à laquelle vous souhaitez que Datadog exécute votre test HTTP.
• Dans vos pipelines CI/CD pour commencer à livrer sans craindre que du code défectueux n’impacte l’expérience de vos clients.
• À la demande pour exécuter vos tests quand cela a le plus de sens 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.

Un clic

La création de tests API suggère des endpoints du Catalog et des tests 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 des endpoints du Catalog et les Synthetic tests similaires créés par des utilisateurs.

Commencez à taper dans le champ URL du test API pour obtenir des suggestions d’endpoints ou de Synthetic 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. Once you have defined the variable string, click Add Variable.

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 contre l’endpoint.

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

Permissions

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

Si vous utilisez la fonctionnalité de rôle personnalisé, ajoutez votre utilisateur à tout rôle personnalisé qui inclut les permissions 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.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Présentation de la surveillance Datadog SyntheticsBLOG 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