環境の登録・切替

接続先ごとの設定をまとめた「環境（接続プロファイル）」を登録・切り替え、環境変数・認証・ヘッダーを設定する操作を説明します。

環境とは（接続プロファイル）（概要）

環境は Postman の「環境（Environment）」に相当する、切り替え可能な接続プロファイルです。 コレクションやクエリの親（中間ノード）ではなく、クエリとは独立して存在します（直交型）。 クエリは環境に依存せずコレクション配下に持ち、送信やスキーマ取込は常に「操作対象 × 選択中の環境」で 組み立てられます。用語は 主要な用語 を参照してください。

前提

• アプリが起動していること（はじめに（インストールと起動））。
• 「環境変数」と「GraphQL 変数」の違いを理解していること（下表・主要な用語）。 混同するとヘッダー・URL の設定を誤ります。

環境変数と GraphQL 変数の違い（混同しないでください）

GalleonQL は 2 種類の「変数」を区別します。本ページで扱うのは環境変数です。

名前付き GraphQL 変数（$id 等）は、クエリビルダーの入力モードを「変数」に切り替えると使えます（クエリビルダー 参照）。

認証の秘密（Bearer トークン・Basic パスワード）は環境変数ではなく、後述の「認証」節に入れてください。

操作手順

1. 環境エディタを開く

ウィンドウの上部に、プロジェクトと環境のセレクタ、そして選択中の環境の解決後 URL が並んでいます。

環境セレクタをクリックすると、そのプロジェクトの環境が一覧で開きます。編集したい行にマウスを重ねると 鉛筆が現れ、クリックすると環境エディタが開きます。開いた時点で選択していた環境が編集対象です。 探索ペインの「環境を編集」からも、選択中の環境のエディタを開けます。

2. 環境を追加する

トップバーの環境セレクタを開き、一覧の下の 「＋ 新しい環境を追加」 を押します。「新しい環境」という 見出しの環境エディタが開くので、環境名やリクエスト URL などを入力して 「完了」 を押します。

• 「完了」を押すまで環境は追加されません。 「キャンセル」・×・Esc・エディタの外側（暗い背景）のクリックで閉じると、入力した内容は破棄されます。
• 新しい環境は、いま選んでいるプロジェクトに追加されます。URL・環境変数・環境ヘッダーは入力しなければ空、 **認証は「なし（none）」**です。
• 追加した環境は、そのまま選択された状態になります。

3. リクエスト URL を設定する

「リクエスト URL」節に、直 URL（例 https://api.example.com/graphql）または環境変数参照 （例 {{baseUrl}}）を入力します。

• 入力欄の下に「解決後: …」のプレビューが表示されます。未解決の {{...}} があると警告されます。
• 送信・スキーマ取込のエンドポイントは、このリクエスト URL を環境変数で解決した値を使います。

3-2. Subscription のトランスポートと接続先を設定する

subscription（購読）を送信するときの接続方式（トランスポート）と接続先です。トランスポートは 「WebSocket」「SSE」のどちらかを選ぶラジオボタンで、既定は WebSocket です。 URL 欄は任意項目 なので、多くの場合は空欄のままで構いません。トランスポートの選択自体は Free プランでも操作できます （購読を送信できるのは Pro プランのみです。クエリを送信する 参照）。

• URL が空欄のときは、リクエスト URL のスキームだけを選んだトランスポートに合わせて置き換えた 値が使われます。

  • WebSocket を選んでいる場合: https://api.example.com/graphql → wss://api.example.com/graphql（http:// → ws://）
  • SSE を選んでいる場合: スキームは置き換えません（https:// / http:// のまま。SSE は 通常の HTTP で接続するためです）

  入力欄の下のプレビューに「解決後: …（リクエスト URL から導出）」と表示されます。

• HTTP と subscription でパスが違うとき（例: /graphql と、WebSocket なら /graphql/ws、 SSE なら /graphql/stream）だけ、この欄に接続先を書きます。書いた値はそのまま使われ、 スキームの置き換えは行いません。

• 直 URL のほか環境変数参照（例: {{wsUrl}} / {{sseUrl}}）も書けます。

• 接続先を決められないとき、または入力した URL のスキームが選んだトランスポートと合わないとき （例: SSE を選んでいるのに ws:// と書いた場合）は、プレビューが警告になり理由が表示されます。 その場合はこの欄を見直すか、選択中のトランスポートを変更してください。

4. 環境変数を追加・編集・削除する

「環境変数」節で「変数名」「値」を入力し、「環境変数を追加」をクリックします。

• 追加済みの変数は、一覧の値欄を直接編集すると即座に更新されます。各行の「削除」で削除できます。
• リクエスト URL やヘッダーの値の中で {{key}} として参照できます。{{ token }} のように 波括弧と変数名の間に空白があっても解決されます。
• 間接参照は 1 段までしか解決されません（後述「制限事項」）。
• 認証の Bearer トークンや Basic パスワードはここに置かないでください（次の「認証」節を使います）。
• 環境変数は手動編集のほか、リクエストフック（送信後の値抽出・検証。上書きするのは 値抽出アクションのみ）によって確認なしで上書きされることがあります。意図しない変更があれば Hooks タブの実行結果を確認してください （リクエストフック（値の抽出と検証））。

変数サジェスト（{{ オートコンプリート）

URL・ヘッダー・変数の値欄で、{{ の後に 1 文字以上打つと候補一覧が開きます。

候補の先頭バッジ:

同名の P と E は別行で出ます。解決時は環境側がプロジェクトを上書きします。認証秘密欄には サジェストは出ません（認証値はテンプレート展開しないため）。

5. 認証（既定方式と秘密）を設定する

「認証」節（見出し左に由来バッジ Au）で、この環境の既定認証方式と秘密を設定します。

• リクエストの Auth タブが「環境の既定を継承」のとき、ここで設定した方式と秘密から Authorization が 自動注入されます（由来 Au）。秘密はエクスポート／インポートされません。
• 認証値は {{...}} を展開しません（秘密をテンプレート経由にしない設計）。トークン欄に {{token}} と 書いても、そのままの文字列が使われます。
• トークンが空の Bearer では Authorization ヘッダー自体を送りません。パスワードが空の Basic は ヘッダーを送ります（空パスワードとして符号化。警告のみ）。

リクエスト側で方式だけを上書きする方法は クエリの送信とレスポンス の 「Auth タブ」を参照してください。

6. 環境リクエストヘッダーを追加・編集・削除する

「環境リクエストヘッダー」節（由来バッジ E）で、この環境固有の HTTP ヘッダーを設定します。

• 「Header」「Value」を入力し、「ヘッダーを追加」をクリックします。
• 値には {{envVar}} のように環境変数を差し込めます（{{ サジェスト可）。
• 追加済みの行は各欄を直接編集すると即座に更新されます。「削除」で削除できます。
• Authorization の手書きは非推奨です（「認証」節を使ってください）。互換のため入力自体はできますが、 環境ヘッダーに書いた Authorization は、その後の認証段（Au）やリクエスト固有ヘッダー（R）で 上書きされます（後述「ヘッダーのカスケード」）。

7. HTTP タイムアウトを設定する

「HTTP タイムアウト」節（由来バッジ E）で、この環境用の接続タイムアウト・全体タイムアウトを 設定します。プロジェクト編集ドロワーにも同じ節があり、こちらはプロジェクト全体の既定値になります。

• 接続タイムアウト（既定 10 秒。1〜60 秒の範囲で指定可）と全体タイムアウト （既定 60 秒。1〜600 秒の範囲で指定可）の 2 つの入力欄があります。
• 入力欄を空欄のままにすると、プロジェクトの設定（さらに未設定ならアプリの既定値）を継承します。 空欄のときは「継承中 60 秒（プロジェクト） / 1〜600 秒」のように、現在有効な秒数・由来・ 許容範囲が表示されます。
• 全角数字は自動的に半角へ正規化して保存されます（１０ → 10。エラーにはなりません）。
• 数字以外の文字（小数点・記号など）は入力からその場で取り除かれ、「数字以外は入力できません」 と通知されます。取り除いた後に残った数字がそのまま秒数として保存されるため、1.5 と入力すると . が消えて 15 秒として保存されます（10.5 は 105 秒）。意図した秒数と違う値に なっていないか、必ず入力欄の表示を確認してください。
• 範囲外の整数を入力した場合のみエラー表示され、保存されません（UI から起こり得る唯一の エラーです）。
• 0 や無制限は指定できません（サーバーからの応答が返らないまま、アプリが待ち続けるのを防ぐためです）。
• ここで設定した値は、この環境を使うすべてのクエリ送信・スキーマ取込に適用されます （リクエストの Headers タブで個別に上書きしていない場合）。

8. 環境名を変更する・環境を削除する

• 環境エディタの「環境名」欄を編集すると、その環境の名前が即座に変わります。
• 環境を削除するには、環境エディタの一番下にある 「この環境を削除」 を押し、確認のダイアログで 「削除する」 を押します。削除は取り消せません。
• すべて削除して 0 件にもできます（ただしその場合スキーマ取込は実行できません）。
• 選択中の環境を削除した場合、残っている環境のうち先頭のものが自動的に選択されます。

9. 環境を切り替える

トップバーの環境セレクタで切り替えたい環境を選ぶと、解決後の URL、リクエストペインの Headers タブの最終ヘッダー プレビュー、認証の Authorization が即座に切り替わります。プロジェクトに環境が 1 件も無いときは、 セレクタに「—」と表示され、開いた一覧には「このプロジェクトに環境がありません」と出ます。

設定例

HTTP タイムアウトの設定例（応答が遅いステージング環境だけ全体タイムアウトを延ばす）:

ヘッダーのカスケード（プロジェクト → 環境 → 認証 → リクエスト）

送信されるヘッダーは次の順にマージされ、同じヘッダー名は下位が上位を上書きします。

1. アプリ組み込み（由来 A。例: User-Agent）
2. プロジェクト共通ヘッダー（P）
3. 環境リクエストヘッダー（E）
4. 認証（方式＋秘密から組み立てた Authorization。Au）
5. リクエスト固有ヘッダー（R）

• 優先順位: リクエスト ＞ 認証 ＞ 環境 ＞ プロジェクト ＞ アプリ。
• ヘッダー名の照合は大文字・小文字を区別しません（content-type と Content-Type は同一ヘッダーとして 1 件に畳まれ、最終的な表示名は勝った側のものになります）。
• リクエストペインの Headers タブに「送信される最終ヘッダー」プレビューが出て、キー・解決後の値・由来バッジが 表示されます。このプレビューは実際の送信と同じ解決結果です （クエリの送信とレスポンス）。

HTTP タイムアウトのカスケード（既定値 → プロジェクト → 環境 → クエリ）

HTTP タイムアウト（接続／全体）も、ヘッダーと同じ「上位から順に載せ、値があれば後勝ち」という 規則で決まります。

1. 既定値（接続 10 秒／全体 60 秒）
2. プロジェクト（プロジェクト編集ドロワーの「HTTP タイムアウト」節）
3. 環境（本ページの「HTTP タイムアウトを設定する」節）
4. クエリ（リクエストペインの Headers タブ「HTTP タイムアウト（このクエリ）」節。 クエリの送信とレスポンス 参照）

ヘッダーのカスケードとの違いは、タイムアウトには認証の段がないこと、そして接続タイムアウトと 全体タイムアウトが完全に独立してカスケードすることです。例えば、全体タイムアウトだけを環境で 延ばしても、接続タイムアウトはプロジェクトの設定（または既定の 10 秒）のまま変わりません。

各入力欄が空欄のときは、その一つ上位までの実効値・由来・許容範囲が「継承中 N 秒（由来） / 下限〜上限 秒」として表示されるため、値を入れなくても、いま何秒が使われるかを確認できます。

スキーマ取込（イントロスペクション）にはクエリの層がないため、既定値→プロジェクト→環境の3段で 解決されます（スキーマの取り込み 参照）。

永続化と復元

環境（名前・環境変数・環境ヘッダー・認証の方式と秘密）と、最後に選択していた環境は、追加・編集・削除・ 切替のたびに端末内へ自動保存されます。「保存」操作は不要です。アプリを再起動すると、登録した環境一覧と 最後に選択していた環境がそのまま復元されます。この復元では HTTP を一切発行しません。

• 初回起動時（環境が 1 件も保存されていない場合）は、サンプル環境「Default」（上の設定例の 1 行目・ Bearer トークン dev-local を含む）が 1 件自動作成されます。
• 環境を切り替えて解決後の URL が変わると、その URL のスキーマキャッシュが自動的に読み込まれ、 表示中のスキーマ・クエリビルダーがその URL のものに切り替わります（HTTP は発行しません）。 まだ取り込んでいない URL の場合、同じプロジェクトの中では、それまで表示していたスキーマがそのまま残ります （「まだ取り込まれていません」の案内に変わるのは、表示中のスキーマが無いときだけです。条件は スキーマの取り込み の「キャッシュの挙動」）。新しい エンドポイントのスキーマを取得するには、切り替え後に改めて「⟳ 取込」（または「⟳ 再取込」）を 実行してください（スキーマの取り込み）。

🚨 認証トークン等は暗号化されずに保存されます

認証の秘密（Bearer トークン・Basic パスワード）や、環境変数・環境ヘッダーの値は、暗号化されず 平文のまま端末内に保存されます。アプリデータは OS のユーザー領域にあり他の OS ユーザーからは 読めませんが、ディスク上に平文が残る点は変わりません。これは意図的な決定で、Postman や Insomnia など 同種のローカルツールも平文で保存しています。トークンやパスワードを入力する際は、この点を踏まえて 取り扱ってください。

現時点での制限事項

• 認証方式は なし（none）／ Bearer ／ Basic のみです（いずれも Authorization ヘッダーで完結）。 OAuth2 Client Credentials は対応済みです。API Key・OAuth2 Authorization Code・カスタムヘッダー認証は未対応です。
• 認証値は環境変数（{{...}}）で解決されません。
• 環境変数の間接参照は 1 段までしか解決されません。 例えば apiHost の値が {{host}} という別の 変数参照でも、host までは自動的に追いません（無限ループ防止のための意図的な制約）。この場合 置換後に {{host}} が残り、未解決として警告されます。多段が必要なら参照先の値を直接展開して 登録してください。
• Authorization の手書きは非推奨です（「認証」節を使ってください）。

うまくいかないときは

関連ドキュメント

• スキーマの取り込みでの利用: スキーマの取り込み
• リクエストの Auth タブ・送信時の Authorization: クエリの送信とレスポンス
• 送信後の値抽出・検証（リクエストフック）: リクエストフック（値の抽出と検証）
• クエリの組み立て: クエリビルダー
• 環境の並べ替え: 並べ替えと移動
• 用語: 主要な用語
• 索引に戻る: ユーザーマニュアル目次