Comment définir des paramètres globaux dans Apidog (Envoyer les en-têtes d'authentification à chaque requête)

Vous avez quarante points d'accès (endpoints) dans un projet, et chacun d'entre eux nécessite le même en-tête Authorization: Bearer ... et un en-tête X-Api-Version à chaque appel. Ajouter ces deux lignes manuellement à chaque requête est lent, et pire encore, cela génère des incohérences. Un point d'accès reçoit le jeton, un autre est oublié, et vous passez un après-midi à traquer une erreur 401 qui n'apparaît que sur trois routes sur quarante.

Il existe une meilleure façon. Apidog vous permet de définir des paramètres une seule fois et de les appliquer automatiquement à chaque requête. Définissez l'en-tête au niveau du projet, référencez votre jeton comme une variable, et chaque point d'accès l'héritera sans que vous n'ayez à toucher une seule requête. Ce guide passe en revue les trois leviers documentés pour cela : les paramètres globaux, les variables d'environnement et un script de repli (fallback) limité au dossier. Vous terminerez avec une configuration fonctionnelle qui attache un en-tête d'authentification et un en-tête de version à tout, plus un moyen de prouver que l'en-tête a bien été envoyé. Si vous souhaitez d'abord des informations plus approfondies sur les variables, notre guide sur la maîtrise des variables dans Apidog complète bien celui-ci.

bouton

L'idée d'une requête qui transporte un en-tête standard à chaque appel n'est pas unique à Apidog. C'est le même modèle que la référence des en-têtes HTTP MDN décrit : un petit ensemble de paires clé/valeur qui accompagnent chaque requête. Le rôle d'Apidog est de vous permettre de définir cet ensemble une seule fois.

Ce que "paramètres globaux" signifie réellement

Un paramètre global dans Apidog est un paramètre de requête qui s'applique à l'ensemble du projet plutôt qu'à un seul point d'accès. Vous le définissez une fois, et Apidog l'attache automatiquement aux requêtes correspondantes.

Les paramètres globaux couvrent quatre emplacements, et c'est la clé de toute la fonctionnalité :

En-têtes (En-tête de Requête) pour des éléments comme Authorization ou X-Api-Version.
Cookies (Informations de Cookie) pour les cookies de session.
Requête (Paramètre de Requête URL) pour des valeurs comme ?api_key= ajoutées à chaque URL.
Corps (Paramètre du Corps de Requête) pour un champ que chaque corps de requête devrait contenir.

Pour le cas d'utilisation de l'en-tête d'authentification, vous voulez les En-têtes. Les trois autres fonctionnent de la même manière si votre valeur standard se trouve dans un cookie, une chaîne de requête ou un champ du corps à la place.

Une règle est importante avant de commencer : les paramètres globaux ont une priorité inférieure à celle des paramètres définis au niveau du point d'accès. Si une requête spécifique définit déjà son propre en-tête Authorization, cette valeur au niveau du point d'accès l'emporte et le paramètre global est ignoré. Considérez un paramètre global comme la valeur par défaut qui est utilisée lorsqu'un point d'accès n'a pas défini la sienne, et non comme un remplacement forcé qui écrase tout. Cette précédence est ce qui rend les paramètres globaux sûrs à activer sur un grand projet.

Définir un en-tête global sur chaque requête

Voici le déroulement principal. L'objectif : attacher Authorization et X-Api-Version à chaque point d'accès du projet sans en modifier aucun.

Étape 1 : Ouvrir la gestion de l'environnement

Les paramètres globaux se trouvent dans la Gestion de l'environnement, que vous ouvrez en haut à droite de la page. C'est le point d'entrée pour les paramètres qui s'appliquent à l'ensemble du projet, et la documentation Apidog la décrit comme l'emplacement des valeurs qui accompagnent chaque requête. Ouvrez-la, et vous verrez les sections où vous ajoutez des paramètres par emplacement.

Étape 2 : Choisir l'emplacement des en-têtes

Choisissez En-têtes (l'emplacement En-tête de Requête) puisque vous ajoutez un en-tête d'authentification. Si votre valeur standard était un cookie, un paramètre de requête ou un champ de corps, vous choisiriez Cookies, Requête ou Corps à la place. Les mécanismes sont identiques pour les quatre.

Étape 3 : Remplir les détails du paramètre

Chaque paramètre global possède un ensemble fixe de propriétés. Remplissez-les pour votre premier en-tête :

Nom : Authorization
Type : le type de paramètre (chaîne de caractères pour une valeur d'en-tête).
Valeur par défaut : Bearer {{token}} (plus d'informations sur cette partie {{token}} ci-dessous).
Description : une courte note comme "Jeton Bearer pour tous les points d'accès authentifiés."

Un champ Default et un marqueur obligatoire (un astérisque *) apparaissent également sur les paramètres requis. Ajoutez une deuxième ligne de la même manière pour l'en-tête de version :

Nom : X-Api-Version
Type : chaîne de caractères
Valeur par défaut : 2024-08-01
Description : "Version d'API fixée pour chaque requête."

Étape 4 : Activer le paramètre

Chaque paramètre dispose d'un interrupteur d'activation/désactivation sur le côté droit. Activez-le pour activer le paramètre. Cet interrupteur est pratique plus tard : si vous devez désactiver un en-tête global pour une session de débogage, vous le désactivez ici au lieu de le supprimer et de tout retaper.

Étape 5 : Enregistrer

Enregistrez la configuration. Les deux en-têtes sont maintenant globaux. Chaque requête du projet transportera Authorization et X-Api-Version, à moins qu'un point d'accès spécifique n'en remplace l'un d'eux.

Étape 6 : Prouver qu'il a bien été envoyé

Ne vous fiez pas à son fonctionnement ; vérifiez. Envoyez n'importe quelle requête dans le projet, puis ouvrez l'onglet Requête Réelle dans la console de réponse. Cet onglet affiche la requête exactement telle qu'elle a été envoyée, avec les variables déjà remplacées par leurs valeurs réelles. Vous devriez y voir les deux en-têtes listés :

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01

Si les en-têtes apparaissent dans la Requête Réelle, ils ont été envoyés sur le réseau. C'est l'étape la plus utile de toute la configuration, car elle transforme "Je pense que c'est appliqué" en "Je peux voir que c'est appliqué".

Gardez le secret hors de l'en-tête : utilisez une variable

Notez que la valeur par défaut ci-dessus était Bearer {{token}}, et non Bearer sk_live_7f3a9c2e1b8d4056. Cette syntaxe à double accolade référence une variable au lieu de coder en dur le jeton brut dans le paramètre. Le schéma Bearer lui-même est défini dans la RFC 6750, et la référence de l'en-tête Authorization MDN explique comment les serveurs le lisent. La documentation d'Apidog est explicite sur l'aspect sécurité : pour les données sensibles comme les jetons d'authentification et les clés API, utilisez des variables d'environnement plutôt que de stocker la valeur brute comme valeur par défaut en texte clair. Une variable est un espace réservé dynamique pour une valeur que vous utilisez dans de nombreuses requêtes et scripts, et elle maintient le secret hors de la définition du paramètre.

Voici comment configurer la variable token :

Cliquez sur l'icône d'environnement (l'icône ≡) en haut à droite. Notez qu'il s'agit d'un point d'entrée différent de la Gestion de l'environnement : l'icône ≡ est l'endroit où se trouvent les variables.
Recherchez la section Variables Globales.
Créez une variable, par exemple token avec la valeur de votre secret bearer.
Cliquez sur Enregistrer.

Maintenant, la valeur de votre en-tête global Bearer {{token}} se résout en Bearer <votre-vrai-secret> au moment de l'envoi, et l'onglet Requête Réelle confirme la substitution. Le fait de survoler le nom d'une variable n'importe où affiche sa valeur et sa portée actuelles, ce qui est un moyen rapide de vérifier que vous avez référencé la bonne.

Cette association est le modèle recommandé : le paramètre global détient l'emplacement de l'en-tête, et la variable détient le secret. Notre étude approfondie sur la gestion de l'environnement et des secrets du client API explique plus en détail comment garder les jetons hors de tout ce que vous pourriez partager ou commettre.

Changer les valeurs par environnement

Les variables deviennent plus utiles lorsque vous en avez plus d'une. Les projets réels utilisent différents serveurs pour le Développement, le Test et la Production, et chacun souhaite généralement un jeton différent. Regroupez chaque ensemble sous son propre environnement, puis basculez entre eux avec le menu déroulant Environnements à côté de l'icône ≡ (un environnement exemple pourrait être nommé Local Mock). Changer d'environnement dirige vos requêtes vers un ensemble différent de serveurs et échange les valeurs des variables de cet environnement. Votre en-tête global Bearer {{token}} reste le même ; seul le secret résolu change avec l'environnement. Si vous construisez des flux d'authentification basés sur cela, les concepts de notre guide des schémas de sécurité expliquent comment les définitions bearer, clé API et OAuth se traduisent en requêtes réelles.

Lorsque vous ne voulez l'en-tête que sur un seul dossier

Les paramètres globaux affectent l'ensemble du projet. Parfois, c'est trop large. Supposons que seuls vos points d'accès /admin nécessitent un en-tête X-Admin-Scope, et que le reste du projet ne devrait pas le transporter.

Voici la limitation honnête : Apidog n'a pas de champ natif "ajouter un en-tête" dans les paramètres de dossier. Il n'y a pas d'interface utilisateur d'en-tête au niveau du dossier à remplir. Ce que la documentation décrit plutôt est une solution de contournement utilisant un script de pré-requête au niveau du dossier, de sorte que chaque requête à l'intérieur de ce dossier hérite de l'en-tête. Le script utilise la scriptage pm.* compatible avec Postman :

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });

Ajoutez cela comme un script de pré-requête sur le dossier, et chaque requête dans le dossier récupérera l'en-tête, tandis que les requêtes en dehors du dossier ne le feront pas. C'est un script, pas un interrupteur de réglage, donc traitez-le comme un mécanisme de repli délibéré pour les besoins spécifiques à un dossier plutôt que comme le chemin principal. Pour le modèle de script plus large sur lequel cela repose, consultez notre guide sur les scripts de pré-requête et post-requête dans Apidog.

Quel levier, et quand

Vous avez maintenant trois façons d'attacher un en-tête sans modifier les points d'accès. Choisissez par portée :

Paramètre global (En-têtes) via la Gestion de l'environnement : l'en-tête s'applique à l'ensemble du projet. C'est votre option par défaut pour un en-tête d'authentification ou de version partagé.
Variable d'environnement ({{token}}) : associez-la au paramètre global afin que l'emplacement de l'en-tête soit global mais que le secret soit stocké en toute sécurité et échangé par environnement.
Script de pré-requête au niveau du dossier (pm.request.headers.add) : l'en-tête s'applique à un seul dossier. Utilisez cette option lorsque l'application à l'échelle du projet est trop large.

Quelques points à surveiller. Vérifiez l'absence de noms de paramètres en double afin que deux en-têtes globaux n'entrent pas en collision, et assurez-vous que le type de chaque paramètre correspond à son utilisation. Et rappelez-vous la règle de précédence : un point d'accès qui définit son propre Authorization annule le paramètre global, ce qui est une fonctionnalité utile lorsqu'une route a besoin d'un jeton différent, mais une surprise si vous avez oublié que cette route avait sa propre valeur. Aucune de ces trois fonctionnalités n'implique de restriction de plan dans la documentation, vous n'avez donc pas besoin d'un niveau spécifique pour les utiliser.

Automatiser le workflow avec l'interface de ligne de commande Apidog (CLI)

Les paramètres globaux et les environnements ne sont pas seulement une commodité de l'interface graphique ; ils sont également pris en compte dans les exécutions automatisées. Lorsque vous construisez un scénario de test enregistré dans Apidog et que vous l'exécutez depuis la ligne de commande, l'exécution hérite d'un environnement que vous passez par son identifiant, de sorte que le même en-tête Bearer {{token}} et la même valeur X-Api-Version qui fonctionnaient dans l'interface graphique se résolvent de la même manière en intégration continue (CI).

Installez la CLI (Node.js v16+) et authentifiez-vous :

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Puis exécutez un scénario enregistré contre un environnement spécifique :

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Le drapeau -e sélectionne l'environnement, de sorte que le scénario utilise les variables de cet environnement, y compris votre jeton. Le drapeau -t est l'identifiant du scénario de test et -r est le rapporteur (cli, html, ou junit). C'est le lien : définissez l'en-tête et la variable une seule fois, et chaque exécution de scénario via la CLI les transportera. Pour les détails de configuration et de jeton, consultez le guide d'installation de la CLI Apidog, et pour intégrer les exécutions dans l'automatisation, notre présentation de la CLI Apidog dans GitHub Actions montre le pipeline complet.

FAQ

Les paramètres globaux remplacent-ils un en-tête que j'ai défini sur un point d'accès spécifique ?

Non. Les paramètres globaux ont une priorité inférieure à celle des paramètres au niveau du point d'accès. Si une requête définit son propre en-tête Authorization, cette valeur l'emporte et le paramètre global est ignoré pour cette requête. Les paramètres globaux agissent comme la valeur par défaut du projet, remplissant les champs là où un point d'accès n'a pas défini sa propre valeur.

Où dois-je stocker le jeton réel afin qu'il ne soit pas en texte clair ?

Utilisez une variable d'environnement ou globale, et non une Valeur par défaut brute. Définissez l'en-tête global sur Bearer {{token}} et conservez le secret réel dans une variable créée via l'icône d'environnement ≡. La documentation recommande des variables ou des méthodes sécurisées pour les données sensibles spécifiquement afin que le jeton ne soit pas stocké en ligne. Notre guide sur l'extraction de variables avec JSONPath couvre la capture d'un jeton à partir d'une réponse de connexion et sa réutilisation de la même manière.

Comment puis-je confirmer que l'en-tête global a bien été envoyé ?

Envoyez n'importe quelle requête, puis ouvrez l'onglet Requête Réelle dans la console de réponse. Il affiche la requête telle qu'elle a été réellement envoyée, avec {{token}} et d'autres variables déjà remplacées par leurs valeurs. Si votre en-tête y apparaît, il a été envoyé sur le réseau.

Puis-je ajouter un en-tête par défaut à un seul dossier au lieu de l'ensemble du projet ?

Oui, mais pas via un champ de paramètres, car Apidog n'a pas d'interface utilisateur native pour les en-têtes de dossier. Ajoutez un script de pré-requête sur le dossier en utilisant pm.request.headers.add({ key, value }), et chaque requête dans ce dossier héritera de l'en-tête tandis que le reste du projet ne le fera pas.

Ai-je besoin d'un plan payant pour utiliser les paramètres globaux ou les variables d'environnement ?

La documentation de ces fonctionnalités ne mentionne aucune restriction de niveau. Les paramètres globaux, les variables d'environnement et les scripts de pré-requête au niveau du dossier sont tous documentés sans distinction entre version gratuite et payante.

En résumé

Définir un en-tête sur chaque requête est un travail unique dans Apidog : définissez l'en-tête comme un paramètre global sous la Gestion de l'environnement, référencez le secret comme une variable {{token}} pour qu'il reste hors du texte clair, et confirmez qu'il a été envoyé avec l'onglet Requête Réelle. Lorsque vous n'avez besoin d'un en-tête que sur un seul dossier, le script de pré-requête de repli s'en charge. Pour suivre dans votre propre projet, Téléchargez Apidog et configurez votre premier en-tête global. C'est gratuit, aucune carte de crédit n'est requise.

bouton