徹底解説 - Postman 変数 (Variables)

はじめに

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

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

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

変数とは何か？

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

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

変数の使い方

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

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

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

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

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

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

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

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

変数スコープ

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

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

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

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

スコープレベルの優先順位について、グローバル ＞ コレクション ＞ 環境変数の順番に小さくなり、もしそれぞれで設定した変数名が被っている場合は、スコープの小さい変数が優先されます。下記イメージのように、グローバル、コレクション、環境変数全てにbaseUrlを設定している場合は、環境変数のbaseUrlの値が優先されます。

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

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

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

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

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

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

グローバル、コレクション、環境変数にはそれぞれ初期値(Initial Value)と現在値(Current Value)が存在します。

• 初期値(Initial Value) のデータはPostmanクラウドに同期されます。そして、コレクションや環境変数を共有する際には初期値が共有されます（現在値は自分のローカルインスタンスにのみ保持される）
• 現在値(Current Value) は、自分のローカルインスタンスにのみ保持される変数で、Postmanクラウドには同期されません。また、コレクションや環境変数を共有した際にも現在値は共有されません。初期値と現在値の両方があったとしても、実際にアプリ内での変数の参照で活用されるのは現在値です。一人でテストするのであれば、現在値だけでよいですが、共有したい場合は初期値を意識するようにしましょう

これは、変数の初期値と現在値の保存場所を表したイメージです。

一部再掲となるが、ポイントをまとめると：

• 初期値はPostmanクラウドに同期され、現在値は自分のローカルインスタンスにのみ保持される
• 実際にアプリ内での変数の参照で活用されるのは現在値
• Postmanクラウドにおいては初期値と現在値は同じ値で保存される。これは、ローカルから同期された初期値が現在値にコピーされるため（デフォルトの挙動として、保存時に現在値が空の場合、初期値の値がコピーされる）
  • コレクションのスケジュール実行や、モニターからのコレクション実行は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とtestというセクションで記述できます。詳しくはこちらのページを参照ください。

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

// グローバル変数設定
pm.globals.set("variable_key", "variable_value");
// コレクション変数設定
pm.collectionVariables.set("variable_key", "variable_value");
// 選択している環境に環境変数を設定
pm.environment.set("variable_key", "variable_value");
// ローカル変数（そのリクエストレベルでのみ有効）を設定
pm.variables.set("variable_key", "variable_value");
// 選択している環境の環境変数をアンセットする
pm.environment.unset("variable_key");

ref: Defining variables in scripts

それでは、送信したリクエストのレスポンスボディ内容を元に、環境変数設定してみます。次の例では、レスポンスボディにある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!