DEV Community

Cover image for Apidog グローバルパラメータ設定: 全リクエストに認証ヘッダーを自動付与する方法
Akira
Akira

Posted on • Originally published at apidog.com

Apidog グローバルパラメータ設定: 全リクエストに認証ヘッダーを自動付与する方法

プロジェクトに40個のエンドポイントがあり、すべての呼び出しで Authorization: Bearer ... と X-Api-Version が必要な場合、各リクエストへ手動でヘッダーを追加する運用はすぐに破綻します。設定漏れによる401エラーや、エンドポイントごとの値のばらつきを避けるには、共通ヘッダーを一元管理する必要があります。

今すぐApidogを試す

Apidog では、プロジェクトレベルのグローバルパラメーター、環境変数、フォルダーレベルのプリリクエストスクリプトを使って、ヘッダーを一度定義し、複数のリクエストへ自動適用できます。

この記事では、次の構成を実装します。

  • Authorization: Bearer {{token}} を全リクエストへ適用する
  • X-Api-Version: 2024-08-01 を共通ヘッダーとして適用する
  • トークンを変数として管理し、環境ごとに切り替える
  • 実際に送信されたリクエストでヘッダーを検証する
  • 特定フォルダーだけにヘッダーを付与する

変数の基本から確認したい場合は、Apidog で変数をマスターする も参照してください。

共通ヘッダーという考え方自体はApidog固有ではありません。MDN HTTPヘッダーリファレンスで説明されているように、HTTPリクエストには毎回送信するキー・バリューの組み合わせがあります。Apidogでは、その定義を各リクエストに複製せず、一箇所で管理できます。

「グローバルパラメーター」とは

Apidogのグローバルパラメーターは、個別エンドポイントではなくプロジェクト全体に適用されるリクエストパラメーターです。一度設定すると、対象のリクエストへ自動的に追加されます。

設定できる場所は4種類です。

  • ヘッダー: Authorization、X-Api-Version など
  • クッキー: セッションCookieなど
  • クエリ: ?api_key= のようなURLクエリパラメーター
  • ボディ: すべてのリクエストボディに必要なフィールド

認証やAPIバージョンを共通化する場合は、ヘッダーを使用します。

グローバルパラメーターは、エンドポイントレベルのパラメーターより優先度が低くなります。

たとえば特定リクエストに独自の Authorization ヘッダーがある場合、その値が優先されます。

つまり、グローバルパラメーターは「プロジェクト全体のデフォルト」です。例外的なルートだけ個別設定で上書きできます。

すべてのリクエストにグローバルヘッダーを設定する

ここでは、個別エンドポイントを編集せずに Authorization と X-Api-Version を適用します。

ステップ1: 環境管理を開く

Apidogの右上から環境管理を開きます。

グローバルパラメーターはここで管理します。Apidogドキュメントでは、すべてのリクエストとともに送信する値を定義する場所として説明されています。

ステップ2: ヘッダーを選択する

認証ヘッダーを追加するため、パラメーターの場所としてヘッダーを選択します。

Cookie、クエリ、ボディを共通化したい場合も、同じ画面から対応する場所を選択できます。

ステップ3: Authorization を追加する

最初に、ベアラートークン用のグローバルヘッダーを追加します。

項目 値
名前 Authorization
タイプ 文字列
デフォルト値 Bearer {{token}}
説明 すべての認証済みエンドポイント用のベアラートークン

{{token}} は変数参照です。トークンを直接書かず、後ほど環境変数として定義します。

ステップ4: X-Api-Version を追加する

次に、APIバージョン用のヘッダーを追加します。

項目 値
名前 X-Api-Version
タイプ 文字列
デフォルト値 2024-08-01
説明 すべてのリクエストに固定されたAPIバージョン

ステップ5: パラメーターを有効化して保存する

各パラメーターの有効/無効スイッチをオンにし、設定を保存します。

これで、個別リクエストに同名ヘッダーが定義されていない限り、プロジェクト内のすべてのリクエストへ以下が追加されます。

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

ステップ6: 実際に送信されたヘッダーを確認する

設定後は、必ず送信内容を確認します。

  1. プロジェクト内の任意のリクエストを送信する
  2. 応答コンソールの実際の要求タブを開く
  3. Authorization と X-Api-Version が含まれることを確認する

確認例:

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

「実際の要求」には、{{token}} のような変数が解決された後のリクエストが表示されます。ここにヘッダーがあれば、実際に送信されています。

ヘッダーにシークレットを書かない: 変数を使用する

Authorization の値には、次のようにトークンを直接書かないでください。

Bearer sk_live_7f3a9c2e1b8d4056
Enter fullscreen mode Exit fullscreen mode

代わりに変数を使います。

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Bearer スキームは RFC 6750 で定義されており、MDN Authorization ヘッダーリファレンスではHTTPヘッダーでの利用方法を確認できます。

token 変数を作成する

  1. 右上の環境アイコン（≡）をクリックする
  2. グローバル変数セクションを開く
  3. 変数名 token を追加する
  4. 値にベアラートークンを設定する
  5. 保存する

これで、送信時に次のように解決されます。

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode 
Bearer <実際のシークレット>
Enter fullscreen mode Exit fullscreen mode

推奨パターンは次のとおりです。

  • グローバルパラメーター: Authorization ヘッダーの構造を管理する
  • 環境変数またはグローバル変数: トークンなどのシークレットを管理する

シークレットと環境の管理については、APIクライアントの環境とシークレット管理も参照してください。

環境ごとにトークンを切り替える

開発、テスト、本番では、通常異なるトークンを使います。

たとえば、環境ごとに同じ変数名 token を定義します。

環境 token の値
Development 開発用トークン
Staging テスト用トークン
Production 本番用トークン

環境ドロップダウンから対象環境を選択すると、グローバルヘッダーの記述を変えずに、解決されるトークンだけを切り替えられます。

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

認証方式を含めた設計を確認したい場合は、セキュリティスキームガイドを参照してください。

特定フォルダーだけにヘッダーを適用する

グローバルパラメーターはプロジェクト全体へ適用されます。しかし、以下のように一部のAPIだけ追加ヘッダーが必要なケースもあります。

/admin/* だけ X-Admin-Scope: full が必要
Enter fullscreen mode Exit fullscreen mode

Apidogには、フォルダー設定に専用の「ヘッダー追加」UIはありません。この場合は、フォルダーレベルのプリリクエストスクリプトを使います。

フォルダーのプリリクエストスクリプトに以下を追加してください。

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

このフォルダー配下のリクエストだけに、次のヘッダーが付与されます。

X-Admin-Scope: full
Enter fullscreen mode Exit fullscreen mode

プロジェクト全体に適用したいヘッダーにはグローバルパラメーターを使い、フォルダー限定の要件にはプリリクエストスクリプトを使うと管理しやすくなります。

スクリプトの詳細は、Apidog におけるプリリクエストスクリプトとポストリクエストスクリプトの使用方法を参照してください。

どの機能を使うべきか

要件 使用する機能
全リクエストに共通ヘッダーを付ける グローバルパラメーター
トークンを平文でヘッダー定義に書かない 環境変数またはグローバル変数
開発・テスト・本番でトークンを切り替える 環境変数
特定フォルダーだけにヘッダーを付ける フォルダーレベルのプリリクエストスクリプト
一部エンドポイントだけ別の認証情報を使う エンドポイントレベルのヘッダー設定

運用時は、次の点を確認してください。

  • 同名のグローバルヘッダーを重複定義しない
  • パラメーターの型と用途を一致させる
  • エンドポイントレベルのヘッダーがグローバル設定を上書きすることを理解する
  • 実行後に「実際の要求」タブで送信内容を検証する

Apidog CLIでワークフローを自動化する

グローバルパラメーターと環境変数は、GUIでの手動実行だけでなく、Apidog CLIを使う自動実行にも引き継がれます。

まずCLIをインストールし、ログインします。

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

次に、環境を指定して保存済みシナリオを実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

主要なオプションは以下です。

オプション 用途
-t テストシナリオID
-e 実行する環境ID
-r レポーター。cli、html、junit を指定可能

-e で環境を指定すると、その環境の変数値が利用されます。そのため、GUIで定義した Bearer {{token}} と X-Api-Version の設定を、CI実行でも同じように利用できます。

セットアップの詳細はApidog CLIインストールガイド、CIへの組み込みはGitHub Actions での Apidog CLIを参照してください。

FAQ

グローバルパラメーターは個別エンドポイントのヘッダーを上書きしますか？

いいえ。グローバルパラメーターはエンドポイントレベルのパラメーターより優先度が低くなります。

特定リクエストに Authorization が定義されている場合、そのリクエストの値が使われます。グローバルパラメーターは、個別設定がない場合のデフォルトとして機能します。

実際のトークンはどこに保存すべきですか？

生のデフォルト値ではなく、環境変数またはグローバル変数に保存してください。

グローバルヘッダーは次のように設定します。

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

実際のシークレットは token 変数に保持します。ログインレスポンスからトークンを取得して再利用する方法は、JSONPath を使用した変数の抽出で確認できます。

グローバルヘッダーが送信されたことを確認する方法は？

任意のリクエストを送信し、応答コンソールの実際の要求タブを開いてください。

変数が解決された状態の送信済みリクエストが表示されます。そこに対象ヘッダーがあれば、送信されています。

プロジェクト全体ではなく、1つのフォルダーだけにヘッダーを追加できますか？

はい。フォルダーのプリリクエストスクリプトを使います。

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

このスクリプトは、そのフォルダー内のリクエストにのみ適用されます。

グローバルパラメーターや環境変数に有料プランは必要ですか？

これらの機能に関するドキュメントには、ティア制限は記載されていません。グローバルパラメーター、環境変数、フォルダーレベルのプリリクエストスクリプトはいずれもドキュメントに記載されています。

まとめ

Apidogで共通ヘッダーを管理する手順は次のとおりです。

  1. 環境管理でヘッダーをグローバルパラメーターとして追加する
  2. Authorization は Bearer {{token}} として設定する
  3. シークレットは環境変数またはグローバル変数に保存する
  4. 「実際の要求」タブで送信済みヘッダーを確認する
  5. フォルダー限定の要件にはプリリクエストスクリプトを使う

まずはApidogをダウンロードし、プロジェクトの共通ヘッダーを1つ設定して、個別リクエストの重複設定を減らしてみてください。

Top comments (0)