Apidog 変数理解と習得

変数を使用すると、値に名前を付けて、必要な場所ならどこでも再利用できます。

例えば、頻繁に変わるAPIトークンをすべてのリクエストに貼り付ける代わりに、ACCESS_TOKENのような変数を定義し、リクエストで{{ACCESS_TOKEN}}を使用します。トークンの有効期限が切れたら、変数を一度更新するだけで、それを使用するすべてのリクエストが自動的に新しい値を取得します。

変数の種類概要

Apidogは、特定のシナリオに合わせて設計されたいくつかの変数タイプをサポートしています。チームレベルのグローバル変数、プロジェクトレベルのグローバル変数、モジュール変数、環境変数、テストデータ変数、ローカル変数を使用できます。

グローバル変数

グローバル変数を使用すると、データを広範囲に共有できます。これには2種類あります。

プロジェクトレベルのグローバル変数: 現在のプロジェクトに限定されます。同じプロジェクト内のリクエスト間でデータを渡すのに最適です。例えば、ログインエンドポイントから取得したトークンをプロジェクトレベルのグローバル変数として保存し、そのプロジェクト内の他のリクエストで再利用します。

チームレベルのグローバル変数: チーム内のすべてのプロジェクトで共有されます。プロジェクト間の共同作業に最適です。例えば、認証サービスが複数のプロジェクトで使用されるトークンを発行する場合、それをチームグローバル変数として保存します。

権限に関する注意: 通常のメンバーは、既存のチームレベルのグローバル変数の現在の値を表示および変更することしかできません。変数を追加/削除したり、名前を変更したりすることはできません。チーム管理者のみが、チームリソース → 変数でチームレベルの変数を完全に管理できます。

モジュール変数

モジュール変数は、特定のモジュールにスコープが設定されています。Postmanコレクションをインポートすると、そのコレクション変数はApidogのモジュール変数としてインポートされます。

これらはモジュール固有の設定に非常に役立ちます。例えば、プロジェクトにユーザー、注文、製品の個別のモジュールがある場合、それぞれが独自の構成をモジュール変数に保持できます。

モジュール変数を使用するには、Apidogが最新であることを確認してください。

環境変数

環境変数は、おそらく最もよく使用されるタイプです。各リクエストの設定を変更することなく、環境を切り替えることができます。

実際には、通常、複数の環境（ローカル、テスト、ステージング、本番）があります。それぞれに異なるサーバーアドレス、データベース接続、またはサードパーティの設定があります。環境変数を使用すると、それらを瞬時に切り替えることができます。

注: 一度にアクティブにできる環境は1つだけです。環境を選択すると、その中に定義されているすべての変数が有効になります。

テストデータ変数

テストデータ変数は、データ駆動型テストを強化します。多くのデータセットで同じエンドポイントをテストする必要がある場合に役立ちます。

複数の行（またはオブジェクト）を含むCSVまたはJSONファイルを準備します。自動テストシナリオでは、ファイルをインポートすると、Apidogは各行を1つの変数セットとして反復処理し、それぞれに対してテストを実行します。

ローカル変数

ローカル変数は、単一のリクエストまたはテスト実行中のみ有効で、最も短い寿命を持ちます。実行後に消滅します。

ローカル変数は最も高い優先度を持つため、他の変数タイプを一時的にオーバーライドするのに最適です。例えば、環境がuser_idを定義しているが、ある特別なテストのために異なる値が必要な場合、環境を変更する代わりに同じ名前のローカル変数を設定します。

変数の優先度

複数の変数が同じ名前を共有する場合、Apidogは優先度（高い順から低い順）に従って解決します: ローカル変数 > テストデータ変数 > 環境変数 > モジュール変数 > プロジェクトレベルのグローバル変数 > チームレベルのグローバル変数

例: userIdという名前の3つの変数を定義した場合:

プロジェクトレベルのグローバル変数 userId = 1000
モジュール変数: userId = 2000
環境変数: userId = 3000

リクエストで{{userId}}を使用すると、有効な値は3000（環境から）になります。環境値がない場合、モジュール値（2000）にフォールバックし、次にプロジェクトグローバル値（1000）にフォールバックします。

初期値と現在値

グローバル変数、モジュール変数、環境変数には、初期値と現在値の両方があります。これは、チーム共有と個人のプライバシーのバランスを取るためです。

初期値はApidogのサーバーに保存され、チームメイトと同期されます。テストサーバーのURLや公開APIキーなど、共有設定に使用します。
現在値はあなたのデバイスにのみ保存されます。個人のAPIキー、パスワード、プライベートな環境設定などの秘密情報に使用します。

現在値が存在する場合、Apidogはそれを優先します。現在値が空の場合、Apidogは初期値を使用します。現在値を初期値に追従させたい場合は、現在値の横にあるリンクアイコンをクリックして再バインドします。

現在値はデバイスに保存されており、キャッシュをクリアしたりデバイスを切り替えたりすると失われる可能性があります。ApidogのWebバージョンでは、ブラウザに保存されます。新しいデバイスに移行するには、環境をエクスポート/インポートして現在値を移行します。

注: Apidog CLIで自動テストを実行する場合、重要な違いに注意してください。 Apidogクライアントは実行中に現在値を使用しますが、CLIは初期値を使用します。クライアントとCLIで結果が異なる場合、これが一般的な理由です。

変数を設定する方法

値の出所と使用方法に最も適した方法を選択してください。

環境管理ページで直接変数を設定する

最も簡単な方法です。環境管理ボタン（右上）をクリックし、グローバルまたは特定の環境に切り替えて、名前と値を追加します。

この方法は、データベース接続などの安定した設定に最適です。初期値（共有）と現在値（プライベート）の両方を設定できます。

「変数を保存」機能を使用する

多くの場合、変数の値はレスポンスから取得されます。例えば、ログインエンドポイントからのトークンや、ユーザー作成エンドポイントからのユーザーIDなどです。ポストプロセッサーの視覚的な「変数を保存」を使用して、新しい変数を設定します。

リクエストのポストプロセッサーで「変数を保存」を追加し、ソース（通常はJSONレスポンス）を選択し、JSONPathを使用してフィールドを選択します。

例えば、レスポンスJSONが次のようになっている場合:

{
    "user": {
        "id": "69",
        "email": "Ralph85@gmail.com",
        "first_name": "Katlynn",
        "last_name": "Reichert",
        "api_token": "dolore ut mollit Duis sit",
        "created_at": "2025-09-19T01:03:50.236Z",
        "updated_at": "2025-05-10",
        "deleted_at": "2025-09-18T18:30:51.217Z",
        "role": "developer",
        "metadata": {}
    }
}

$.user.emailを使用してトークンを抽出します。

リクエストのレスポンスセクションから直接変数を設定することもできます。

スクリプト経由で変数を設定する

より複雑なロジックには、プリプロセッサーまたはポストプロセッサーでカスタムスクリプトを使用します。Apidogは、すべての変数タイプを操作するための完全なスクリプトAPIを提供しています。

// プロジェクトレベルのグローバル変数を設定する

pm.globals.set('variable_key', 'variable_value');

// チームレベルのグローバル変数を設定する（最初にチームリソースページで定義する必要があります）

pm.globals.set('variable_key', 'variable_value', 'TEAM');

// 環境変数を設定する

pm.environment.set('variable_key', 'variable_value');

// モジュール変数を設定する

pm.moduleVariables.set('variable_key', 'variable_value');

// ローカル変数を設定する

pm.variables.set('variable_key', 'variable_value');

オブジェクトや配列を保存する場合は、最初に文字列化し、読み込むときに解析します。例えば:

pm.environment.set('user', JSON.stringify(userObj));

const users = JSON.parse(pm.environment.get('user'));

注: スクリプトは変数の現在値のみを設定できます。初期値は環境管理ページで設定する必要があります。

データベースデータを変数として使用する

Apidogは、データベースから直接データを取得し、それを変数として設定できます。これは、実際のレコードに依存するテストに非常に役立ちます。

ポストプロセッサーにデータベース操作を追加し、接続を設定し、SQLを記述します。次に、JSONPathを使用してフィールドを変数に抽出します。

変数を使用するためのヒント

変数が機能する場所

変数は、リクエストが実際に送信されたときにのみ解決されます。つまり、ヘッダー、パラメーター、ボディ、テストシナリオ、スクリプトなど、リクエストの送信に関わるあらゆる場所でそれらを使用できます。

Apidogは視覚優先であるため、簡単な経験則として、「動的値」ボタンが表示されている場所では変数を使用できます。

基本的な構文

変数を参照するには二重中括弧を使用します: {{variableName}}。これはURL、ヘッダー、パラメーター、ボディで機能します。

例えば、パラメーターでは:

そしてボディでは:

JSONボディに関する注意: 文字列変数は引用符で囲む必要がありますが、数値変数は不要です。二重中括弧はJSONリンターの警告をトリガーする可能性がありますが、安全に無視できます。

「未解決の変数」が表示されても慌てないでください。ポストプロセッサーやスクリプトで設定された変数は、リクエストが実行されるまで存在しない場合があり、ローカル変数は実行後に消滅します。確認する最善の方法は、実際にリクエストを送信することです。

変数から子フィールドを取得する

変数には、文字列や数値だけでなく、オブジェクトや配列が格納されている場合があります。例えば、ユーザーAPIは、ID、名前、メールなどを含むオブジェクトを返すことがよくあります。

このレスポンスオブジェクトをuserという名前の変数として保存したとします:

{
  "id": 1001,
  "name": "Joe",
  "email": "joe@example.com",
  "role": "admin"
}

{{user.id}} (1001) や {{user.name}} ("Joe") のように、ドット表記で特定のフィールドを参照できます。

配列の場合も同様です。usersという変数がある場合:

[
  {"id": 1001, "name": "Joe"},
  {"id": 1002, "name": "Rio"},
  {"id": 1003, "name": "Outher"}
]

{{users[0].name}}で最初のユーザーの名前を、{{users[1].id}}で2番目のユーザーのIDを取得できます。

これはJSONPathのようなセマンティクスに従っており、変数名がルート ($) のように機能します。

スクリプトで変数を使用する

プリプロセッサーやポストプロセッサーのカスタムスクリプトで変数を使用できます。Apidogは、さまざまな種類の変数に柔軟にアクセスできる完全なスクリプトAPIを提供しています。

// プロジェクトレベルのグローバル変数を取得する

pm.globals.get('variable_key');

// チームレベルのグローバル変数を取得する

pm.globals.get('variable_key', 'TEAM');



// 環境変数を取得する

pm.environment.get('variable_key');



// モジュール変数を取得する

pm.moduleVariables.get('variable_key');



// ローカル変数を取得する

pm.variables.get('variable_key');

文字列として保存されているオブジェクト/配列の場合は、最初に解析します:

const userObj = JSON.parse(pm.environment.get('user'));

console.log(userObj.name);

テストデータ変数によるデータ駆動型テスト

複数のデータ行を含むCSVまたはJSONファイルをアップロードします。実行中、Apidogは{{variableName}}を各行の値に置き換え、各行ごとにテストを1回実行します。これは、多くの入力で堅牢性を検証するのに最適です。

動的値式

独自の変数に加えて、Apidogは特定のルールに従ってランダムなデータを生成する動的値をサポートしています。

スクリプトでは、await pm.variables.replaceInAsync()を使用して、動的式を含む文字列を処理できます。

const template = "Hello, {{$person.fullName}}";

const result = await pm.variables.replaceInAsync(template);

console.log(result); // ランダムに生成された名前を出力します

動的値は、事前にデータセットを準備することなく、ランダムなテストデータを生成するのに最適です。

まとめ

変数はApidogの最も強力な機能の1つです。繰り返しを減らし、テストを柔軟にし、プロジェクトや環境間の切り替えを簡素化します。チーム間でグローバル設定を共有する場合でも、CSVデータでテストを駆動する場合でも、ローカルで値をオーバーライドする場合でも、変数はワークフローを効率的かつ整理された状態に保つのに役立ちます。変数の種類、優先順位、設定方法を習得することで、APIリクエストの一貫性、保守性、および実際のシナリオへの対応を確実にすることができます。