徹底解説 - Postman 変数 (Variables)

はじめに

こんにちは！Postmanの変数を使っていますか？
変数はとても強力な機能です。変数を理解することで、Postmanでの作業が効率的になるだけでなく、テストの柔軟性や拡張性が驚くほど向上します。変数を制すれば、Postmanを制すると言っても過言ではありません。

しかし、実際にはPostmanを使ったことがある人でも、変数の存在を知らない方や、まだ活用できていない方がいることがあります。これは非常にもったいないです。

この記事では、変数初めての人にとっても、既に使っている人にとっても、役立つようにPostmanの変数機能についてできるだけ網羅的に徹底解説したいと思います。

変数とは何か？

変数を使うことで、Postmanに値を保存して再利用することができます。APIテストの自動化やリクエストのパラメータ化ができ、同じリクエストを繰り返し行ったり、複数のリクエストで共通のデータを使用したりすることが容易になります。

変数は、{{変数名}} という形式で定義します。変数名は任意の文字列で、後で参照する際に使用されます。

変数の使い方

変数はクエリーパラメーターやパス変数、ヘッダー、ボディなど、ほぼリクエストに関連したほぼ全ての設定箇所で活用できます。

（１）リクエストURLの一部に対しての変数使用例（ここではベースURL）

（２）クエリーパラメータの変数使用例

（３）パス変数として使用例（ URL中で:orderIdのようにorderIdの前にコロンを付与することでそのパスをパス変数のキーとして値を指定できるようになる）

（４）リクエストボディでの変数使用例

（５）ヘッダーで変数使用例

なお、変数はスクリプトの中でも利用できます。後述の「スクリプト中で変数を使う」で解説するのでそちらを参照ください。

変数の基本：スコープ、変数タイプ、初期値/現在値

変数の種類と変数スコープ

変数には大きく次の5種類があり、それぞれ異なるスコープを持っています。

グローバル変数 (Global)
ワークスペース (Workspace)全体で共有される変数です。ワークスペース全体で共有できるため、あるコレクションのリクエストでセットした値を別のコレクションのリクエストで参照することが可能です。

コレクション変数 (Collection)
あるコレクションの中のリクエスト間で共有可能な変数です。

環境変数 (Environment)
異なる環境（Environment）間で共有できる変数です。ワークスペースやコレクションレベルでの設定ではなく、本番・ステージング・開発といった、サーバー環境ごとに異なるデータセットを活用したい場合に有効です。

データ変数 (Data)

Collection RunnerやNewman、Postman CLIでは、コレクション実行時に外部データファイル（CSVおよびJSONファイル）からのデータを活用したデータ駆動テストが可能です。この実行時にインポートされた取得されたデータはデータ変数としてPostmanのAPIリクエスト内で利用可能です。しかし、データ変数の値はコレクション実行後は、Postman内に保持されません。データ変数によるデータ駆動テストについては後述する「データファイル（CSV or JSON）から変数を読み込む」でより詳しく説明します。

ローカル変数 (Local)

ローカル変数は、スクリプト内からのみアクセス可能な一時的な変数です。ローカル変数のスコープは、Postmanで定義可能な変数の中で最も狭く、単一のリクエストまたはコレクションの実行にのみに限定されます。したがって、実行が完了するとその値は使用できなくなります。ローカル変数は、リクエスト実行中のスクリプト処理における一時変数として利用して、実行終了後は値を永続化したくない場合に適している変数です。

変数のスコープレベルの優先順位

スコープレベルの優先順位は、下記の順にの順番に小さくなり、もしそれぞれで設定した変数名が被っている場合は、スコープの小さい変数が優先されます。

スコープの優先順位

Global > Collection > Environment > Data > Local 

- Global: 最も広いスコープ
- Local : 最も狭いスコープ

例えば、下記イメージのように、グローバル、コレクション、環境変数全てにbaseUrlを設定している場合は、環境変数のbaseUrlの値が優先されます。

変数タイプ: デフォルト(Default)とシークレット(Secret)

Postmanでは、グローバル変数と環境変数に関しては、デフォルト(Default)とシークレット(Secret)の２種類の変数タイプを設定できます。

• デフォルトタイプ (Default): デフォルトタイプの変数は、入力した値がそのままのプレーンテキストで表示されます

• シークレットタイプ (Secret): シークレットタイプの変数は、デフォルトタイプと異なり入力した値をマスクして表示されます。よって、パスワード、秘密鍵、APIシークレットなど、表示上見られたくない情報に有効です。また、シークレットタイプの変数は、コレクションファイルをエクスポートする際に自動的に非表示になります

なお、変数の値がPostmanクラウド（AWS）に同期される際は、変数タイプに限らず、その値はAES-256-GCMで暗号化されて保存されます - Data Security

初期値(Initial Value)と現在値(Current Value)

Postmanでは、グローバル変数・コレクション変数・環境変数それぞれに「初期値（Initial Value）」 と 「現在値（Current Value）」 の2つの値を持つことができます。それぞれの役割は次の通りです。

• 初期値 (Initial Value):
  • Postmanクラウドと同期される値です
  • 他のメンバーとコレクションや環境を共有する際に共有されるのはこの初期値です
  • たとえば、ベースURLや共通ヘッダーのような共有しても問題のない情報は、初期値として設定しておくと便利です
• 現在値 (Current Value)
  • Postmanのアプリが実行時に参照するのは基本的にこの「現在値」です
  • ローカルにのみ保存され、クラウドには同期されません
  • パスワードやAPIキーなど、他人に見せたくない情報は、初期値には設定せず「現在値」だけに設定しておくのが安全です

変数の初期値と現在値のPostmanアプリからのアクセス対象と各値の保存場所については次のイメージが参考になります。

設定の方針としては、次の表のように共有の有無で使い分けましょう。初期値を空やプレースホルダー（例：<YOUR_API_KEY>）にすると、誤って共有してしまうリスクを防げます。

使いたい情報	初期値	現在値
ベースURLなど共有してよい情報	○	○
秘匿情報（APIキー、認証トークンなど）	×（空 or ダミー）	○

チーム内で使う変数は、「初期値＝共有用」「現在値＝実行用」と覚えるとわかりやすいです。

このように、何を共有したくて、何をローカルにとどめたいかを意識すると、Postmanの変数管理はぐっと安全で使いやすくなります。

変数を活用した秘匿情報の扱いについて

これまでに、変数のスコープ、変数タイプ(デフォルトとシークレット)、初期値と現在値の説明をしました。それでは変数でセキュリティトークン、パスワードなど秘匿情報を扱うにはどうすればよいでしょうか？ ポイントは3つあります。

（１）環境変数、もしくはグローバル変数として設定する
際は、環境変数、もしくはグローバル変数として設定してください。他にもコレクション変数があるがシークレットタイプが設定可能な環境、グローバル変数での設定が推奨されています

（２）各変数の初期値に秘匿情報を入力しない（現在値のみで利用する）
先述のとおり、初期値はPostmanクラウドに同期され、そのコレクションまたは環境にアクセス可能なユーザー（メンバー）に共有されます。一方、現在値はローカルにのみ保存され、誰にも共有されません。APIリクエスト送信で秘匿情報が必要な場合は、現在値にのみ入力して、初期値には入力しないでください

（３）変数タイプをシークレットにする
シークレットタイプとして設定された変数はマスクされて表示されるので、表示上見られたくない情報に有効です。ただし、言い方を変えると、シークレットタイプは表示上マスクされるだけであることに注意してください。

補足: Postmanにおける秘匿情報の扱いについて

Postmanにおける秘匿情報の扱い方については、２種類の方式を推奨してます。

方式1: 変数 (環境変数もしくはグローバル変数)の活用

上述のとおり秘匿情報を環境変数もしくはグローバル変数に格納して再利用する。

方式2: Postman Vaultの活用（オススメ⭐）

2024年5月前後に発表された新機能で、Postman Vaultと呼ばれるPostmanローカルインスタンスに格納する方式。

• Postman Vaultは機密データをPostmanのローカルインスタンスにのみ保存して再利用できる仕組みであり、データはPostman Vault内で暗号化され保存される
• Postman Vaultに保存したデータはPostmanクラウドには同期されない（共同作業者がVaultにシークレットの使用を防ぐ）
• デフォルトでPostman Vaultのシークレットはマスクされて表示される
• [注意] スクリプトからVaultシークレットを設定したりアクセスはできない

なお、Enterpriseプラン、かつAdvanced Security Administrationアドオンを購入することで外部Vaultインテグレーションの活用も可能。外部Vaultインテグレーションにより外部キー管理サービスに格納されたシークレット情報をPostman変数として利用が可能になる。サポートされている外部キー管理サービスに、1Password、AWS Secrets Manager、Azure Key Vault、HashiCorp Vaultなどがある。

変数の中身の確認と編集方法

マウスカーソルをホバーさせて変数閲覧

変数のところにマウスカーソルをホバーさせると次のように変数の中身を閲覧できます。

変数化したい値を選択して変数設定

変数化したい値を選択するとSet as variableがポップアップするので、そこから直接変数設定ができます。ここでは、パラメータqの値部分を選択しています。

Set as variableをクリックしてartistという変数名に値artist:yoasobiを環境変数(Spotifyという名前のEnvironment)として格納。

クイックルックページからグローバル・環境変数をまとめて閲覧、編集する

右サイドバーの一番に上にあるアイコン（下図の赤枠）をクリックすると、クイックルックページが表示されます。そこで、設定されている環境変数、グローバル変数をまとめて閲覧できます。また、環境変数、グローバル変数ともに右側のEditやAddをクリックすることでそれぞれの変数の編集ページに遷移します。そこでまとめて変数の編集ができます。

なお、コレクション変数については、上記のクイックルックアップではなく、各コレクションのトップメニューのVariablesで閲覧・編集ください。

スクリプト中で変数を使う

PostmanにはJavaScriptを用いたテストスクリプト（＊）を記述することができます。テストスクリプト内で変数を操作したり、レスポンスから値を抽出して変数に格納したりすることができます。なお、JavaScriptを用いたスクリプトでは、当然ながら変数の初期化、取得、スコープの定義は別の方法で行いますのでご注意ください。
（＊）スクリプトは、pre-requestとpost-responseというセクションで記述できます。詳しくはこちらのページを参照ください。

各変数の操作には次のようなメソッドが活用できます。

変数	操作メソッド
グローバル変数	pm.globals.<method>
コレクション変数	pm.collectionVariables.<method>
環境変数	pm.environment.<method>
データ変数	pm.iterationData.<method>
ローカル変数	pm.variables.<method> (＊)

変数操作例

// グローバル変数設定
pm.globals.set("variable_key", "variable_value");
// コレクション変数設定
pm.collectionVariables.set("variable_key", "variable_value");

// 選択している環境に環境変数を設定
pm.environment.set("variable_key", "variable_value");
// 選択している環境の環境変数の値を取得
console.log(pm.environment.get("variable_key")); 
// 選択している環境に指定された名前の変数があるかどうかを確認
if (pm.environment.has("variable_key")) {
    console.log("your environemnt has a variable named variable_key")
}
// 選択している環境の環境変数をアンセットする
pm.environment.unset("variable_key");

// ローカル変数（そのリクエストレベルでのみ有効）を設定
pm.variables.set("variable_key", "variable_value");

各変数タイプで利用可能なメソッドの詳細について詳しくは Defining variables in scripts を参照ください。

(＊) pm.variables
pm.variablesはスコープが最も狭い変数の値でオーバーライドします。例えば、現在のコレクションとアクティブな（選択している）環境の両方にscore変数があり、pm.variables.get('score')を呼び出すと、Postmanは環境変数の現在の値を返します。 pm.variables.setを使用して変数の値を設定すると、その値はローカルとなり、現在のリクエストまたはコレクションの実行中のみ保持されます。

// コレクション（collection）変数 'score'の値: 1
// 環境（environment）変数 'score'の値: 2

// リクエスト実行１回目
console.log(pm.variables.get('score')); // 出力結果 2（スコープの狭い環境でオーバーライド）
console.log(pm.collectionVariables.get('score')); // 出力結果 1
console.log(pm.environment.get('score')); // 出力結果 2

// リクエスト実行２回目
pm.variables.set('score', 3);    // ローカル変数 'score'にセット
console.log(pm.variables.get('score')); // 出力結果 3

// リクエスト実行３回目
console.log(pm.variables.get('score')); // 出力結果 2
// リクエスト実行２回目で３に設定したが、それは２回目リクエスト実行中にのみ保持され
// 永続化されない。したがって、３回目のリクエスト実行時は２が出力

それでは、送信したリクエストのレスポンスボディ内容を元に、環境変数設定してみます。次の例では、レスポンスボディにあるidフィールドを取得して環境変数にキーvalidPetIdの値として設定しています。このようにあるリクエストで得られた結果を環境変数に格納することで、別のリクエストでその値を元に処理するといったリクエスト間の連携が可能になります。

データファイル（CSV or JSON）から変数を読み込む

変数を使ってデータ駆動テストを行うことも可能です。Postman CLIやNewman、またはコレクションRunnerを実行するときに、CSVファイルやJSONファイルからデータを読み込み、そのデータを元に複数のテストケースを自動化することができます。

例えば、次のようなCityとRamenという名前のパラメータ変数を設定したリクエストがあるとします。

このリクエストが設定されているコレクションのコレクションRunnerページにて、CityとRamenのフィールドを持ったCSVファイルを選択することでファイル中に記述されているデータが変数に注入されテストが実行されます。

なお、テストスクリプトでは、データファイルからのデータを次のメソッドで読み込むことができます。

pm.iterationData.get("variable_key")

上述の通り、Postman CLIやNewmanなどコマンドラインインターフェイスからの実行においてもデータファイルの読み込みは可能です。CI/CD経由で、複数データパターンで自動テストする際にはとても有効です。

ダイナミック変数

Postmanには、乱数やタイムスタンプなどの動的な値を生成してくれるダイナミック変数という定義済みの変数が用意されています。内部的にはFakerライブラリを活用しており、ランダムなサンプルデータを生成してくれます。これにより、テストの再現性を確保しつつ、毎回異なるデータでテストを実行できたりします。

• {{$guid}} : v4スタイルのGUID
• {{$timestamp}}：現在のUnixタイムスタンプ（秒単位
• {{$randomInt}}：0 から 1000 までのランダムな整数

例えば、固定ではなくラインダムで生成した文字列を設定したい場合は、変数として下記のようなダイナミック変数を指定することで、36文字のUUID文字列（例: "6929bb52-3ab2-448a-9796-d6480ecad36b"）が取得できます。

{{$randomInt}}

他にもさまざまなダイナミック変数が用意されています。詳しくはこちらのページを参照ください。

おわりに

少々長くなりましたがPostmanの変数機能について紹介しました。本記事を読むことで、変数を活用したPostmanの新たな可能性に気付いていただのではないでしょうか？
変数は、Postmanの活用において最も基本的で重要な機能です。繰り返しになりますが、変数を使いこなせば、Postmanを制することができると言っても過言ではありません。是非、変数を活用し、より効果的なAPIテスト・開発を実施いただけたらと思います。

Have a happy API testing with Postman!