GraftQL マニュアル
変更履歴

スキーマの取り込み

このページでは、GraphQL エンドポイントのスキーマを GalleonQL に取り込む方法（HTTP イントロスペクションと、ローカルファイル／ディレクトリからの読み込み）を説明します。

スキーマや葉・枝などの用語は 主要な用語 を参照してください。

前提

  • GalleonQL とは／インストールと起動 の手順でアプリが起動していること。
  • トップバーの環境セレクタで、取り込み対象のエンドポイントを指す 環境（接続プロファイル） が選択されていること。環境が 1 件も無いと取り込みは実行できません。環境の作り方は 環境の登録・切替 を参照してください。
  • HTTP で取り込む場合は、対象エンドポイントが イントロスペクションクエリを受け付ける こと（多くのサーバは既定で有効ですが、本番環境では無効化されている場合があります）。
  • 外部への HTTP 通信は GalleonQL 本体（デスクトッププロセス）から発行されます。ブラウザの CORS 制限を受けないため、ブラウザから直接アクセスできない社内 API でも、PC から到達できれば取り込めます。

スキーマを取り込む（HTTP イントロスペクション）

エンドポイント URL・ヘッダー・認証は、右ペインに直接入力するのではなく、トップバーで選択中の環境の設定から解決 されます。

  1. トップバーのセレクタで、取り込み対象の環境を選択します。選択中の環境の解決後エンドポイント URL が、セレクタの横に表示されます。
    • URL には ポート番号を明示 してください。省略すると http:// は 80 番、https:// は 443 番に接続されます。ローカル開発サーバー（例: :8080・:4000）ではポート指定漏れが接続失敗の典型的な原因です。
  2. 認証が必要な場合は、環境エディタの 「認証」節 で方式と秘密を設定します（Authorization を環境ヘッダーに手書きする運用は非推奨）。
    • Bearer: 既定の認証方式に Bearer を選び、「Bearer トークン」にアクセストークンを入力。
    • Basic: 既定の認証方式に Basic を選び、「Basic ユーザー名」「Basic パスワード」を入力。
    • 認証不要: なし（none） のまま。
    • 設定手順の詳細は 環境の登録・切替 を参照してください。
  3. 「スキーマを取り込む」（取り込み済みなら 「⟳ 再取込」）ボタンをクリックすると、HTTP イントロスペクションが実行されます。
  4. 取り込み中は「取込中...」と表示されます。接続のタイムアウトは 10 秒、リクエスト全体のタイムアウトは 60 秒です。この時間内に応答がなければ失敗として扱われます。

取り込みに成功したら

成功すると、右ペイン（見出し「Schema」）に緑色で次のような要約が表示されます。

型定義: 42 件 / Query フィールド: 8 件 ／ 最終取得日時: 2026-07-09 13:45
  • 型定義: スキーマに含まれる全型定義数（Query / Mutation に加え、object・scalar・enum・interface・union などをすべて含む）。
  • Query フィールド: Query ルート直下のフィールド数（Query 型が無い、または 0 件なら 0）。
  • 最終取得日時: そのスキーマを HTTP で取得した日時（ローカル時刻の絶対表示）。キャッシュから表示している場合は、前回 HTTP 取り込みを行った日時 がそのまま表示されます。

要約に続けて 型カタログのツリー が表示されます。見方は スキーマドキュメントの参照 を参照してください。

一部エラーを含む成功（部分エラー）: サーバによっては、応答に data と errors の両方が含まれることがあります。data からスキーマが構築できれば型定義数などは表示されますが、要約の下に黄色地で errors の内容が併記されます。この場合もスキーマは通常どおり使えますが、警告に挙がった型・フィールドは反映されていない可能性があるため内容を確認してください。

ボタンが押せないとき

取り込みボタンが無効化されて押せない場合は、取り込み以前の設定に問題があります。ボタンにマウスを乗せると理由がツールチップで表示されます。

症状 想定される原因 対処
ボタンが常に無効／環境セレクタが「(環境がありません)」 環境が 1 件も登録されていない 環境エディタで環境を追加する
ボタンが無効で、URL 欄が空 リクエスト URL が未設定 環境エディタの「リクエスト URL」を設定する
ボタンが無効で、警告バーに「未解決の変数があります: ...」 {{...}} が参照する環境変数が未定義 参照している環境変数を追加する

ローカルファイル／ディレクトリから取り込む

本番でイントロスペクションが無効化されている、オフラインで作業している、といった理由で HTTP 経由で取得できない場合は、ローカルのスキーマファイルから取り込めます。右ペインの Schema 見出しにある次のボタンを使います（いずれも HTTP は一切発行しません）。

ボタン 操作 用途
ファイルから読込 ファイル選択ダイアログが開く 単一ファイル（JSON または SDL）を読む
ディレクトリから読込 ディレクトリ選択ダイアログが開く フォルダ内（サブフォルダ含む）のスキーマ関連ファイルをまとめて読む

対応フォーマット

形式 拡張子の目安 内容
Introspection JSON .json { "__schema": ... } 形、または HTTP 応答そのままの { "data": { "__schema": ... } } 形
GraphQL SDL .graphql / .gql type Query { ... } などのスキーマ定義テキスト
  • 単一ファイル: 内容の先頭（空白を除く）が { なら JSON、それ以外は SDL として解釈します。
  • ディレクトリ: 配下の .graphql / .gql / .json だけを対象にします（README.md などは無視）。.json があれば相対パスの昇順で最初に成功した有効な Introspection JSON を採用し、JSON が無い／全部失敗なら .graphql / .gql を昇順で結合して 1 つの SDL として読み込みます。分割定義した SDL（型ごとにファイルを分けたもの）をまとめて取り込む用途を想定しています。複数の有効な JSON がある場合は最初の 1 件のみ採用し、マージはしません。

ローカルから読み込んだスキーマも、HTTP 取り込みと同じく解決後 URL をキーにキャッシュされます。内容が空・不正・SDL の構文エラーなどの場合は、右ペインに赤字で [キャッシュ破損] … のエラーが表示されます。内容を直して選び直すか、HTTP 取り込みを試してください。

キャッシュの挙動

取り込んだスキーマは、ローカル（端末内）に自動的にキャッシュされます。これにより、アプリを再起動しても、一度取り込んだエンドポイントは次回起動時から待ち時間なしで再表示 されます。

  • キャッシュキーは「解決後のエンドポイント URL」 です（環境そのものではありません）。異なる環境でも解決結果が同じ URL を指していれば、同じスキーマを共有します。認証やヘッダーが違っても、URL が同じなら一方で取り込んだスキーマがもう一方でも表示される点に注意してください。
  • 起動時・環境切替時はキャッシュを読むだけで、HTTP は発行しません。 数十秒かかることのあるイントロスペクションは、「スキーマを取り込む」「⟳ 再取込」を押したときだけ実行されます。「ファイルから読込」「ディレクトリから読込」も HTTP を発行しません。
  • 自動更新（TTL）はありません。 更新は常に「⟳ 再取込」や「ファイルから読込」による手動操作です。
  • 保存先（macOS の例）は ~/Library/Application Support/jp.trimix.galleonql/galleonql.db です。このファイルには、スキーマキャッシュのほか、登録した環境・最後に選択していた環境・リクエスト履歴も保存されています。ファイルを削除すると、これらもすべて失われます。
  • キャッシュ同士の差分検出（型・フィールドの追加/削除の比較表示）は未実装 です。

まだ一度も取り込んでいないエンドポイントを選ぶと、「まだ取り込まれていません。…」と表示されます。この時点で自動的に HTTP が実行されることはなく、上記のボタン操作が唯一の取り込み経路です。

エラー時の対処

取り込みを実行できてもエラーになった場合、右ペインに赤字で [分類名] メッセージ の形式で表示されます。分類（起因）の意味は次のとおりです。分類の考え方は 主要な用語 の「エラー分類」も参照してください。

分類 主な原因 対処
ネットワークエラー 接続失敗・タイムアウト・DNS / TLS エラーなど、サーバに到達できない メッセージ末尾の詳細を確認。タイムアウトならサーバの応答速度、「接続を確立できません」なら ポート指定漏れ やサーバ起動状況、「ホスト名を解決できません」なら URL のホスト名や VPN 経由の要否、「TLS/証明書の検証に失敗」なら証明書の有効期限・ホスト名一致を確認する
認証エラー HTTP 401 / 403 環境エディタの「認証」節（方式・トークン等）を確認。最終ヘッダーのプレビューで Authorization が載っているか、トークンが失効していないかを見る
クライアント（クエリ）エラー HTTP 400 や、対象がイントロスペクションを許可していない／GraphQL エンドポイントでない URL を指定した URL の末尾パス（/graphql の付け忘れ等）や、サーバ側でイントロスペクションが有効かを確認する。応答が GraphQL 形式でない場合は「有効な GraphQL 応答ではありません。…」と表示される
サーバエラー HTTP 5xx、または応答が不正な形式 サーバ側のログを確認するか、時間を置いて再試行する。継続する場合はサーバ管理者に問い合わせる

キャッシュ関連のエラー

環境選択時のキャッシュ読み込みに失敗した場合も、赤字でエラーが表示されます。これは上記の HTTP エラーとは別分類で、取り込みボタンは押せるままです（回復導線として使えます）。

分類 主な原因 対処
キャッシュ DB エラー ローカルの保存領域の読み書きに失敗（ディスク空き容量不足・ファイル権限の問題など） 「スキーマを取り込む」（または「⟳ 再取込」）を再試行。解消しない場合はディスク空き容量・保存先ファイルの権限を確認する
キャッシュ破損 保存済み JSON の解析やスキーマ構築に失敗。ローカル読込で内容が不正だった場合も同じ分類 「⟳ 再取込」で取り込み直すか、正しいファイル／ディレクトリを選び直すと、正常な内容でキャッシュが上書きされ解消する

なお、取り込み（HTTP）自体は成功したのにキャッシュ保存だけが失敗した場合は、エラー画面には遷移せず、緑字の要約の下に黄色地の警告が表示されます。表示中のスキーマはそのまま使えますが、再起動すると失われます。

関連ドキュメント