クエリの送信とレスポンス

組み立てたクエリを HTTP で送信し、レスポンスとエラーの分類を確認する操作を説明します。

概要

送信は「組み立てたクエリ × 選択中の環境」で行います。HTTP 通信は端末側（GalleonQL 本体）から発行される ため、ブラウザの CORS 制限を受けません。フロントから直接アクセスできない社内 API でも、GalleonQL の デスクトッププロセスから到達できれば送信できます。応答はタブを切り替えて確認でき、エラーは起因ごとに 分類して表示されます。用語は 主要な用語 を参照してください。

前提

• 送信先の環境が選択され、解決後 URL が確定していること（未解決の {{...}} が残っていると送信できません。 環境の登録・切替）。
• クエリビルダー でルートフィールドを 1 件以上追加していること （0 件の間は送信できません）。
• スキーマの取込は送信の必須条件ではありません（トップバーの送信ボタンとレスポンス領域は未取込でも表示されます）。 ただしクエリの組み立てには取込が必要です（スキーマの取り込み）。

画面上の位置

画面は左のパネル・リクエスト・レスポンスの 3 区画です（概要と特徴）。 リクエストペインのタブは Query | Auth | Headers | Hooks。送信に使う部品は次の場所にあります。

• HTTP メソッド: トップバーの左端（解決後 URL の左）。
• ▶ 送信: トップバーの解決後 URL のすぐ右と、リクエストペイン Query タブのクエリビルダー見出し（入力モード切替の右）の 2 か所。 どちらを押しても同じ送信です。まだ何も送っていないときは、レスポンスペインにも同じボタンが出ます。
• ステータス（HTTP ステータスと所要時間など）: レスポンスペインの見出しの行（リクエストペインの見出しと同じ高さで、タブの行の上）の 1 か所。 送信中だけは、送信ボタンとこの行の両方に 送信中... が出ます。

レスポンスはレスポンスペインに表示されます。 Hooks は送信後にレスポンスから環境変数へ値を取り出す／検証するルールです （リクエストフック（値の抽出と検証）。Pro）。

操作手順

1. 環境とクエリを用意する

1. トップバーの環境セレクタで送信先の環境を選び、解決後 URL が表示されていることを確認します （空や未解決の {{...}} のままだと送信できません）。
2. 認証が必要なら、環境エディタの「認証」節で既定方式と秘密を設定します （環境の登録・切替）。
3. 必要なら Auth / Headers タブを確認します（下記）。
4. Query タブでクエリを組み立てます（クエリビルダー）。下部のプレビューの内容が そのまま送信本文になります。

Auth タブ（リクエストの認証方式）

リクエストペインの Auth タブで認証方式を選びます。秘密（鍵）は選択中の環境に保存され、 エクスポートには漏れません。

「環境の既定を継承」では鍵入力欄は出ません（鍵は環境エディタの「認証」節）。Bearer / Basic を選ぶと 鍵入力欄が出て、入力値は選択中環境の秘密として保存されます。環境未選択で Bearer / Basic を選ぶと 「環境を選択すると鍵を入力できます。」と表示されます。空トークン等の警告は 環境の登録・切替 と同じ文言です。

Headers タブ（認証の ON/OFF・リクエスト固有ヘッダー・最終プレビュー）

リクエストペインの Headers タブの一番上に [✓] 認証を使う チェックがあります。

• ON … 認証ヘッダーを組み立てる（Auth タブの方式を使う）。
• OFF … Authorization を付けない（方式は保持したまま。再 ON で戻る）。

その下の「このリクエスト固有」節で、この送信にだけ載せたいヘッダー（由来 R）を追加・編集・削除できます。 ヘッダー名（例 X-Request-Id）と値を入れて「ヘッダーを追加」。値には {{envVar}} を書けます （選択中の環境で解決されます）。最下部の「送信される最終ヘッダー」に、カスケード・変数解決した結果が 由来バッジ付きで表示されます（環境の登録・切替 の「ヘッダーのカスケード」参照）。

さらにその下の「HTTP タイムアウト（このクエリ）」節では、このクエリだけの接続タイムアウト（1〜60 秒）・ 全体タイムアウト（1〜600 秒）を設定できます。空欄のままなら環境 → プロジェクト → アプリ既定（接続 10 秒／ 全体 60 秒）の順で継承し、空欄の入力欄には現在有効な秒数・由来・許容範囲が表示されます （例:「継承中 60 秒（環境） / 1〜600 秒」）。全角数字は半角へ正規化して保存され、数字以外の文字 （小数点・記号等）は入力からその場で取り除かれ「数字以外は入力できません」と通知されます。 取り除いた後に残った数字がそのまま秒数として保存されるため、1.5 と入力すると . が消えて 15 秒として保存されます。UI から到達しうる唯一のエラーは範囲外の整数を入力した場合です （0 や無制限は指定できません）。環境・プロジェクト単位で設定する方法は 環境の登録・切替 の「HTTP タイムアウトを設定する」「HTTP タイムアウトのカスケード」 を参照してください。

リクエスト固有ヘッダー・認証方式・組み立て中の内容・HTTP メソッド・このクエリの HTTP タイムアウト設定は 自動保存され、起動時やプロジェクト切替時に復元されます（環境切替では載せ替えません）。レスポンス本文は 保存されず、タブを切り替えると Response ペインはリセットされます。このクエリの HTTP タイムアウト設定は リクエスト履歴からは復元されません（長期的に保持したい場合はコレクションへ保存してください）。

2. HTTP メソッドを選び「▶ 送信」を押す

トップバー左端のメソッドボタンで HTTP メソッドを選びます（既定 POST）。

クエリビルダーの入力モードが変数のときは、生成された variables（JSON）も一緒に送信されます（POST 系はボディに、 GET は &variables= パラメータに）。インラインのときは従来どおりクエリ本文だけを送り、variables は付きません （クエリビルダー の入力モードの切替）。

引数の値に書いた {{環境変数}} は、クエリ本文・variables とも送信時に選択中の環境の値へ解決されてから送られます （未解決のキーが残っていても送信はブロックされず警告のみ）。解決後の内容はプレビューの「最終形（解決後）」 トグルで確認でき、履歴や保存には元の {{...}} がそのまま残ります（ヘッダー・URL の {{...}} も同様に解決されます）。

▶ 送信 をクリックすると、送信中はボタンの ▶ が回転するアイコンに替わってラベルが 送信中... になり、 ボタンが無効化されます（レスポンスペインの見出しの行にも同じ回転するアイコンと 送信中... が出ます。OS の設定で 動きを減らしている場合〈macOS の「視差効果を減らす」など〉、アイコンは回転せず止まったまま表示されます）。応答が返ると、 レスポンスペインの見出しの行に {ステータス} {所要時間} ms（例 200 1234 ms）が表示されます。文字の色は結果に 従います（成功は緑、部分エラーは黄、失敗は赤）。ネットワーク到達前に失敗した場合は 失敗 · {所要時間} ms です。 まだ送信していないときは — が表示されます。

2-2. subscription を購読する

クエリの種別が subscription のときは、環境ごとに選んだトランスポート——WebSocket （専用の接続にアップグレードする方式）または SSE（通常の HTTP リクエストの応答をイベント ストリームとして受け取る方式）——で接続します（環境 の「Subscription の トランスポートと接続先を設定する」）。HTTP メソッドの選択は使われません。接続先は環境の Subscription URL で、空欄ならリクエスト URL から自動で決まります。

subscription の購読は Pro プラン限定です。 無料プランで ▶ 送信 を押すと「Pro プラン限定の機能です」 というお知らせが表示され、購読は始まりません（WebSocket・SSE のどちらを選んでいても同じです）。 お知らせの **「Pro にアップグレード」**からプランを確認できます。組み立てたクエリや保存済みのクエリは そのまま残るので、Pro にすればそのまま購読できます。購読中に無料プランへ戻ったときは、その時点で購読が終了します（受信済みのイベントは残ります）。無料プランへ戻るのは、 このデバイスからライセンスを解除したときと、ライセンスの有効期限が切れたことを GalleonQL が確かめたときです （起動時と、起動中に有効期限日を過ぎたとき・起動中は 6 時間ごとに確かめます。Windows / Linux・macOS とも同じです）。

1. ▶ 送信 を押すと購読が始まり、ボタンが ■ 停止 に変わります。
2. サーバからイベントが届くたびに、レスポンスペインのイベント一覧へ積まれていきます。
3. ■ 停止 を押すか、サーバ側が購読を終えると終了します。

認証は、送信時と同じカスケードで解決したヘッダーを使います。WebSocket は接続を開くときに まとめて渡します（ハンドシェイクの仕組み上、リクエストごとにヘッダーを付けられないため）。 SSE はその 1 回の HTTP リクエストに通常のヘッダーとして載せて送ります（購読中に繰り返し 送り直すわけではありません）。いずれも Auth タブ・Headers タブの設定はそのまま効きます。

同時に購読できるのは 1 本だけです。 新しい購読を始めると、それまでの購読は自動的に停止します （WebSocket・SSE を問わず共通の制限です）。

SSE を選んでいる場合の注意: SSE に対応していないエンドポイントへ接続すると、「エンドポイントが SSE に対応していない可能性があります」という理由でエラーになります。環境の「Subscription トランスポート」が接続先と合っているか確認してください。また、サーバの実装によっては、正常に 終了した購読でも「切断」の赤帯が出ることがあります（サーバが購読の終了を知らせる合図の送り方に 依存する既知の制限）。受信済みのイベントには影響しません。

2-3. 受信したイベントを読む

購読中はレスポンスペインの左側にイベント一覧が出て、右側のタブ（レスポンス・レンダーなど）が 選択中のイベントを映します。レスポンスペインが狭く、一覧と右側の中身が横に並ばないとき（ウィンドウが小さいときなど）は、 一覧を上に、中身を下に積んで表示します（どちらの文字も切りません）。

• 最新に追従がオンの間は、新しいイベントが届くたびに選択が最新へ移ります。一覧で過去のイベントを 選ぶと自動的にオフになり、読んでいる途中で飛ばされません。トグルを押せば追従へ戻れます。
• 保持できるのは最新 1000 件までです。超えると古いものから捨てられ、（古い N 件を破棄） と 表示されます。
• エラーを含むイベントがあっても購読は続きます。 GraphQL ではイベントごとに部分的なエラーが 返ることがあるためで、そのイベントを選んだときだけ帯が出ます。
• 接続が切れたときは赤い帯で理由が表示され、受信済みのイベントは消えません。 何件目で切れたかを 確認できるようにするためです。サーバ側が正常に購読を終えた場合は赤帯は出ません。
• 切断されても自動では再接続しません。 切れている間のイベントは取得できないため、自動で繋ぎ直すと 「全部見えている」と誤解する恐れがあるからです。もう一度 ▶ 送信 を押して購読し直してください。

購読が終わると、リクエスト履歴に 1 件残ります（受信件数と経過時間つき）。履歴の行から結果を 開き直せます。アプリを終了して終端を迎えなかった購読は履歴に残りません。

3. レスポンスを確認する

レスポンスペインの見出しの行（リクエストペインの見出しと同じ高さ）に、HTTP ステータスと所要時間（例 200 1234 ms）が 表示されます。状態の語（200・失敗・送信中・受信中・切断など）は縮めず、所要時間・件数・経過はペインが狭いと「…」で 省略します。省略されたところにマウスを載せると、ツールチップで全文が表示されます。ウィンドウが狭いときは、左のパネルから 先に狭めて中央のペインの幅を確保します。

その下のタブの行で見方を切り替えます。タブの行は折り返さず、高さも変わりません。タブが行に入りきらないときは、 後ろのタブから順に「»」のボタン（横の数字は隠れたタブの数）のメニューへ移ります。いま選んでいるタブは必ず行に残り、 メニューからタブを選ぶとそのタブが開きます。キーボードでは「»」で Enter・Space・↓ を押すとメニューが開き、↑・↓ で選んで Enter で開きます（Esc で閉じます）。このリクエストにフックが適用されている場合、実行結果は Response の Hooks タブで確認できます（詳細は リクエストフック）。

• 「レスポンス」タブは行の ▼（折りたたむ）/ ▶（展開）で切り替えます。新しい応答が来ると全展開へ リセットされます。JSON として解析できないボディはツリー表示できない旨が案内されます（原文は レンダータブの raw チェックで確認）。
• ヘッダータブの「送った」の由来バッジは A（アプリ）/ P（プロジェクト）/ E（環境）/ Au（認証）/ R（リクエスト）/ 無印（送信時に合成される Content-Type 等）です。OAuth2 で認証したときは、トークンをどこから得たかのメモも出ます。

4. エラー・部分エラーの見方

GraphQL は HTTP 200 でも errors[] を返すことがあります。GalleonQL はエラーの起因を分類して表示します。

完全なエラー（成功データなし） は Response 上部に赤字で [分類名] メッセージ として表示されます。

代表的なメッセージ例:

タイムアウト値はユーザーが設定できます（接続は既定10秒・1〜60秒、全体は既定60秒・1〜600秒。 スキーマ取込と共通）。アプリ既定・プロジェクト・環境・このクエリの4段でカスケード設定でき、詳細は前述 「Headers タブ」、環境の登録・切替 の「HTTP タイムアウトのカスケード」を 参照してください。

部分エラー（data と errors の併存） では、ツリーに data 側を残したまま、Response 上部に黄色で 「部分的なエラーが含まれています:」と表示され、各エラーメッセージが並びます（extensions.code があれば メッセージ (CODE) の形式）。

送信できないとき（ガード）

▶ 送信 が無効（薄い表示）のときは、ボタンの外側にカーソルを乗せると理由がツールチップで表示されます （複数該当時は最も優先度の高い 1 件）。

送信例

架空スキーマ type Query { hello: String } を例にします。

1. 環境セレクタで送信先の環境を選ぶ（トップバーに解決後 URL が表示される）。
2. 認証が必要なら環境の「認証」節で方式とトークンを設定する。Auth タブは「環境の既定を継承」でよい。
3. スキーマのパネルのスキーマドキュメントで hello の + query をクリックし、プレビューが query MyQuery { hello } になることを確認する。
4. メソッド POST のまま ▶ 送信 をクリックする。
5. レスポンスペインの見出しの行が 200 42 ms のような表示になり、「レスポンス」タブに data → hello → "world" のツリー、 「レンダー」タブで pretty 表示され、raw チェックで原文を表示できる。

ポイント

• 「送信される最終ヘッダー」プレビューと実際に送信されるヘッダーは、常に同じ解決結果です。
• リクエスト履歴は左レールの履歴アイコンから確認できます（環境ごと直近 50 件）。行をクリックすると 新しいタブで、クエリ・ビルダー状態・リクエスト固有ヘッダー・HTTP メソッド・認証方式（秘密は除く）を 復元できます。レスポンス本文は履歴に保存されません。このクエリの HTTP タイムアウト設定も履歴には 保存されず、復元後は環境・プロジェクトの設定を継承します。
• 送信中に環境を切り替えても、進行中の応答が新しい状態を上書きすることはありません。切り替えた先で 改めて送信し直してください。

現時点での制限事項

• GraphQL 変数の送信は入力モードに従います。 インラインではクエリ本文のみ（POST 系は { "query": "..." }、 GET は ?query=...）、変数モードでは variables も送ります（POST 系はボディ { "query": "...", "variables": {…} }、 GET は &variables=<URL エンコードした JSON>）。入力モードの切替は クエリビルダー を参照。
• 必須引数のあるフィールドは、クエリビルダー の引数入力で値を設定してから 送信してください。未設定のまま送るとサーバ側でクライアント（クエリ）エラーになり得ます。
• UPDATE は標準の HTTP メソッドではありません。 受け付けないサーバでは失敗します。
• 認証は なし（none）／ Bearer ／ Basic ／ OAuth2 Client Credentials です（API Key・OAuth2 Authorization Code は未対応）。
• subscription は同時に 1 本までで、切断されても自動では再接続しません。保持できるイベントは 最新 1000 件までです。

うまくいかないときは

関連ドキュメント

• クエリの組み立て: クエリビルダー
• 環境・URL・認証・ヘッダーのカスケード: 環境の登録・切替
• 送信後の値抽出・検証: リクエストフック（値の抽出と検証）
• HTTP タイムアウトのカスケード: 環境の登録・切替 の「HTTP タイムアウトのカスケード」
• スキーマの取り込み（同じエラー分類・タイムアウト）: スキーマの取り込み
• 用語: 主要な用語
• 索引に戻る: ユーザーマニュアル目次