リクエストフック（値の抽出と検証）

送信後のレスポンスに対して、宣言的なルールで値を環境変数へ取り出す、またはステータスやボディを検証する操作を説明します。

概要

リクエストフックは、クエリ送信のあとに自動で評価されるルールです。代表的な使い方は次の 2 つです。

1. 値の抽出 — 例: login ミューテーションのレスポンスからトークンを取り出し、環境変数 token に保存する。以降のリクエストはヘッダーで Bearer {{token}} を参照できる。
2. 検証（アサーション） — 例: ステータスが 200 であること、ボディの $.data.ok が true であることを検査し、結果を Response の Hooks タブに表示する。

ルールは トリガー → 条件（AND）→ アクション の形です。JavaScript などのスクリプトは使えません（宣言的なフォーム編集のみ）。

Pro プラン限定です。 Free ではルールの閲覧・インポート結果の保持はできますが、新規作成・編集・有効切替・送信時の実行はできません。プランの詳細は プラン（Free / Pro）とライセンス を参照してください。

前提

• クエリの送信とレスポンス で送信ができること。
• 環境の登録・切替 で環境変数とヘッダーカスケードを理解していること。
• フックが書き込む先は 環境変数（{{key}}）です。GraphQL 変数（$id 等）とは別物です（主要な用語）。

画面上の位置

左ペインのリクエストタブ Query | Auth | Headers | Hooks の 4 枚目が Hooks です。Free のときはタブ見出しとパネルに [Pro] バッジが出ます（Pro 利用中は出しません）。

実行結果は、中央ペイン（Response）の Hooks タブにまとめて出ます（適用フックが 1 件以上あるときだけタブ自体が出ます）。

• タブ見出し: 未実行は Hooks、送信後は Hooks (発火数/定義数)（例: Hooks (1/1)）
• タブ内サマリ: フック n/m と、検証があるときは 検証 (p/t) ✓|△|✗
• 一覧: 各フックの発火／不発火・抽出・検証（✓/✗）の内訳
• ルールの編集は左ペインの Hooks タブ（リクエスト編集側）のままです

スコープ（3 層カスケード）

• 実行順は プロジェクト → 環境 → このリクエスト です。
• 値の抽出で同じ環境変数名が複数ある場合は、後のスコープが勝ちます。
• 検証の結果はマージせず、フックごとにすべて記録されます。
• 「このリクエスト」は、リクエストをコレクションへ保存するまで選べません。

トリガー

「常に」でも、レスポンスボディが無いとき（トランスポートエラー）はボディ参照の条件・抽出・検証は成立しません。

条件（AND）

条件は 0 件以上。すべて満たしたときだけ発火します（0 件ならトリガー一致で発火）。

演算子は ＝ / ≠ / 含む / 存在する / 未設定（未設定は環境変数専用）です。

アクション

• 抽出できるのは 文字列・数値・真偽値 です。オブジェクト／配列／null はスキップされます。
• 検証が失敗しても、同じルールの抽出は独立して実行されます。
• 検証の失敗は送信結果そのもの（ステータス帯・partial errors 表示）を書き換えません。 Response の Hooks タブに現れます。

操作手順

値を抽出する（トークン保存の例）

1. 対象のリクエストを開き、Hooks タブで「フックを追加」を押します。
2. スコープ・トリガー（多くは「成功時のみ」）を選びます。
3. 必要なら条件を追加します（例: ステータス ＝ 200）。
4. アクションを「値を抽出」にし、パス（例 $.data.login.token）と環境変数名（例 token）を入れます。
5. 「直前のレスポンスで試す」で dry-run し、問題なければ「完了」します。
6. クエリを送信すると、条件を満たした場合に環境変数が更新されます。

検証を追加する

1. アクションの種類を 「検証」 にします。
2. 対象・演算子・値を条件と同じ UI で指定します（例: ステータス ＝ 200、ボディ $.data.ok ＝ true）。
3. dry-run または本送信のあと、Response の Hooks タブでサマリと各検証の ✓/✗ を確認できます。
4. 普段は Body だけ見て、疑わしいときや実装確認のときに Hooks タブを開けば足ります。

期待結果

• Hooks タブに適用中のフックが一覧表示される。
• dry-run は環境変数を書き換えず、本送信と同じ評価結果を返す。
• 本送信で抽出が成功すると、選択中環境の環境変数が確認なしで更新される。
• 検証の成否は Response の Hooks タブに現れ、送信結果の分類表示は従来どおり。

制限事項

• 送信前（pre-request）のフックや、{{$timestamp}} のような組み込み動的変数は未対応です。
• スクリプトによるフックや JSON でのルール編集はありません。
• フックはプロジェクトの JSON エクスポート／インポートに含まれません。
• 未保存タブでは「このリクエスト」スコープを選べません。
• パスや変数名が空の条件・アクションは成立／抽出しません。
• 演算子 「含む」 で比較値を空のままにした場合も不成立です（条件・検証の両方。空文字を許すと常に真になるのを避けるため）。

関連ドキュメント

• クエリの送信とレスポンス
• 環境の登録・切替
• プラン（Free / Pro）とライセンス
• プロジェクトのエクスポート／インポート
• 主要な用語