Sie haben vierzig Endpunkte in einem Projekt, und jeder einzelne benötigt bei jedem Aufruf denselben Authorization: Bearer ... Header und einen X-Api-Version Header. Das manuelle Hinzufügen dieser beiden Zeilen zu jeder Anfrage ist langsam, und schlimmer noch, es führt zu Abweichungen. Ein Endpunkt erhält das Token, ein anderer wird vergessen, und Sie verbringen einen Nachmittag damit, einen 401-Fehler zu jagen, der nur bei drei von vierzig Routen auftritt.
Es gibt einen besseren Weg. Apidog lässt Sie Parameter einmal definieren und diese automatisch auf jede Anfrage anwenden. Legen Sie den Header auf Projektebene fest, referenzieren Sie Ihr Token als Variable, und jeder Endpunkt erbt ihn, ohne dass Sie eine einzige Anfrage anfassen müssen. Dieser Leitfaden führt Sie durch die drei dokumentierten Hebel dafür: globale Parameter, Umgebungsvariablen und einen Skript-Fallback auf Ordnerebene. Sie werden am Ende eine funktionierende Einrichtung haben, die einen Authentifizierungs-Header und einen Versions-Header an alles anhängt, plus eine Möglichkeit zu beweisen, dass der Header tatsächlich über die Leitung gesendet wurde. Wenn Sie zuerst den tieferen Hintergrund zu Variablen wünschen, passt unser Leitfaden zum Beherrschen von Variablen in Apidog gut zu diesem.
Die Idee einer Anfrage, die bei jedem Aufruf einen Standard-Header mitführt, ist nicht einzigartig für Apidog. Es ist dasselbe Muster, das die MDN HTTP-Header-Referenz beschreibt: eine kleine Menge von Schlüssel/Wert-Paaren, die jede Anfrage begleiten. Apidogs Aufgabe ist es, Ihnen zu ermöglichen, diesen Satz einmal festzulegen.
Was „globale Parameter“ tatsächlich bedeuten
Ein globaler Parameter in Apidog ist ein Anfrageparameter, der für das gesamte Projekt gilt und nicht nur für einen einzelnen Endpunkt. Sie definieren ihn einmal, und Apidog hängt ihn automatisch an passende Anfragen an.
Globale Parameter decken vier Bereiche ab, und das ist der Schlüssel zur gesamten Funktion:
- Header (Anfrage-Header) für Dinge wie
AuthorizationoderX-Api-Version. - Cookies (Cookie-Informationen) für Session-Cookies.
- Abfrage (URL-Abfrageparameter) für Werte wie
?api_key=, die an jede URL angehängt werden. - Body (Anfrage-Body-Parameter) für ein Feld, das jeder Anfrage-Body enthalten sollte.
Für den Anwendungsfall des Auth-Headers benötigen Sie Header. Die anderen drei funktionieren auf die gleiche Weise, wenn Ihr Standardwert stattdessen in einem Cookie, einem Abfrage-String oder einem Body-Feld liegt.
Eine Regel ist wichtig, bevor Sie beginnen: Globale Parameter haben eine geringere Priorität als Parameter, die auf Endpunkt-Ebene definiert sind. Wenn eine spezifische Anfrage bereits ihren eigenen Authorization-Header setzt, gewinnt dieser Wert auf Endpunkt-Ebene und der globale Parameter tritt zurück. Betrachten Sie einen globalen Parameter als Standardwert, der eingesetzt wird, wenn ein Endpunkt sich nicht selbst geäußert hat, nicht als eine harte Überschreibung, die alles überstimmt. Diese Reihenfolge macht globale Parameter sicher für die Aktivierung in einem großen Projekt.
Einen globalen Header für jede Anfrage festlegen
Hier ist die Kernanleitung. Das Ziel: Authorization und X-Api-Version an jeden Endpunkt im Projekt anhängen, ohne einen davon zu bearbeiten.
Schritt 1: Umgebungsverwaltung öffnen
Globale Parameter befinden sich in der **Umgebungsverwaltung** (Environment Management), die Sie oben rechts auf der Seite öffnen. Dies ist der Einstiegspunkt für Parameter, die projektweit gelten, und die Apidog-Dokumentation beschreibt sie als die Heimat für Werte, die jede Anfrage begleiten. Öffnen Sie sie, und Sie sehen die Abschnitte, in denen Sie Parameter nach Ort hinzufügen können.
Schritt 2: Den Header-Ort auswählen
Wählen Sie **Header** (den Ort für den Anfrage-Header), da Sie einen Auth-Header hinzufügen. Wenn Ihr Standardwert ein Cookie, ein Abfrageparameter oder ein Body-Feld wäre, würden Sie stattdessen Cookies, Abfrage oder Body wählen. Die Mechanismen sind bei allen vier identisch.
Schritt 3: Die Parameterdetails ausfüllen
Jeder globale Parameter hat einen festen Satz von Eigenschaften. Füllen Sie diese für Ihren ersten Header aus:
- Name:
Authorization - Typ: der Parametertyp (String für einen Header-Wert).
- Standardwert:
Bearer {{token}}(mehr zu diesem{{token}}-Teil weiter unten). - Beschreibung: eine kurze Anmerkung wie „Bearer-Token für alle authentifizierten Endpunkte.“
Ein Standardfeld und eine Kennzeichnung für „erforderlich“ (ein Sternchen *) erscheinen auch bei erforderlichen Parametern. Fügen Sie auf die gleiche Weise eine zweite Zeile für den Versions-Header hinzu:
- Name:
X-Api-Version - Typ: String
- Standardwert:
2024-08-01 - Beschreibung: „Festgelegte API-Version für jede Anfrage.“
Schritt 4: Den Parameter aktivieren
Jeder Parameter hat rechts einen Ein-/Ausschalter. Schalten Sie ihn ein, um den Parameter zu aktivieren. Dieser Schalter ist später praktisch: Wenn Sie einen globalen Header für eine Debugging-Sitzung stummschalten müssen, deaktivieren Sie ihn hier, anstatt ihn zu löschen und alles neu einzugeben.
Schritt 5: Speichern
Speichern Sie die Konfiguration. Beide Header sind nun global. Jede Anfrage im Projekt wird Authorization und X-Api-Version mitführen, es sei denn, ein spezifischer Endpunkt überschreibt einen davon.
Schritt 6: Nachweisen, dass es tatsächlich gesendet wurde
Vertrauen Sie nicht darauf, dass es funktioniert hat; überprüfen Sie es. Senden Sie eine beliebige Anfrage im Projekt und öffnen Sie dann die Registerkarte **Tatsächliche Anfrage** (Actual Request) in der Antwortkonsole. Diese Registerkarte zeigt die Anfrage genau so an, wie sie gesendet wurde, wobei Variablen bereits durch ihre realen Werte ersetzt sind. Sie sollten beide Header dort aufgelistet sehen:
GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Wenn die Header in der „Tatsächlichen Anfrage“ (Actual Request) erscheinen, wurden sie über die Leitung gesendet. Dies ist der nützlichste Schritt in der gesamten Einrichtung, denn er verwandelt „Ich glaube, es wurde angewendet“ in „Ich kann sehen, dass es angewendet wurde.“
Das Geheimnis aus dem Header heraushalten: eine Variable verwenden
Beachten Sie, dass der Standardwert oben Bearer {{token}} war, nicht Bearer sk_live_7f3a9c2e1b8d4056. Diese Doppelklammer-Syntax referenziert eine Variable, anstatt den rohen Token fest in den Parameter zu kodieren. Das Bearer-Schema selbst ist in RFC 6750 definiert, und die MDN Authorization-Header-Referenz beschreibt, wie Server es lesen. Apidogs Dokumentation ist explizit, was den Sicherheitsaspekt angeht: Für sensible Daten wie Auth-Tokens und API-Schlüssel verwenden Sie Umgebungsvariablen, anstatt den Rohwert als Klartext-Standardwert zu speichern. Eine Variable ist ein dynamischer Platzhalter für einen Wert, den Sie in vielen Anfragen und Skripten verwenden, und sie hält das Geheimnis aus der Parameterdefinition heraus.
So richten Sie die token-Variable ein:
- Klicken Sie oben rechts auf das Umgebungssymbol (das
≡-Symbol). Beachten Sie, dass dies ein anderer Einstiegspunkt als die Umgebungsverwaltung ist: Das≡-Symbol ist der Ort, an dem Variablen gespeichert sind. - Suchen Sie den Abschnitt **Globale Variablen** (Global Variables).
- Erstellen Sie eine Variable, zum Beispiel
tokenmit dem Wert Ihres Bearer-Geheimnisses. - Klicken Sie auf **Speichern** (Save).
Nun wird Ihr globaler Header-Wert Bearer {{token}} zum Zeitpunkt des Sendens in Bearer <Ihr-echtes-Geheimnis> aufgelöst, und die Registerkarte „Tatsächliche Anfrage“ (Actual Request) bestätigt die Substitution. Wenn Sie den Mauszeiger über einen Variablennamen bewegen, wird dessen aktueller Wert und Geltungsbereich angezeigt, was eine schnelle Möglichkeit ist, zu überprüfen, ob Sie die richtige referenziert haben.
Diese Kombination ist das empfohlene Muster: Der **globale Parameter** besitzt den Header-Slot, und die **Variable** besitzt das Geheimnis. Unser detaillierter Leitfaden zum API-Client-Umgebungs- und Geheimnismanagement geht näher darauf ein, wie Tokens aus allem herausgehalten werden können, was Sie teilen oder committen könnten.
Werte pro Umgebung wechseln
Variablen werden nützlicher, wenn Sie mehr als eine haben. Echte Projekte greifen auf verschiedene Server für Entwicklung, Tests und Produktion zu, und jeder möchte normalerweise ein anderes Token. Gruppieren Sie jeden Satz unter seiner eigenen Umgebung und wechseln Sie dann zwischen ihnen mit der Dropdown-Liste „Umgebungen“ (Environments) neben dem ≡-Symbol (eine Beispielumgebung könnte „Local Mock“ heißen). Das Wechseln einer Umgebung richtet Ihre Anfragen auf einen anderen Satz von Servern und tauscht die Variablenwerte dieser Umgebung aus. Ihr globaler Bearer {{token}}-Header bleibt derselbe; nur das aufgelöste Geheimnis ändert sich mit der Umgebung. Wenn Sie darauf aufbauend Authentifizierungs-Flows erstellen, erklären die Konzepte in unserem Leitfaden zu Sicherheitsschemata, wie Bearer-, API-Schlüssel- und OAuth-Definitionen auf reale Anfragen abgebildet werden.
Wenn Sie den Header nur in einem Ordner wünschen
Globale Parameter betreffen das gesamte Projekt. Manchmal ist das zu breit gefasst. Nehmen wir an, nur Ihre /admin-Endpunkte benötigen einen X-Admin-Scope-Header, und der Rest des Projekts sollte ihn nicht mitführen.
Hier ist die ehrliche Einschränkung: Apidog hat kein natives „Header hinzufügen“-Feld in den Ordner-Einstellungen. Es gibt keine Header-Benutzeroberfläche auf Ordnerebene zum Ausfüllen. Was stattdessen in der Dokumentation beschrieben wird, ist eine Umgehungslösung unter Verwendung eines Pre-Request-Skripts auf Ordnerebene, sodass jede Anfrage innerhalb dieses Ordners den Header erbt. Das Skript verwendet Postman-kompatibles pm.*-Skripting:
pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
Fügen Sie dies als Pre-Request-Skript im Ordner hinzu, und jede Anfrage in diesem Ordner übernimmt den Header, während Anfragen außerhalb des Ordners dies nicht tun. Es ist ein Skript, kein Einstellungs-Toggle, behandeln Sie es also als bewussten Fallback für ordnerbezogene Anforderungen und nicht als primären Weg. Für das umfassendere Skripting-Modell, auf dem dies aufbaut, siehe unseren Leitfaden zu Pre-Request- und Post-Request-Skripten in Apidog.
Welcher Hebel, und wann
Sie haben nun drei Möglichkeiten, einen Header anzuhängen, ohne Endpunkte zu bearbeiten. Wählen Sie nach Geltungsbereich:
- Globaler Parameter (Header) über die Umgebungsverwaltung (Environment Management): Der Header gilt für das gesamte Projekt. Dies ist Ihre Standardeinstellung für einen gemeinsamen Auth-Header oder Versions-Header.
- Umgebungsvariable (
{{token}}): Kombinieren Sie sie mit dem globalen Parameter, sodass der Header-Slot global ist, das Geheimnis jedoch sicher gespeichert wird und pro Umgebung austauschbar ist. - Pre-Request-Skript auf Ordnerebene (
pm.request.headers.add): Der Header gilt nur für einen Ordner. Greifen Sie hierauf zurück, wenn projektweit zu umfassend ist.
Ein paar Dinge, auf die Sie achten sollten. Prüfen Sie auf doppelte Parameternamen, damit zwei globale Header nicht kollidieren, und stellen Sie sicher, dass der Typ jedes Parameters seiner Verwendung entspricht. Und denken Sie an die Präzedenzregel: Ein Endpunkt, der seinen eigenen Authorization-Header setzt, überschreibt den globalen. Dies ist eine Funktion, wenn eine Route ein anderes Token benötigt, aber eine Überraschung, wenn Sie vergessen haben, dass diese Route ihren eigenen Wert hatte. Keine dieser drei Funktionen unterliegt laut Dokumentation einer Planbeschränkung, daher benötigen Sie keine bestimmte Stufe, um sie zu verwenden.
Den Workflow mit der Apidog CLI automatisieren
Globale Parameter und Umgebungen sind nicht nur eine GUI-Annehmlichkeit; sie werden auch in automatisierte Abläufe übernommen. Wenn Sie in Apidog ein gespeichertes Testszenario erstellen und es über die Befehlszeile ausführen, erbt der Lauf eine Umgebung, die Sie per ID übergeben, sodass derselbe Bearer {{token}}-Header und X-Api-Version-Wert, der in der GUI funktionierte, im CI auf dieselbe Weise aufgelöst werden.
Installieren Sie die CLI (Node.js v16+) und authentifizieren Sie sich:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Führen Sie dann ein gespeichertes Szenario in einer bestimmten Umgebung aus:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Das -e-Flag wählt die Umgebung aus, sodass das Szenario die Variablen dieser Umgebung, einschließlich Ihres Tokens, übernimmt. Das -t-Flag ist die ID des Testszenarios und -r ist der Reporter (cli, html oder junit). Das ist der Zusammenhang: Definieren Sie den Header und die Variable einmal, und jeder Szenario-Lauf über die CLI führt sie mit sich. Für Setup- und Token-Details siehe den Leitfaden zur Apidog CLI-Installation, und um Läufe in die Automatisierung einzubinden, zeigt unser Apidog CLI in GitHub Actions-Walkthrough die gesamte Pipeline.
FAQ
Überschreiben globale Parameter einen Header, den ich an einem spezifischen Endpunkt gesetzt habe?
Nein. Globale Parameter haben eine geringere Priorität als Parameter auf Endpunktebene. Wenn eine Anfrage ihren eigenen Authorization-Header definiert, gewinnt dieser Wert und der globale wird für diese Anfrage ignoriert. Globale Parameter fungieren als Projektstandard und füllen Lücken, wo ein Endpunkt keinen eigenen Wert gesetzt hat.
Wo sollte ich das eigentliche Token speichern, damit es nicht im Klartext vorliegt?
Verwenden Sie eine Umgebungs- oder globale Variable, keinen rohen Standardwert. Setzen Sie den globalen Header auf Bearer {{token}} und bewahren Sie das eigentliche Geheimnis in einer Variable auf, die über das ≡-Umgebungssymbol erstellt wurde. Die Dokumentation empfiehlt Variablen oder sichere Methoden für sensible Daten, damit das Token nicht inline gespeichert wird. Unser Leitfaden zum Extrahieren von Variablen mit JSONPath behandelt das Erfassen eines Tokens aus einer Login-Antwort und dessen Wiederverwendung auf dieselbe Weise.
Wie bestätige ich, dass der globale Header tatsächlich gesendet wurde?
Senden Sie eine beliebige Anfrage und öffnen Sie dann die Registerkarte **Tatsächliche Anfrage** (Actual Request) in der Antwortkonsole. Sie zeigt die Anfrage so an, wie sie tatsächlich gesendet wurde, wobei {{token}} und andere Variablen bereits durch ihre Werte ersetzt sind. Wenn Ihr Header dort erscheint, wurde er über die Leitung gesendet.
Kann ich einen Standard-Header nur einem Ordner und nicht dem gesamten Projekt hinzufügen?
Ja, aber nicht über ein Einstellungsfeld, da Apidog keine native Ordner-Header-Benutzeroberfläche hat. Fügen Sie ein Pre-Request-Skript im Ordner hinzu, indem Sie pm.request.headers.add({ key, value }) verwenden, und jede Anfrage in diesem Ordner erbt den Header, während der Rest des Projekts dies nicht tut.
Benötige ich einen kostenpflichtigen Plan, um globale Parameter oder Umgebungsvariablen zu verwenden?
Die Dokumentation für diese Funktionen listet keine Stufenbeschränkung auf. Globale Parameter, Umgebungsvariablen und Pre-Request-Skripte auf Ordnerebene sind alle ohne eine Unterscheidung zwischen kostenlosen und kostenpflichtigen Funktionen dokumentiert.
Zusammenfassung
Das Festlegen eines Headers für jede Anfrage ist in Apidog eine einmalige Aufgabe: Definieren Sie den Header als globalen Parameter unter Umgebungsverwaltung (Environment Management), referenzieren Sie das Geheimnis als {{token}}-Variable, damit es nicht im Klartext vorliegt, und bestätigen Sie den Versand mit der Registerkarte „Tatsächliche Anfrage“ (Actual Request). Wenn Sie einen Header nur in einem Ordner benötigen, deckt dies der Pre-Request-Skript-Fallback ab. Um in Ihrem eigenen Projekt mitzumachen, laden Sie Apidog herunter und richten Sie Ihren ersten globalen Header ein. Es ist kostenlos, keine Kreditkarte erforderlich.