GalleonQL マニュアル
変更履歴

主要な用語

このページでは、GalleonQL のマニュアル全体で使う基礎用語を、短い例とともにまとめます。他のページから参照される共通の土台です。

環境（接続プロファイル）

環境 は、「どのエンドポイントに、どんな認証・ヘッダーで接続するか」をひとまとめにした 切替可能な接続プロファイル です。GalleonQL は Postman と同じ 直交型 のモデルを採用しており、環境は階層の中間ノードではありません。

  • クエリは 環境に依存せず、コレクションの中に持ちます。
  • 送信は「クエリ × 選択中の環境」で組み立てます。トップバーで環境を切り替えるだけで、同じクエリの送信先を dev / stg / prod のように変えられます。

例: 環境 dev はローカルの http://localhost:4000/graphql、環境 prod は https://api.example.com/graphql を指す。クエリ getUsers は 1 つだけ持ち、環境トグルで送信先を切り替える。

見た目の上では環境フィルタで階層のように見せることがありますが、データ構造としては直交（クエリと環境は別軸）です。詳しくは 環境の登録・切替 を参照してください。

環境変数（{{...}}）

環境変数 は、環境が持つ key-value のことです。{{...}} の形でエンドポイント URL・ヘッダー・GraphQL 変数の値などに差し込み、送信時に選択中環境の実値へ解決されます。

例: 環境変数 baseUrl = http://localhost:4000/graphql を定義し、リクエスト URL を {{baseUrl}} と書く。環境を切り替えると {{baseUrl}} の中身が入れ替わる。token を定義して Authorization ヘッダーに Bearer {{token}} のように使うこともできる。

環境変数は次の「GraphQL 変数」とは 別物 です。混同しないでください。

送信後のレスポンスから値を取り出して環境変数へ保存する操作は リクエストフック（値の抽出と検証） を参照してください（Pro）。

GraphQL 変数（$id / $input）

GraphQL 変数 は、GraphQL クエリ自身の引数です。$id や $input のように $ で始まり、クエリの実行時に値を渡します。環境が持つ {{...}} の環境変数とは役割が異なります。

例: user(id: $id) の $id が GraphQL 変数。baseUrl や token（環境変数）とは別の仕組み。

クエリビルダーでは、フィールドの 引数（arguments） をキー追加型の UI で入力し、field(name: value) の形で生成クエリに出力できます。さらに 入力モードを「変数」に切り替える と、トップレベルの引数が $名前 の名前付き GraphQL 変数に置き換わり、query($名前: 型){ … } と variables（JSON）を生成します。値は 変数マトリクス で入力します。詳しくは クエリビルダー を参照してください。

ヘッダーのカスケード

送信時のヘッダーは、プロジェクト共通 → 環境 → クエリ固有 の順に重ね合わせて（カスケードして）決まります。同じキーがあれば 下位（後ろ）が上書き します。

例: プロジェクト共通で X-App: galleonql、環境で Authorization: Bearer {{token}}、クエリ固有で X-Trace: 1 を持たせると、3 つが合流した最終ヘッダーになる。

送信前には、{{token}} などを選択中環境の実値へ解決した 最終ヘッダー をプレビューで確認できます。カスケードの詳細（認証の位置づけを含む）は 環境の登録・切替 と クエリの送信とレスポンス を参照してください。

HTTP タイムアウトのカスケード

接続タイムアウト（サーバへの接続確立を待つ上限）と全体タイムアウト（応答全体を待つ上限）は、ヘッダーと同じ考え方で アプリの既定値 → プロジェクト → 環境 → クエリ の順に重ね合わせて決まります。空欄にした層は「未設定」として上位の値を継承し、値を入れた層がそこから先を上書きします。

例: プロジェクトでは何も設定せず（アプリの既定である接続 10 秒／全体 60 秒のまま）、応答が遅い環境 Staging だけ全体タイムアウトを 180 秒に設定すると、Staging を使う送信はすべて全体 180 秒になる。

接続タイムアウトと全体タイムアウトはそれぞれ独立にカスケードします（片方だけを上書きしても、もう片方には影響しません）。設定できる範囲は接続 1〜60 秒・全体 1〜600 秒で、0 や無制限は指定できません。設定手順は 環境の登録・切替 の「HTTP タイムアウトを設定する」「HTTP タイムアウトのカスケード」を参照してください。

スキーマ

スキーマ は、GraphQL エンドポイントが公開している型・フィールドの定義一式です。GalleonQL は環境（エンドポイント）ごとに、HTTP イントロスペクション で取得し、ローカルにキャッシュします。取り込んだスキーマは型カタログとして参照でき、クエリビルダーの土台になります。

取り込み手順は スキーマの取り込み、閲覧方法は スキーマドキュメントの参照 を参照してください。

葉（leaf）と枝（branch）

スキーマ上のフィールドは、参照している型の種類によって 葉 と 枝 に分かれます。この区別が、ドキュメントの辿り方やクエリの組み立て方を左右します。

  • 葉（leaf）: 参照先が スカラー / enum のフィールド。それ以上は展開できません。
  • 枝（branch）: 参照先が object / interface / union のフィールド。さらに内側のフィールドを展開（add Child）できます。

例: User.name（String）は葉。User.friends（[User!]）は枝で、内側の name などをさらに展開できる。

add Query / add Child

add Query と add Child は、クエリを段階的に組み立てる操作です。枝を継ぎ足すように、必要なフィールドだけを少しずつ広げてクエリを育てられます。

  • add Query（+ query）: 型カタログのルート型（Query / Mutation / Subscription）のフィールドを、クエリのルートとして挿入します。本体ボタンは常に子なし で追加します。
  • add Child（+ child）: 挿入済みの枝に対して、直下のスカラーのみ を 1 階層展開します。

どちらも本体ボタンと ▼ メニューからなる split button です。▼ から「直下スカラーのみ」「直下すべて」を選ぶと、その 1 回だけ 粒度を上書きできます（固定の既定は変わりません）。詳しい操作は クエリビルダー を参照してください。

subscription（購読）

subscription は、サーバ側で起きた出来事を受け取り続けるための GraphQL の操作です。1 回投げて 1 回返る query / mutation と違い、購読している間はイベントが届くたびに結果が増えていきます。

GalleonQL は、環境ごとに選んだトランスポート——WebSocket（専用の接続にアップグレードする方式） または SSE（通常の HTTP リクエストの応答をイベントストリームとして受け取る方式）——で接続します。 接続先は環境の Subscription URL で、空欄ならリクエスト URL から自動で決まります。 購読を始めると送信ボタンが ■ 停止 に変わり、受信したイベントはレスポンスペインの一覧に積まれます。 同時に購読できるのは 1 本まで、保持できるのは最新 1000 件まで、切断されても自動では再接続しません（トランスポートに関わらず共通です）。

詳しい操作は クエリを送信する を参照してください。

コレクション

コレクション は、クエリ（Query / Mutation / Subscription）を整理して入れておく入れ物（フォルダ）です。ネスト（入れ子）できます。将来的に、個人スコープとチーム共有スコープの二層で扱えるよう設計されています。

プロジェクト

プロジェクト は、環境とコレクションが所属する一番外側の単位です。トップバーのセレクタでプロジェクトを切り替えると、その配下の環境・コレクションに切り替わります。プロジェクト単位での書き出し・読み込みは プロジェクトのエクスポート／インポート を参照してください。

プラン（Free / Pro）

GalleonQL のプランは Free（$0・プロジェクト無制限）と Pro（月額 $9.99 または 年額 $99）の 2 つです。 Pro ではリクエストフック、WebSocket / SSE による GraphQL subscription、スキーマ再取込時の差分確認などが使えます。 どちらのプランでもプロジェクト数の上限はありません。

操作の詳細は プラン（Free / Pro）とライセンス を参照してください。

起動時のライセンス確認（サブスク失効の自動反映）

起動時のライセンス確認 は、Pro のライセンスを登録している場合に、GalleonQL が アプリの起動ごとにオンラインでライセンスの有効性を確認 する仕組みです。これにより、サブスクの解約や失効が、次回起動時に自動でアプリへ反映されます（Free のみのご利用時は行われません）。

  • 有効（サブスク継続中、または解約したが有効期限内）なら、Pro はそのまま維持されます。
  • 失効（期限切れ・無効化・解約して有効期限が過ぎた等）なら、自動的に Free へ戻り、このデバイスからライセンスキーが削除 されます。プロジェクトはロックされません（Free でも無制限です）。
  • オフライン起動 では、最後にオンラインで確認できてから 24 時間以内 かつ 有効期限内 なら一時的に維持され、「ライセンスが確認できません」と表示されます。これを過ぎると Free へ戻ります。オンラインに戻れば自動で再確認されます。

詳しくは プラン（Free / Pro）とライセンス を参照してください。

ライセンスの解除／サブスクの解約

どちらも有料の Pro を手放す操作ですが、請求と Free へ戻るタイミングが異なります。混同しないでください。

  • ライセンスの解除（このデバイスからライセンスを解除）: 即座に Free へ戻り、キーが削除されます。ただし請求は止まりません。
  • サブスクの解約: 請求を止める操作です。Pro は 支払済みの期間が満了したあと、次回のアプリ起動時に自動的に Free へ戻ります（上記「起動時のライセンス確認」による）。

詳しくは プラン（Free / Pro）とライセンス を参照してください。

エラー分類

GalleonQL は、取り込みや送信で発生したエラーを 起因ごとに分類 して表示します。原因の切り分けに役立ちます。

  • ネットワークエラー: 接続失敗・タイムアウト・DNS / TLS の問題など、サーバへ到達できない。
  • 認証エラー: HTTP 401 / 403。認証が必要、またはトークンが無効。
  • クライアント（クエリ）エラー: HTTP 400 など、リクエスト側（URL やクエリ）に問題がある。
  • サーバエラー: HTTP 5xx など、サーバ側に問題がある。
  • 部分エラー: 一部だけ失敗。GraphQL は HTTP 200（成功）でも、応答の中に errors[] を含めて返す ことがあります。

分類ごとの具体的な対処は スキーマの取り込み と クエリの送信とレスポンス を参照してください。

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

リクエストフック は、クエリ送信のあとに評価される宣言的なルールです。レスポンスから値を取り出して 環境変数へ保存する（値の抽出）、またはステータス／ボディ／環境変数を検査してResponse の Hooks タブに成功／失敗を 残す（検証・アサーション）ことができます。スクリプトは使えません。Pro プラン限定です（Free は閲覧のみ）。

詳しくは リクエストフック（値の抽出と検証） を参照してください。

マニュアル全体の目次は 索引 から辿れます。