変数の使い方

Apidogでは、変数を使うことで値を簡単に保存し再利用することができます。値を変数として保存することで、さまざまな環境、リクエスト、スクリプト、テストシナリオでアクセス可能になります。変数を活用することで、生産性が向上し、同僚とのチームワークが促進されます。

変数とは

変数はデータの象徴的な表現であり、必要なときに毎回手動で入力することなく値を取得することができます。これにより、異なる場所で同じ値を再利用することが容易になります。変数を使用することで、リクエストがより柔軟になり、特定の詳細を隠すことで理解しやすくなります。

例えば、複数のリクエストで同じトークンを持っていて、将来的にそれが変更されることを予期している場合、トークンを{{my_token}}という名前の変数として保存し、リクエストのパラメータ値に{{my_token}}を入れることで利用できます。トークンが変更されるたびに、変数の値が更新され、変数が使用されているすべてのリクエストでそれが反映されます。

この概念は、リクエスト内の繰り返されるデータに適用できます。変数に保存された値は、リクエストが実行される際に変数が参照される場所に含まれます。変数は、パラメータ値、ボディ、URL、ヘッダーなどで効果を発揮します。

Apidogの自動テストモジュールでは、変数を使用してリクエスト間でデータを渡すことができます。

変数のスコープ

Apidogは、さまざまなスコープでの変数のサポートを提供し、異なる開発、テスト、コラボレーションの要件に合わせてプロセスを調整できます。Apidogのスコープは、リクエストが動作するコンテキストに対応しており、それぞれのスコープは独自の目的を持っています。

スコープは、広いものから狭いものの順に、グローバル、環境、データ、ローカル変数があります。

グローバル変数は、リクエスト、スクリプト、環境間でデータを共有することができます。その広いスコープは、テストや初期の実験に最適です。グローバル変数には2種類あります：

プロジェクト内で共有されるグローバル変数：これらの変数はプロジェクト全体でアクセス可能で、異なるAPI間でデータを共有するのに最適です。例えば、ログインAPIからトークンを抽出し、それをグローバル変数として保存し、他のAPIリクエストで認証に使用することができます。

チーム内で共有されるグローバル変数：これらの変数はチーム全体で共有され、異なるプロジェクト間でデータを共有するのに最適です。例えば、ログインプロジェクトのトークンを使用して、ファイナンスプロジェクトで認証を行うといった、マイクロサービスアーキテクチャでよくあるシナリオに役立ちます。

NOTE

環境管理ページでは、既存のチームグローバル変数の現在の値を表示および更新することしかできません。変数の追加、削除、名前変更、初期値の変更はここでは許可されていません。

APIを実行する際に、前/後処理を使用して、変数をチームグローバル変数として抽出または設定できます。ただし、現在の値のみを変更でき、名前や初期値を変更することはできません。

チーム変数を追加、削除、管理するには、チーム管理者の権限が必要です。これらの操作はチームリソース > 変数でのみ実行できます。

環境変数は、ローカル開発、テスト、または本番環境など、特定の環境に作業をターゲットすることができます。環境を切り替えると、現在の環境の環境変数の値が有効になります。一度にアクティブにできる環境は1つだけです。

データ変数は、外部のCSVまたはJSONファイルから取得され、テストシナリオやApidog CLIでデータセットを定義するために使用されます。これらの変数は一時的な値を持ち、リクエストやコレクションの実行後には持続しません。

ローカル変数は、単一のリクエストまたはテストシナリオの実行に限定された一時的な変数であり、実行が完了すると消えます。ローカル変数は、他の変数スコープを一時的に上書きするのに役立ちますが、実行後に値を保持することはありません。

同じ名前の変数が異なるスコープで定義されている場合、狭いスコープの値が優先されます。つまり、変数の有効性の優先順位は、グローバル < 環境 < データ < ローカルの順です。

例えば、「id」という名前のグローバル変数と同じ名前のローカル変数がある場合、リクエストが実行されるときにはローカル変数の値が使用されます。

Apidogの変数は文字列として保存されます。オブジェクトや配列を保存する場合は、JSON.stringify()を使用して文字列に変換してから保存し、取得する際にはJSON.parse()を使用してください。

初期値と現在値

各変数には初期値と現在の値があります。

初期値は、変数が設定された要素（環境またはグローバル）内で設定された値を表します。この値はApidogのサーバーと同期され、特定の要素を共有する際にチームと共有されます。初期値を設定することは、チームメイトとのコラボレーションに役立ちます。ただし、初期値内のデータは他の人と共有され、公開される可能性があることに注意してください。

現在値は、リクエストを送信する際に使用されます。これらはApidogのサーバーと同期されないローカル値です。現在値に対する変更は、元の共有APIドキュメント、環境、またはグローバルに永久に保存されません。

現在の値はローカルにのみ保存されるため、パスワードやトークンなどの機密データを保存するのに適しています。このデータは他のチームメンバーと同期されないため、各個人が自分の現在の値を個別に安全に利用できます。

個人的な現在の値を使用する必要がない場合は、現在の値を空のままにしておくことができます。この場合、現在の値は初期値に従います。ただし、現在の値フィールドに値を入力すると、変数は初期値を使用しなくなります。

また、現在の値の横にあるリンクアイコン🔗をクリックして、現在の値を初期値に再バインドすることもできます。

現在の値はローカルにのみ保存されるため、Apidogのファイルキャッシュをクリーニングするソフトウェアを使用すると、現在の値が削除される可能性がありますのでご注意ください。

デバイスを変更する際、現在の値はアカウントと共に自動的に移行されません。エクスポート-インポート環境機能を使用して移行を実現できます。

Apidog Webを使用している場合、現在の値はブラウザデータに保存されます。

Apidog CLIでの変数の使用

Apidogクライアントでテストシナリオを設定した後、Apidog CLIを使用して任意のマシンでこのシナリオを実行できます。

クライアントで実行する際には変数の現在の値が使用され、CLIでは変数の初期値が使用されることに注意が必要です。クライアントとCLIでの実行結果が異なる場合、これがその理由であることがよくあります。

Apidog CLIについて詳しく学ぶ。

変数の定義

変数の値がどこから来るかに応じて、変数を定義する方法はいくつかあります。環境管理ポップアップで変数の値を事前設定したり、前/後処理で変数を抽出したり、カスタムスクリプトを使用して変数の値を設定することができます。

環境管理での変数値の事前設定

"環境管理"ポップアップでグローバル変数と環境変数の値を事前設定することができます。以下の手順に従ってください：

インターフェースの右上隅にある"環境管理"ボタン≡をクリックします。

"グローバル変数"または特定の環境に切り替えます。

変数名、初期値、現在の値を追加します。

保存をクリックします。

変数の初期値は環境ポップアップでのみ設定できます。プロセッサやスクリプトを使用する場合、変数の現在の値のみを設定でき、初期値は設定できません。

「抽出変数」操作の追加

Apidogは、APIレスポンスから値を視覚的に抽出し、変数として保存することをサポートしています。以下の手順に従ってください：

実行タブ（設計モード）またはリクエストタブ（デバッグモード）で後処理に移動します。

"後処理を追加"にカーソルを合わせて"抽出変数"を選択します。

変数名を入力し、変数スコープを選択します。
抽出元を選択します。例えば、レスポンスJSON、レスポンスXML、レスポンステキストなど。

レスポンスがJSON/XML形式の場合、JSONPath/XPath構文を使用してレスポンスJSON/XMLの特定の部分を解析し、変数の値として保存できます。

"送信"をクリックしてリクエストを送信すると、変数抽出が実行され、コンソールでログを確認できます。

抽出変数変数について詳しく学ぶ

スクリプトでの変数設定

前処理または後処理スクリプトでsetメソッドを使用して変数を簡単に設定できます。以下はその例です：

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

setの構文：

環境変数

// 環境変数を設定する  
pm.environment.set('variable_key', 'variable_value');  

// 環境変数を解除する  
pm.environment.unset('variable_key');

環境変数は、配列、オブジェクト、文字列など、さまざまなタイプのデータを保持できます。オブジェクトや配列のような非文字列データの場合、JSON.stringifyを使用して文字列に変換してから保存する必要があります：

var array = [1, 2, 3, 4];  
pm.environment.set('array', JSON.stringify(array));  

var obj = { a: [1, 2, 3, 4], b: { c: 'val' } };  
pm.environment.set('obj', JSON.stringify(obj));

保存されたデータを読み取るには、JSON.parseを使用して元の形式に戻します：

try {  
  var array = JSON.parse(pm.environment.get('array'));  
  var obj = JSON.parse(pm.environment.get('obj'));  
} catch (e) {  
  // 例外を処理する  
}

グローバル変数

プロジェクト内で共有されるグローバル変数：

// グローバル変数を設定する  
pm.globals.set('variable_key', 'variable_value');  

// グローバル変数を解除する  
pm.globals.unset('variable_key');

チーム内で共有されるグローバル変数：

// チームで共有されるグローバル変数を設定する  
pm.globals.set('variable_key', 'variable_value', 'TEAM');  

// チームで共有されるグローバル変数を解除する  
pm.globals.unset('variable_key', 'TEAM');

ローカル変数

// ローカル変数を設定する  
pm.variables.set('variable_key', 'variable_value');  

// ローカル変数を解除する  
pm.variables.unset('variable_key');

スクリプト構文について詳しく学ぶ。

データベースからの変数値の取得

Apidogは、データベースに接続してデータを取得し、変数として設定し、リクエストで使用するユニークな機能を提供しています。以下の手順に従ってください：

実行タブ（設計モード）またはリクエストタブ（デバッグモード）で後処理に移動します。

"後処理を追加"にカーソルを合わせて"データベース操作"を選択します。

データベース操作に名前を付け、データベース接続を設定します。データベース接続について詳しく学ぶ。

SQLコマンドを入力します。コマンド内で{{variables}}を使用することができます。

"結果を変数に抽出"を設定します。JSONPathがサポートされています。

送信をクリックしてリクエストを実行します。コンソールでデータベース操作の結果を確認できます。

データベース操作について詳しく学ぶ。

変数の使用

Apidogでは、プロジェクト全体で変数を参照するために二重中括弧を使用できます。例えば、リクエストの認証設定で"username"という名前の変数を参照するには、変数名を二重中括弧で囲んで{{my_variable}}のようにします。

APIを実行すると、Apidogは変数を解決し、その現在の値に置き換えます。

例えば、変数が参照されているリクエストURLでは、次のようになります：

http://127.0.0.1/pet/findByStatus?status={{CurrentStatus}}

Apidogはリクエストを実行する際にCurrentStatus変数の保存された値を使用します。CurrentStatusの値が"available"の場合、リクエストは次のクエリパラメータを含むURLに送信されます：

http://127.0.0.1/pet/findByStatus?status=available

"実際のリクエスト"タブで組み立てられたリクエストを確認できます。

リクエストボディ内で変数を参照する場合、参照を二重引用符で囲みます：

{ 
    "status" : "{{CurrentStatus}}"
    "quantity" : {{TotalPet}}
}

JSON形式で文字列型の変数を使用する場合は、二重引用符が必要です。他の型には二重引用符を追加しないでください。上記の例を参照してください。

二重中括弧は、時々不正なJSON形式の警告を引き起こすことがあります。これらの警告は無視して構いません。

変数は、リクエストURL、パラメータ、ヘッダー、認証設定、リクエストボディ、ヘッダープリセットで使用できます。

時々、"未解決の変数"通知が表示されることがあります。これは、変数が環境またはグローバル変数で定義されていないことを示しています。ただし、これは必ずしも問題ではありません。後処理で変数を抽出したり、スクリプトを使用して変数を設定している場合、リクエストを実行する前に値が取得されない可能性があります。ローカル変数の場合、実行後に期限切れになる可能性があり、その結果、変数の値が利用できなくなります。したがって、問題があるかどうかを確認するために、最初にリクエストを送信して確認してください。

変数のサブ要素の値にアクセスする

変数の値がオブジェクトまたは配列の形式である場合、変数内の属性の値を{{variableName.attributeName}}または{{variableName[0].attributeName}}で読み取ることができます。例えば：

オブジェクト変数userは次のようになります：

APIパラメータでuserオブジェクトのnameプロパティを{{user.name}}として参照できます。

カスタマイズされたスクリプトでuserオブジェクトのnameプロパティをpm.variables.get("user.name")として参照できます。

配列変数userは次のようになります：

APIパラメータでuser配列の最初の要素のnameプロパティを{{user[0].name}}として参照できます。

カスタマイズされたスクリプトでuser配列の最初の要素のnameプロパティをpm.variables.get("user[0].name")として参照できます。

変数（オブジェクトまたは配列）のプロパティの値を{{user.name}}として読み取ることは、JSONPath構文仕様に従います。JSONPathの\記号を変数名で置き換えることができます。

JSONPathの詳細を確認する。

スクリプトでの変数の使用

スクリプトで変数を使用する場合、{{variable}}の構文を直接使用することはできません。代わりに、getメソッドを使用して変数の値を変数に割り当てる必要があります。以下はその例です：

getの構文についての詳細：

環境変数

// 環境変数を取得する
var variable_key = pm.environment.get('variable_key');

環境変数は、配列、オブジェクト、文字列など、さまざまな形式のデータを保存できます。オブジェクトや配列のような非文字列データの場合、JSON.stringifyを使用して適切に保存する必要があります：

// 配列を保存する  
var array = [1, 2, 3, 4];  
pm.environment.set('array', JSON.stringify(array));  

// オブジェクトを保存する  
var obj = { a: [1, 2, 3, 4], b: { c: 'val' } };  
pm.environment.set('obj', JSON.stringify(obj));

このようなデータを取得する際には、JSON.parseを使用して元の形式に戻す必要があります：

try {  
  var array = JSON.parse(pm.environment.get('array'));  
  var obj = JSON.parse(pm.environment.get('obj'));  
} catch (e) {  
  // 例外を処理する  
}

グローバル変数

プロジェクト内で共有されるグローバル変数：

// プロジェクト内で共有されるグローバル変数を取得する
var variable_key = pm.globals.get('variable_key');

チーム内で共有されるグローバル変数：

// チーム内で共有されるグローバル変数を取得する
var variable_key = pm.globals.get('variable_key', 'TEAM');

ローカル変数

// ローカル変数を取得する
var variable_key = pm.variables.get('variable_key');

変数のログ記録

リクエストの実行中にApidogコンソールに変数の値をログとして記録できます。

スクリプト内で変数の値をログに記録するには、次の構文を使用します：

ログの結果を表示するには、レスポンスセクションのコンソールタブをクリックします。

データ変数の使用

Apidogでは、リクエストパラメータとして送信する必要がある複数のデータセットがある場合、データ変数機能を利用できます。テストシナリオでは、CSVまたはJSON形式のデータをインポートできます。その後、これらのデータ変数を{{variable_name}}として参照できます。変数名はCSVの列名に対応します。

テストシナリオでこのテストデータセットを選択すると、実行時に{{variables}}の値が実際のデータに置き換えられます。各データ行が1回の実行に対応し、テストレポートで各実行のリクエストとレスポンスを確認できます。

データ駆動型テストのガイドを参照して詳細を確認してください。

FAQ

Q: モックで変数を参照できますか？変数を使用できるシナリオはどのようなものですか？

A: 変数はリクエストが送信されるときにのみ実際の値になります。これは、変数が使用できるシナリオと使用できないシナリオがあることを意味します。

変数を使用できるシナリオ：

リクエスト：リクエストパラメータ、ボディ、パス、認証などの場所で{{variable}}を直接使用できます。

前処理および後処理スクリプト：これらのスクリプトでは、pm.environment.get("variablename")や類似の文を使用して変数を参照できますが、{{variable}}を直接使用することはできません。

テストシナリオ：テストシナリオ内のリクエストは送信されるため、リクエストとスクリプトと同じです。

変数を使用できないシナリオ：

API仕様：リクエストのデフォルト値、レスポンスのデフォルト値およびモックでは変数を使用できません。

モック：高度なモックおよびモックスクリプトでは変数の使用をサポートしていません。

重要な注意点：

変数の値を別の変数に設定しないでください。それは変数の値を正しく解決する際に問題を引き起こす可能性があります。

重要なポイントは、変数は実際のリクエストが行われるときにのみ解決されるということです。API定義の静的な部分やモックシナリオでは使用できません。これらはリクエストが送信されることを伴わないためです。

変数とは#

変数のスコープ#

初期値と現在値#

Apidog CLIでの変数の使用#

変数の定義#

環境管理での変数値の事前設定#

「抽出変数」操作の追加#

スクリプトでの変数設定#

データベースからの変数値の取得#

変数の使用#

変数のサブ要素の値にアクセスする#

スクリプトでの変数の使用#

変数のログ記録#

データ変数の使用#

FAQ#

変数とは

変数のスコープ

初期値と現在値

Apidog CLIでの変数の使用

変数の定義

環境管理での変数値の事前設定

「抽出変数」操作の追加

スクリプトでの変数設定

データベースからの変数値の取得

変数の使用

変数のサブ要素の値にアクセスする

スクリプトでの変数の使用

変数のログ記録

データ変数の使用

FAQ