# GraphQL (/ja/docs/requests/graphql)

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

<Shot id="requests-graphql-query" alt="Catalog › Search products：SearchProductsクエリを表示したクエリタブ。スキーマメニューにshop.graphqlと型の数が表示され、totalCountとnodesを含むJSONレスポンスがある" />

## GraphQLリクエストを作成する [#create-a-graphql-request]

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

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

## クエリと変数 [#query-and-variables]

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

```graphql
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}}`が使えます：

```json
{
  "text": "{{searchTerm}}"
}
```

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

送信は**送信**または<kbd>⌘</kbd><kbd>R</kbd>で行います。

## リクエストの送信方法 [#how-the-request-is-sent]

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

| 選択肢 | 送信する内容 |
| --- | --- |
| **POST（JSONボディ）** | `query`、`variables`、`operationName`をJSONにしたPOST。通常の方法 |
| **GET（URLに含める）** | `query`、`variables`、`operationName`をクエリパラメータにしたもの。GETリクエストをキャッシュするサーバ向け |
| **WebSocket（graphql-transport-ws）** | `graphql-transport-ws`プロトコルのWebSocket。サブスクリプション向け |

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

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

## スキーマ [#the-schema]

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

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

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

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

## 補完、問題、ホバー [#completion-problems-and-hover]

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

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

## スキーマエクスプローラとビルダー [#the-schema-explorer-and-the-builder]

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

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

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

<Shot id="requests-graphql-builder" alt="Search productsの構築を表示したスキーマタブ。searchにチェックが入り、nodesが開いていて、sku、name、priceにチェックが入っている。隣のクエリに同じフィールドが表示されている" />

## レスポンス [#responses]

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

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

**テスト**タブに`0`と等しい**GraphQLエラー**のチェックを追加すると、エラーがあれば実行を失敗させられます。[スクリプトとテスト](/docs/requests/scripts-and-tests)を参照してください。

## サブスクリプションとインクリメンタルデリバリー [#subscriptions-and-incremental-delivery]

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

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

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

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

## ファイルのアップロード [#file-uploads]

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

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

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