プロジェクトに40個のエンドポイントがあり、そのすべてが、呼び出しごとに同じ Authorization: Bearer ... ヘッダーと X-Api-Version ヘッダーを必要とします。これらの2行を各リクエストに手動で追加するのは時間がかかり、さらに悪いことに、ばらつきが生じます。あるエンドポイントはトークンを取得し、別のエンドポイントは忘れられ、40個のルートのうち3つにしか表示されない401エラーを追いかけるのに午後を費やしてしまいます。
もっと良い方法があります。Apidog を使えば、パラメーターを一度定義するだけで、すべてのリクエストに自動的に適用できます。ヘッダーをプロジェクトレベルで設定し、トークンを変数として参照すれば、1つのリクエストも変更することなく、すべてのエンドポイントがそれを継承します。このガイドでは、そのための3つの方法、つまりグローバルパラメーター、環境変数、およびフォルダー範囲スクリプトのフォールバックについて説明します。認証ヘッダーとバージョンヘッダーをすべてにアタッチし、さらにヘッダーが実際に送信されたことを確認する方法を備えた動作中のセットアップで完了します。まず変数についてさらに深く知りたい場合は、Apidog で変数をマスターする ガイドがこのガイドとよく合います。
すべての呼び出しで標準ヘッダーを保持するリクエストのアイデアは、Apidogに固有のものではありません。MDN HTTPヘッダーリファレンスが説明するのと同じパターンです。つまり、各リクエストとともに送られる少数のキー/値ペアのセットです。Apidogの役割は、そのセットを一度だけ設定できるようにすることです。
「グローバルパラメーター」が実際に意味するもの
Apidogにおけるグローバルパラメーターとは、単一のエンドポイントではなくプロジェクト全体に適用されるリクエストパラメーターです。一度定義すれば、Apidogはそれを一致するリクエストに自動的にアタッチします。
グローバルパラメーターは4つの場所をカバーしており、これがこの機能全体の鍵となります。
- ヘッダー（リクエストヘッダー）：
AuthorizationやX-Api-Versionなどの項目用。 - クッキー（クッキー情報）：セッションクッキー用。
- クエリ（URLクエリパラメーター）：すべてのURLに追加される
?api_key=のような値用。 - ボディ（リクエストボディパラメーター）：すべてのリクエストボディが持つべきフィールド用。
認証ヘッダーのユースケースでは、「ヘッダー」を使用します。標準値がクッキー、クエリ文字列、またはボディフィールドにある場合も、他の3つは同じように機能します。
開始する前に重要なルールが1つあります。グローバルパラメーターは、エンドポイントレベルで定義されたパラメーターよりも優先順位が低いです。特定のリクエストがすでに独自の `Authorization` ヘッダーを設定している場合、そのエンドポイントレベルの値が優先され、グローバルパラメーターは脇に追いやられます。グローバルパラメーターは、エンドポイントがそれ自体を設定していない場合に埋められるデフォルト値として考え、すべてを上書きする強力なオーバーライドではないと理解してください。この優先順位があるからこそ、大規模なプロジェクト全体でグローバルパラメーターを安全に有効にできるのです。
すべてのリクエストにグローバルヘッダーを設定する
ここでは、主要な手順を説明します。目標は、プロジェクト内のすべてのエンドポイントに `Authorization` と `X-Api-Version` を、それらのいずれも編集することなくアタッチすることです。
ステップ1: 環境管理を開く
グローバルパラメーターは環境管理内にあり、ページ右上から開くことができます。これはプロジェクト全体に適用されるパラメーターのエントリーポイントであり、Apidog ドキュメントでは、すべてのリクエストとともに送られる値の保管場所として説明されています。それを開くと、場所ごとにパラメーターを追加するセクションが表示されます。
ステップ2: ヘッダーの場所を選択する
認証ヘッダーを追加するので、ヘッダー（リクエストヘッダーの場所）を選択します。標準値がクッキー、クエリパラメーター、またはボディフィールドである場合は、代わりにクッキー、クエリ、またはボディを選択します。仕組みは4つすべてで同じです。
ステップ3: パラメーターの詳細を入力する
各グローバルパラメーターには固定のプロパティセットがあります。最初のヘッダーにそれらを入力します。
- 名前:
Authorization - タイプ: パラメーターのタイプ（ヘッダー値の場合は文字列）。
- デフォルト値:
Bearer {{token}}（{{token}}の部分については下記を参照）。 - 説明: 「すべての認証済みエンドポイント用のベアラートークン」のような短いメモ。
必須パラメーターには、Default フィールドと必須マーカー（アスタリスク *）も表示されます。バージョンヘッダーについても同様に2行目を追加します。
- 名前:
X-Api-Version - タイプ: 文字列
- デフォルト値:
2024-08-01 - 説明: 「すべてのリクエストに固定されたAPIバージョン。」
ステップ4: パラメーターをオンに切り替える
各パラメーターには、右側に有効/無効スイッチがあります。これをオンにしてパラメーターをアクティブにします。この切り替えは後で便利です。デバッグセッションのためにグローバルヘッダーを一時的に無効にする必要がある場合、それを削除して全体を再入力するのではなく、ここで無効にすることができます。
ステップ5: 保存する
設定を保存します。これで両方のヘッダーがグローバルになりました。特定のいずれかのエンドポイントがそれらを上書きしない限り、プロジェクト内のすべてのリクエストは `Authorization` と `X-Api-Version` を保持します。
ステップ6: 実際に送信されたことを確認する
動作したことを鵜呑みにせず、確認してください。プロジェクト内の任意のリクエストを送信し、応答コンソールの実際の要求タブを開きます。このタブには、変数が実際の値に置き換えられた、送信されたとおりのリクエストが正確に表示されます。両方のヘッダーがそこにリストされているはずです。
GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
ヘッダーが「実際の要求」に表示されれば、実際に送信されたことになります。これは設定全体の中で最も役立つ確認であり、「適用されていると思う」が「適用されているのが見える」に変わる瞬間です。
ヘッダーからシークレットを隠す：変数を使用する
上記のデフォルト値が `Bearer sk_live_7f3a9c2e1b8d4056` ではなく `Bearer {{token}}` であったことに注目してください。この二重波括弧の構文は、生のトークンをパラメーターにハードコーディングするのではなく、変数を参照しています。`Bearer` スキーム自体は RFC 6750 で定義されており、MDN Authorization ヘッダーリファレンスではサーバーがそれをどのように読み取るかを説明しています。Apidog のドキュメントでは、セキュリティの観点から明確に述べられています。認証トークンやAPIキーのような機密データには、生の値を平文のデフォルト値として保存するのではなく、環境変数を使用してください。変数は、多くのリクエストやスクリプトで使う値の動的なプレースホルダーであり、シークレットをパラメーター定義から分離します。
`token` 変数を設定する方法は次のとおりです。
- 右上にある環境アイコン（
≡アイコン）をクリックします。これは環境管理とは異なるエントリーポイントであることに注意してください。≡アイコンは変数が存在する場所です。 - グローバル変数セクションを見つけます。
- 例えば、あなたのベアラーシークレットの値を持つ
tokenという変数を作成します。 - 保存をクリックします。
これで、グローバルヘッダー値 `Bearer {{token}}` は送信時に `Bearer <あなたの実際のシークレット>` に解決され、「実際の要求」タブで置換が確認されます。どこでも変数名にマウスカーソルを合わせると、現在の値とスコープが表示され、正しい変数を参照しているかを素早く確認できます。
この組み合わせが推奨されるパターンです。グローバルパラメーターがヘッダーのスロットを所有し、変数がシークレットを所有します。APIクライアントの環境とシークレット管理に関する詳細なガイドでは、共有したりコミットしたりする可能性のあるものからトークンをどのように遠ざけるかについてさらに深く掘り下げています。
環境ごとに値を切り替える
変数は、複数ある場合にさらに便利になります。実際のプロジェクトでは、開発、テスト、本番用に異なるサーバーにアクセスし、それぞれが通常異なるトークンを必要とします。各セットを独自の環境にグループ化し、≡ アイコンの隣にある環境ドロップダウンでそれらを切り替えます（サンプルの環境は Local Mock と名付けられているかもしれません）。環境を切り替えると、リクエストが異なるサーバーセットに向けられ、その環境の変数値に置き換わります。グローバルな `Bearer {{token}}` ヘッダーは同じままですが、解決されるシークレットだけが環境によって変わります。この上に認証フローを構築する場合、セキュリティスキームガイドの概念は、ベアラー、APIキー、OAuthの定義が実際のリクエストにどのようにマッピングされるかを説明しています。
ヘッダーを1つのフォルダーにのみ適用したい場合
グローバルパラメーターはプロジェクト全体に影響します。しかし、時にはそれは広すぎることがあります。たとえば、/admin エンドポイントだけが X-Admin-Scope ヘッダーを必要とし、プロジェクトの残りの部分はそれを保持すべきではない場合です。
ここに正直な制約があります。Apidogには、フォルダー設定にネイティブな「ヘッダーを追加」フィールドがありません。フォルダーレベルで入力するヘッダーUIがないのです。その代わりにドキュメントが説明しているのは、フォルダーレベルでプリリクエストスクリプトを使用する回避策であり、そのフォルダー内のすべてのリクエストがヘッダーを継承します。このスクリプトはPostman互換の `pm.*` スクリプティングを使用します。
pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });
これをフォルダーのプリリクエストスクリプトとして追加すると、そのフォルダー内のすべてのリクエストはヘッダーを取得し、フォルダー外のリクエストは取得しません。これは設定トグルではなくスクリプトであるため、主要な方法ではなく、フォルダー範囲のニーズに対する意図的なフォールバックとして扱ってください。このスクリプトモデルのより広範な背景については、Apidog におけるプリリクエストスクリプトとポストリクエストスクリプトの使用方法に関するガイドを参照してください。
どの機能と、いつ使用するか
エンドポイントを編集することなくヘッダーをアタッチする方法が3つできました。スコープによって選択してください。
- グローバルパラメーター（ヘッダー）：環境管理経由で、ヘッダーがプロジェクト全体に適用されます。これは、共有の認証ヘッダーやバージョンヘッダーのデフォルトとして使用します。
- 環境変数（
{{token}}）：グローバルパラメーターと組み合わせて使用し、ヘッダーのスロットはグローバルにしつつ、シークレットは安全に保存され、環境ごとに切り替わるようにします。 - フォルダーレベルのプリリクエストスクリプト（
pm.request.headers.add）：ヘッダーは1つのフォルダーにのみ適用されます。プロジェクト全体に適用するには広すぎる場合にこれを使用します。
注意すべき点がいくつかあります。2つのグローバルヘッダーが衝突しないように、重複するパラメーター名がないか確認し、各パラメーターのタイプがその使用方法と一致していることを確認してください。また、優先順位のルールを覚えておいてください。独自の `Authorization` を設定するエンドポイントは、グローバルなものを上書きします。これは、あるルートが異なるトークンを必要とする場合には機能ですが、そのルートが独自の値を設定していたことを忘れていると驚きとなるでしょう。これら3つの機能のいずれもドキュメントでプランの制限が記載されていないため、使用するために特定のティアは必要ありません。
Apidog CLIでワークフローを自動化する
グローバルパラメーターと環境は、GUIの利便性だけでなく、自動化された実行にも引き継がれます。Apidogで保存されたテストシナリオを構築し、コマンドラインから実行すると、その実行はIDで渡された環境を継承するため、GUIで機能した `Bearer {{token}}` ヘッダーと `X-Api-Version` の値は、CIでも同じように解決されます。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
次に、特定の環境に対して保存されたシナリオを実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
-e フラグは環境を選択するため、シナリオはその環境の変数（トークンを含む）を取得します。-t フラグはテストシナリオIDで、-r はレポーター（cli、html、または junit）です。これが連携のポイントです。ヘッダーと変数を一度定義すれば、CLI経由で実行されるすべてのシナリオがそれらを保持します。セットアップとトークンの詳細については、Apidog CLIインストールガイドを参照してください。自動化に実行を組み込むには、GitHub Actions での Apidog CLI のチュートリアルで完全なパイプラインが示されています。
FAQ
グローバルパラメーターは、特定のエンドポイントで設定したヘッダーを上書きしますか？
いいえ。グローバルパラメーターはエンドポイントレベルのパラメーターよりも優先度が低いです。リクエストが独自の Authorization ヘッダーを定義している場合、その値が優先され、グローバルパラメーターはそのリクエストでは無視されます。グローバルはプロジェクトのデフォルトとして機能し、エンドポイントが独自の値を設定していない場所を埋めます。
実際のトークンを平文で保存しないためには、どこに保管すべきですか？
生のデフォルト値ではなく、環境変数またはグローバル変数を使用してください。グローバルヘッダーを `Bearer {{token}}` に設定し、実際のシークレットは ≡ 環境アイコンを通じて作成された変数に保持します。ドキュメントでは、トークンがインラインで保存されないように、機密データには変数または安全な方法を使用することを特に推奨しています。JSONPath を使用した変数の抽出に関するガイドでは、ログイン応答からトークンをキャプチャし、同じ方法で再利用する方法について説明しています。
グローバルヘッダーが実際に送信されたことを確認するにはどうすればよいですか？
任意のリクエストを送信し、応答コンソールの実際の要求タブを開きます。そこには、{{token}} および他の変数がすでにそれぞれの値に置き換えられた、実際に送信されたリクエストが表示されます。そこにヘッダーが表示されていれば、それが送信されたことになります。
プロジェクト全体ではなく、1つのフォルダーにのみデフォルトヘッダーを追加できますか？
はい、可能です。ただし、ApidogにはネイティブのフォルダーヘッダーUIがないため、設定フィールドを介してはできません。フォルダーに pm.request.headers.add({ key, value }) を使用してプリリクエストスクリプトを追加すると、そのフォルダー内のすべてのリクエストはヘッダーを継承しますが、プロジェクトの残りの部分には適用されません。
グローバルパラメーターや環境変数を使用するには、有料プランが必要ですか？
これらの機能に関するドキュメントには、ティアの制限は記載されていません。グローバルパラメーター、環境変数、フォルダーレベルのプリリクエストスクリプトはすべて、無料版と有料版の区別なくドキュメントに記載されています。
まとめ
Apidogで、すべてのリクエストにヘッダーを設定するのは一度の作業です。環境管理下でヘッダーをグローバルパラメーターとして定義し、シークレットをプレーンテキストに残さないように {{token}} 変数として参照し、「実際の要求」タブで送信されたことを確認します。1つのフォルダーにのみヘッダーが必要な場合は、プリリクエストスクリプトのフォールバックで対応できます。ご自身のプロジェクトで試すには、Apidog をダウンロードして最初のグローバルヘッダーを設定してください。無料で、クレジットカードは不要です。