徹底解説 - Postman 変数 (Variables)

はじめに

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

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

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

Postman変数の編集画面がシンプルになりました（2025年9月10日）

2025年9月10日リリースのPostman 11.62.5で、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:最も広いスコープ、Local:最も狭いスコープ）。

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

変数の設定

変数の編集画面では、各変数値に対して次の3つの設定が可能です。

• 説明設定: 各変数についての説明をペンマークをクリックして入力
• 共有設定: 後述の「変数の共有設定」で解説　
• センシティブ設定: 後述の「変数のセンシティブ設定」で解説（グローバル変数および環境変数のみ）

変数の共有設定

変数の値は、デフォルトではローカルにのみ保存され、クラウドには同期されません。しかし、この値をクラウドに同期することで、チームメンバーと共有できます。

変数の値カラムにマウスをホバーさせると雲のマークが表示されます。これは変数の共有設定を意味し、このマークをクリックすると変数の値がPostmanクラウドに同期されます。この同期された値を共有値と呼びます。

なお、一度値が共有された後、ローカルでその変数の値を変更しても、共有値には影響しません。共有値を更新したい場合は、再度雲のマークをクリックして表示されるメニューの「Update shared value」を選択する必要があります。なお、「Reset value」をクリックすることで、ローカル値を共有値にリセットさせることも可能です。また、共有を解除（Unshare）することもできます。

変数のセンシティブ設定

変数の編集画面で、変数に値を入力すると、デフォルトでは、入力した値がそのままのプレーンテキストで表示されます。ただし、変数にセンシティブ設定すると、変数値はマスク表示されるようになります。
パスワード、秘密鍵、APIシークレットなど、表示上見られたくない情報に有効です。また、シークレットタイプの変数は、コレクションファイルをエクスポートする際に自動的に非表示になります。
各変数にマウスカーソルを合わせると変数名の右側にボタンが現れます。ボタンをクリックするとオン・オフが切り替わり、オンの状態ではセンシティブマークが常に表示される状態になります。

センシティブ設定における注意点

• センシティブ設定は、グローバル変数と環境変数のみで利用可能です
• 変数の値はセンシティブ設定オン・オフに限らず、Postmanクラウドに同期されるデータの値はAES-256-GCMで暗号化されて保存されます - Data Security

秘匿情報の扱い方について

Postmanにおけるパスワード、秘密鍵、APIシークレットなどの秘匿情報の扱い方については、次の2種類の方式を推奨してます。

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

秘匿情報を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などがある。

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

秘匿情報を環境変数もしくはグローバル変数に格納して再利用する方式です。この方式のポイントは次の2つです。

変数の値を共有しない（共有設定を行わない）

先述のとおり、変数の値は、デフォルトではローカルにのみ保存され、クラウドには同期されません。したがって、共有設定しない限り、この値は誰にも共有されません。APIリクエスト送信で秘匿情報が必要な場合は、その変数値に共有設定をしないことを推奨します。

変数のセンシティブ設定をオンにする

先述の通り、センシティブ設定をオンにした変数はマスクされて表示されるので、表示上見られたくない情報に有効です。

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

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

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

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

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

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

変数ペインから変数をまとめて閲覧、編集する

右サイドバーの一番に上にある変数ペイン (Variables Pane)のアイコン（下図の赤枠）をクリックすると、その時点で使用しているPostman要素（たとえば、APIリクエスト）からアクセスできる全ての変数（環境変数、コレクション、グローバル変数やVaultシークレット）が表示されます。また、表示だけではなく、それらの変数をまとめて編集ができます。

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

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!