GraphQL

GraphQLリクエストは、クエリ、その変数、クエリが対象とするスキーマで構成されます。Echolotはスキーマを使って、入力中にフィールドを補完し、送信前に間違いを示し、レスポンスの横に型を表示します。

GraphQLリクエストを作成するCopy Anchor Link

ファイル › 新規GraphQLリクエストを選ぶか、サイドバーのリクエストの横にある+メニューから新規GraphQLリクエストを選びます。 アドレス欄にエンドポイントを入力します。デモショップなら{{baseURL}}/graphqlです。Alpenglowワークスペースには、用意済みのものが1つあります：Catalog › Search products。

エディタのタブは次のとおりです：ドキュメント、クエリ、変数、ヘッダー、パラメータ、認証、変数（リクエスト自身の変数）、テスト、スクリプト、設定。 ヘッダー、認証、テスト、スクリプトは、HTTPリクエストと同じように動作します。

クエリと変数Copy Anchor Link

クエリはクエリタブに書きます：

query SearchProducts($text: String!, $first: Int = 10) {
  search(text: $text, first: $first) {
    totalCount
    nodes { sku name price { amount currency } rating stock { warehouse available } }
  }
}

変数は変数タブにJSONで書きます。JSONの中では{{variables}}が使えます：

{
  "text": "{{searchTerm}}"
}

ドキュメントに複数のオペレーションがある場合は、クエリの上のオペレーションに、送信するものを入力します。オペレーションが1つのドキュメントでは、空のままにします。

送信は送信または⌘Rで行います。

リクエストの送信方法Copy Anchor Link

アドレスの前にあるGQLバッジはメニューになっています。送信方法の選択肢：

その下にスイッチが2つあります：

• 永続化クエリ（APQ）は、最初にクエリ本文なしで、クエリのSHA-256ハッシュを送信します。サーバがそのハッシュを知らないと答えると、Echolotはクエリ付きで再送するので、サーバはクエリを保存できます。
• すべてのオペレーションをバッチ処理は、ドキュメント内の名前付きオペレーションをすべて、1つのJSON配列としてまとめて送信します。

スキーマCopy Anchor Link

スキーマメニューはクエリタブの右側にあります。スキーマファイルと型の数（shop.graphql · … typesなど）、またはスキーマなしが表示されます。

• サーバから取得は、リクエストのアドレスに対してイントロスペクションクエリを実行し、結果をワークスペースのspecs/フォルダにファイルとして保存します。もう一度選ぶと、スキーマが更新されます。
• スキーマを使用は、ワークスペースにすでにあるスキーマファイル（.graphql、.graphqls、.json）を一覧して選べます。
• スキーマファイルを追加…は、Macから、SDLファイル（.graphql）またはイントロスペクションの結果（.json）を取り込みます。
• スキーマエクスプローラを表示は、レスポンスの横にスキーマを開きます。
• このスキーマの使用を停止は、リクエストからスキーマを外します。

specs/内のスキーマファイルは、そのサーバに対するすべてのGraphQLリクエストで共有でき、ワークスペースとともにコミットできます。 取得によってスキーマファイルが置き換えられ、スキーマが変更されていると、スキーマが変更されましたに変更が破壊的、危険、安全に分けて一覧されます。たとえば、フィールドの削除や、必須引数の追加です。 破壊的な変更とは、削除または変更されたものを使うクエリが失敗するようになる変更のことです。 コマンドラインでは、echolot graphql diffが同じ方法で2つのスキーマを比較します。echolot graphqlを参照してください。

スキーマを読み込めないと、メニューにスキーマの問題と表示され、クエリの下のバーに理由が表示されます。

補完、問題、ホバーCopy Anchor Link

スキーマがあると、クエリエディタは入力中に次のように支援します：

• 補完は、カーソルの位置に合うフィールド、引数、入力フィールド、型、enumの値、変数、ディレクティブ、フラグメントを、ドキュメントとともに提案します。非推奨のものには印が付きます。
• 問題は、入力中に下線で示されます。不明なフィールド、引数の型の誤り、必須引数の不足などです。クエリの下のバーには最初の問題が表示され、エラーと警告の数も表示されます。 ポインタを合わせると、すべて読めます。
• ホバー：フィールドや型にポインタを合わせると、シグネチャとドキュメント、非推奨かどうかが表示されます。
• フィールドや型を⌘クリックすると、その型がスキーマエクスプローラで開きます。

スキーマエクスプローラとビルダーCopy Anchor Link

レスポンスペインのスキーマタブには、最初の送信前でも、リクエストのスキーマが表示されます。リクエストにまだスキーマがなければ、そこでサーバから取得を選びます。

探索はエントリポイント（クエリ、Mutation、Subscription）から始まります。型をクリックすると、そのフィールド、入力フィールド、enumの値、またはそれを実装する型や所属する型が、非推奨の印付きで表示されます。 戻るボタンで前の型に戻ります。型とフィールドを検索で、スキーマ内のあらゆるものを名前で探せます。

構築は、クエリを自動で書いてくれます。オペレーションの下でクエリ、mutation、subscriptionのいずれかを選び、ツリーでフィールドにチェックを入れます。 チェックを入れるたびにフィールドがクエリのテキストに追加され、外すと取り除かれます。自分で入力した部分は残ります。 ビルダーは、オペレーションで指定した名前のオペレーション、または指定がなければドキュメント内のその種類の最初のオペレーションに対して動作します。なければ、新しく追加します。

レスポンスCopy Anchor Link

レスポンスは、ほかのレスポンスと同じように、ボディタブにJSONとして表示されます。Echolotは、データとともにGraphQLが伝える内容も読み取ります：

• レスポンスの概要のN件のGraphQLエラー：サーバがerrors配列を送信しています。HTTP 200でも表示されます。クリックすると、各メッセージとそのパスを読めます。
• 部分的なデータ：データとエラーが一緒に返され、失敗したフィールドはnullになっています。
• Extensions：トレースやコスト情報など、レスポンスのextensions。

テストタブに0と等しいGraphQLエラーのチェックを追加すると、エラーがあれば実行を失敗させられます。スクリプトとテストを参照してください。

サブスクリプションとインクリメンタルデリバリーCopy Anchor Link

サブスクリプションは、終了するまで結果を送り続けます：

• HTTP（POSTまたはGET）では、オペレーションがサブスクリプションのとき、Echolotはサーバー送信イベントを要求します。
• WebSocket（graphql-transport-ws）では、EcholotはWebSocketを開き、リクエストのヘッダーと認証でサブスクリプションを送信し、サーバのpingに応答します。

@deferや@streamを使ったクエリは、複数の部分（multipart/mixed）として返ります。

どちらの場合も、レスポンスペインにイベントタブが加わります。各イベントまたは部分が順番に番号付きで、種類（nextやpartなど）、ID、エラーとともに表示されます。 @deferと@streamでは、上部のマージされた結果に、最初の結果にその後のすべての部分を適用したものが表示されます。ストリームの実行中、タブは新しいイベントを追って表示し、受信待機中…「停止」で終了します。と表示します。 終了するにはキャンセル（⌘.）を選びます。開始済みのストリームは、リクエスト全体のタイムアウトでは切断されません。

ファイルのアップロードCopy Anchor Link

Upload変数を持つミューテーションでは、変数タブの変数用のファイルにファイルを追加します：

1. +を選びます。
2. 変数を入力します。たとえばfile、リストの最初の項目ならfiles.0です。
3. ワークスペースからの相対パスで、ファイルのパスを入力します。

POSTはGraphQL multipart request specに従います。変数はoperationsではnullになり、ファイルは専用のパートに入ります。