リクエストの中には、マシンから送信される前に処理が必要なものや、レスポンスが届いた瞬間に処理が必要なものがあります。ペイメントAPIはタイムスタンプと秘密鍵から計算されたHMAC署名を要求します。ログインエンドポイントは、その後のすべての呼び出しに必要なトークンを返します。チェックアウトフローでは、レスポンスが実際に`200`を返し、正しい注文IDを返したことを確認する必要があります。これらすべてを手作業で行うことはできますが、すぐに古くなり、リクエストをチームメイトと共有した瞬間に機能しなくなります。 スクリプトはそれを解決します。Apidogでは、リクエストに小さなJavaScriptコードをアタッチして自動的に実行させることができます。1つはリクエスト送信前に、もう1つはレスポンス受信後に実行されます。Postmanスクリプトを書いたことがある方なら、Apidogのエンジンは同じ`pm`オブジェクトAPIと互換性があるため、その経験が役立つでしょう。このガイドでは、リクエストの署名を事前リクエストスクリプトで行い、その後、レスポンス後スクリプトでトークンを抽出するという、現実的な例を用いて両方のステージを詳しく説明します。Apidogのスクリプトドキュメントには動作が完全に記載されていますが、タブ名やいくつかの動作はPostmanとは異なり、それらの違いが重要になります。
事前スクリプトと事後スクリプトの実際の動作
Apidogはスクリプトを2つのステージで実行し、それらを明確に命名しています。
Pre Processors (事前プロセッサー) は、リクエストがサーバーに送信される前に実行されます。ここでは、タイムスタンプの生成、署名の計算、ランダムな注文IDの設定、変数の読み取りとヘッダーへの整形など、準備作業を行います。この時点ではレスポンスはまだ存在しないため、レスポンスを検査するような処理はここではできません。
Post Processors (事後プロセッサー) は、レスポンスが受信された後に実行されます。ここでは、アサーションを使って返された内容を検証したり、後で再利用するためにボディから値を取り出したりします。認証トークンの抽出、新しく作成されたリソースIDの取得、ステータスコードの確認、ページネーション用のカーソルの保存などを行います。
この分割から2つのルールが導かれます。まず、`pm.response`（その`code`、`status`、`headers`、`responseTime`、`responseSize`、`text()`、および`json()`を含む）はPost Processorsでのみ機能します。送信前に読み取るべきレスポンスはないため、Pre Processorでそれを呼び出しても意味がありません。次に、変数は2つのステージが互いに通信するための手段です。Pre Processorが値を設定し、リクエストがそれを使用し、Post Processorがそれを読み取ったり上書きしたりできます。
Postmanから移行する場合、最初にラベルの変更に注意してください。Apidogのタブは「Pre-request Script」と「Tests」ではなく、Pre ProcessorsとPost Processorsです。動作は非常に似ていますが、画面上の名前が異なります。
セットアップ：リクエストを開き、タブを見つける
Apidogをダウンロードして手順に従ってください。無料で、macOS、Windows、Linuxで動作します。まだお持ちでない場合は、Apidogダウンロードページから入手してください。
Apidog内でスクリプト化したいAPIリクエストを開きます。各エンドポイントには、通常のParams、Headers、Bodyタブの横にPre ProcessorsタブとPost Processorsタブがあります。いずれかのステージにロジックを追加するには、タブを開き、Custom Scriptを追加を選択します。これにより、`pm`オブジェクトに対してプレーンなJavaScriptを記述できるコードエディターが開きます。
何かを書き始める前に、値がどこに存在するかを知っておくと役立ちます。Apidogは変数を次の優先順位で解決します。
ローカル変数 > 環境変数 > プロジェクト内で共有されるグローバル変数 > チーム内で共有されるグローバル変数。
したがって、ローカル変数は同名の環境変数よりも優先され、以下同様です。値が期待どおりでない場合、このことを念頭に置いてください。おそらく、順序の上位にある何かがそれを隠している可能性があります。複数のリクエスト間で永続する値が必要な場合は、Apidogのグローバルパラメータは優先順位が低く、安定したプロジェクト全体の設定に適しています。
事前プロセッサーの例：HMACでリクエストを署名する
各リクエストをHMAC-SHA256署名で認証する支払いエンドポイントを呼び出すとします。これは多くのプロバイダーがウェブフック検証に使用するのと同じパターンであり、Stripeの署名ドキュメントで詳しく説明されています。サーバーはタイムスタンプと、そのタイムスタンプとリクエストボディから計算され、APIシークレットでキー化された署名を期待します。送信ごとに両方を新しく構築する必要があります。
Apidogは`crypto-js`を組み込みライブラリとして提供しているため、何もインストールする必要はありません。Pre Processorsタブを開き、Custom Scriptを追加を選択して、次のように記述します。
// Pre Processor: リクエストが送信される前に署名します
const CryptoJS = require('crypto-js');
// 現在のUnixタイムスタンプ (秒単位)
const timestamp = Math.floor(Date.now() / 1000).toString();
// 環境変数からシークレットを読み取ります
const secret = pm.environment.get('payments_api_secret');
// 署名する文字列を作成します: タイムスタンプ + 改行 + 生のボディ
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;
// HMAC-SHA256署名を計算し、16進数エンコードします
const signature = CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
// 両方の値をリクエストで使用する環境変数として保存します
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);
pm.console.log('リクエストを署名しました: ' + timestamp);
このスクリプトは署名を計算し、タイムスタンプと署名の両方を環境変数に保存します。次に、それらをリクエストに組み込みます。Headersタブで、`{{variableName}}`構文を使用して保存された値を参照します。
X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
送信時、ApidogはまずPre Processorを実行し、2つの変数を設定してから、それらをヘッダーに置き換えます。サーバーは、手動での手順なしに、送信時に有効な署名を常に受け取ります。`require('crypto-js')`の呼び出しはモジュール全体を取り込むことに注意してください。サブモジュールではなくライブラリ全体をインポートするため、`require('crypto-js')`は機能しますが、`require('crypto-js/sha256')`は機能しません。
注意点が1つあります。変数操作は現在の値のみを対象とし、環境エディターに入力した初期値には影響しません。これは、署名が一時的なものであることを意図しているため、ここでは望ましい動作です。Postman側での署名パターンについても説明が必要な場合、Postmanの事前リクエストスクリプトに関するチュートリアルでは、Postmanのラベルで同じアイデアを扱っており、ApidogのPre Processorsにもきれにマッピングされます。
事後プロセッサーの例：トークンを抽出してアサートする
次に、もう一方のステージです。認証された後続のすべての呼び出しに必要なトークンを返すログインリクエストを想像してください。
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": 4812, "email": "dana@example.com" },
"expires_in": 3600
}
Post Processorsタブを開き、Custom Scriptを追加を選択し、ボディからトークンを抽出し、後続のリクエストのために保存します。
// Post Processor: レスポンスを検証し、トークンを抽出します
pm.test('ステータスは200です', function () {
pm.response.to.have.status(200);
});
const jsonData = pm.response.json();
pm.test('レスポンスはトークンを返します', function () {
pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});
pm.test('ユーザーIDが存在します', function () {
pm.expect(jsonData.user.id).to.be.a('number');
});
// 他のリクエストが送信できるようにトークンを保存します
pm.environment.set('auth_token', jsonData.token);
pm.console.log('ユーザー ' + jsonData.user.email + ' のトークンを保存しました');
ここでは2つのことが起こっています。`pm.test()`ブロックは、ApidogがネイティブでサポートするChaiスタイルの`pm.expect()`マッチャーを使用して、レスポンスが期待通りの形式であることをアサートします。そして、`pm.environment.set('auth_token', jsonData.token)`はトークンを環境に保存します。これで、後続のどのリクエストでも手動でコピーすることなく`Authorization: Bearer {{auth_token}}`を送信できます。
このアサーションの部分は、それ自体で注目に値します。優れた事後レスポンスチェックは、手動のクリックと目視確認を実際のテストに変えるものであり、ApidogにおけるAPIアサーションのガイドでは、知っておくべきマッチャーとパターンについてより深く掘り下げています。また、これらのフローに現実的な偽のデータを投入したい場合は、ApidogのFaker.jsが上記の変数設定と非常によく合います。
Post Processorsで注意すべき動作がいくつかあります。`pm.iterationData`（テストデータ）は読み取り専用なので、データ駆動の値を読み取ることはできますが、スクリプトからそれに書き戻すことはできません。また、`pm.cookies`はサーバーが返したレスポンスからのCookieを返し、リクエストと共に送信されたCookieではありません。
公開スクリプトでロジックを再利用する
HMAC署名ブロックを記述したら、おそらく複数のリクエストでそれを使いたくなるでしょう。それを10個のエンドポイントにコピー＆ペーストすると、アルゴリズムが変更されたときに10箇所を修正することになります。Apidogの解決策はPublic Scripts (公開スクリプト) です。これは、一度記述し、必要な場所でアタッチできる再利用可能なスニペットです。
Settings > Public Scriptsで作成し、その後、リクエストのPre ProcessorsまたはPost Processorsタブに追加します。プロセッサーリスト内では、Public ScriptとCustom Scriptが並んで表示され、順序が重要です。公開スクリプトは、同じリスト内のカスタムスクリプトの前に実行され、複数の公開スクリプトがある場合は、リストされた順序で上から下へ実行されます。
人々が引っかかる落とし穴が1つあります。Custom ScriptがPublic Scriptで定義された関数を呼び出したい場合、その関数はグローバルである必要があります。通常の`function`宣言または`const`で束縛された関数は、自身のスクリプト内でローカルであり、次のスクリプトからは見えません。`var`、`let`、または`const`なしで代入することで宣言します。
// Public Script内: キーワードを省略することでsign()をグローバルにします
sign = function (payload, secret) {
const CryptoJS = require('crypto-js');
return CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
};
// その下のCustom Script内: グローバル関数を名前で呼び出します
const timestamp = Math.floor(Date.now() / 1000).toString();
const secret = pm.environment.get('payments_api_secret');
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', sign(timestamp, secret));
まずPublic Scriptを追加し、その下にCustom Scriptを配置すると、呼び出しが解決されます。順序を間違えたり、`const`を追加したりすると、未定義関数のエラーが発生します。
ライブラリ、外部パッケージ、およびデバッグ
上記の`crypto-js`のインポートは、Apidogがセットアップなしでバンドルしている一連のライブラリの1つです。それらのいずれかを直接`require()`できます。
crypto-js(v3.1.9-1) ハッシュとHMAC用jsrsasign(v10.3.0) JWTおよびRSA作業用 (Apidog 1.4.5以降が必要)chai(v4.2.0) アサーションマッチャー用lodash、moment、uuid、xml2js、cheerio、postman-collection、atob、btoa、csv-parse/lib/sync、tv4、ajv- Nodeの組み込みモジュール (`path`、`assert`、`buffer`、`util`、`url`、`querystring`、`stream`、`events`など)
このリストにないものが必要な場合は、`$$.liveRequire()`を使用して実行時にプルインできます。これにより、パッケージがその場でフェッチされます。
$$.liveRequire('nanoid', (nanoid) => {
const id = nanoid.nanoid();
pm.environment.set('request_id', id);
});
このパスはインターネット接続を必要とします。Apidogはスクリプトの実行時にパッケージをダウンロードするためです。バンドルされているライブラリは必要ありません。
スクリプトが誤動作した場合は、ログを出力して原因を突き止めます。`pm.console.log()`と通常の`console.log()`はどちらもApidogのコンソールに出力されるため、計算された署名や抽出されたフィールドをダンプして、リクエストが送信される前または返された後にスクリプトが何を生成したかを正確に確認できます。
驚かされないように、さらに2つの制限を挙げておきます。スクリプト内で追加のHTTP呼び出しを発火するための`pm.sendRequest()`は、Promiseではなくコールバックパターンを使用するため、`await`ではなくコールバックで記述してください。また、リクエストをチェーンするためのPostmanの`pm.nextRequest()`はここではサポートされていません。分岐や条件付きステップを含む実際のワークフローオーケストレーションが必要な場合は、Apidogでは代わりにテストシナリオを使用します。これは、ConditionやIf-Elseステップでリクエストを視覚的にシーケンスするものです。スクリプトを多く書く場合は、組み込みのApidog Script Generatorも、自然言語の記述からスクリプトのひな形を作成し、開始点とすることができます。
Apidog CLIでワークフローを自動化する
スクリプトは「送信」をクリックしたときにだけ実行されるわけではありません。リクエストとアサーションを保存されたテストシナリオにパッケージ化すると、Apidog CLIはそのシナリオ全体をヘッドレスで実行し、Pre ProcessorsとPost Processorsも含まれます。これにより、署名とトークン抽出ロジックが手動のステップではなくCIの一部となります。
CLIをインストールして認証し、IDでシナリオを実行します。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
`-t`フラグはテストシナリオID、`-e`は環境ID、`-r`はレポーター（`cli`、`html`、または`junit`、複数指定する場合はカンマ区切り）を選択します。Apidogアカウント設定でアクセストークンを生成し、`APIDOG_ACCESS_TOKEN`としてエクスポートすると、デスクトップで実行された同じシナリオが、Pre ProcessorsとPost Processorsを含めてCIで実行されます。
正直な注意点として、ローカルファイルや一度ロードしたパッケージなど、マシンにのみ存在する何かに依存するスクリプトは、デスクトップアプリではパスしてもCLIでは失敗する可能性があります。これは、ランナーがその依存関係を持っていないためです。スクリプトはバンドルされたライブラリまたは`$$.liveRequire()`に限定することで、どこでも同じように動作するようにしてください。
よくある質問 (FAQ)
Apidogスクリプトは既存のPostmanスクリプトと互換性がありますか？
ほとんどの場合、互換性があります。Apidogのエンジンは同じ`pm`オブジェクトAPIを使用しているため、`pm.environment.set()`、`pm.response.json()`、`pm.test()`、`pm.expect()`はすべてご存知の通り動作します。覚えておくべき2つの違いは、タブ名が「Pre-request Script」と「Tests」ではなくPre ProcessorsとPost Processorsであること、そして`pm.nextRequest()`のような一部の未サポートの呼び出しです。ほとんどのスクリプトは貼り付けて実行できます。
なぜ事前リクエストスクリプトで`pm.response`が未定義を返すのですか？
まだレスポンスがないためです。Pre Processorsはリクエストが送信される前に実行されるため、検査するべきものがまだ返されていません。`pm.response`（そのステータス、ボディ、ヘッダー）を読み取るコードは、Post Processorに属します。事前ステージで値が必要な場合は、代わりに`pm.request`、変数、またはライブラリから取得してください。
1つのスクリプトを複数のリクエストで共有するにはどうすればよいですか？
Settings > Public Scriptsの下にあるPublic Scriptsを使用します。ロジックを一度記述し、各リクエストのPre ProcessorsまたはPost Processorsタブにアタッチします。そして、同じリスト内では公開スクリプトがカスタムスクリプトの前に実行されることを忘れないでください。カスタムスクリプトからPublic Scriptの関数を呼び出すには、`var`、`let`、`const`なしで代入することによりグローバルに宣言します。
Apidogがバンドルしていないnpmパッケージをインポートできますか？
はい、`$$.liveRequire('package-name', (pkg) => { ... })`を使用することで可能です。これは実行時にパッケージをダウンロードするため、インターネット接続が必要です。`crypto-js`、`moment`、`uuid`などの組み込みリストにあるものは、ネットワークなしで通常の`require()`を使用してください。完全なモジュールのみを要求でき、サブモジュールパスは要求できないことに注意してください。
スクリプトが出力したものはどこで見られますか？
`pm.console.log()`または`console.log()`を使用して、リクエスト送信後にApidogのコンソールで出力を確認します。これは、シナリオで信頼する前に、署名が計算されたか、トークンが抽出されたかを確認する最も速い方法です。
まとめ
Pre ProcessorsとPost Processorsは、静的なリクエストを、自身を準備し、自身の作業をチェックするリクエストに変えます。送信前に署名し、受信後に抽出とアサートを行い、共有ロジックをPublic Scriptsに持ち上げて一度だけ記述するようにします。`pm` APIとバンドルされているライブラリにより、Postmanで知っていることのほとんどがそのまま移行できます。Apidogを開き、任意のリクエストを選択し、最初のカスタムスクリプトを追加して、単一の送信で両方のステージが実行されるのを見てください。無料で開始でき、クレジットカードは不要です。