GraphQL問合せ

3 GraphQL問合せ

GraphQL問合せは、GraphQLサーバーから特定のデータを要求する方法です。

GraphQL問合せを使用すると、ユーザーは必要な情報を厳密に記述し、サーバーは要求の構造に一致するデータで応答します。出力は要求と完全に一致し、要求以上の情報は返されず、出力が要求以下の情報になることもありません。このアプローチにより、余分な不要な情報を送信したり、関連データを収集するために複数の要求を必要とする従来のAPIとは異なり、クライアントは受け取るデータを正確に制御できます。問合せ型は、基本的にGraphQLスキーマのルートにあるオブジェクト型です。これにはフィールドが含まれており、それぞれがクライアントが問い合せることができる一意のエントリ・ポイントまたはリソースを表しています。問合せ型の各フィールドは、データ取得の個別のエンドポイントに対応しています。フィールドには名前と型が設定され、要求可能な内容と返される内容を明確に定義します。

GraphQL問合せは、次の基本ブロックを使用して記述されます:

問合せ型およびフィールド: 問合せ型は、クライアントが要求できるエントリ・ポイントを定義します。たとえば、カー・レース・スキーマでは次のようになります:
```
type Query {
  driver(id: ID!): Driver
  race(id: ID!): Race
  drivers: [Driver!]!
  races: [Race!]!
}
```
各フィールドには次のものがあることがわかります:
- 戻り型: 返されるオブジェクトまたはプリミティブの種類(ドライバ、レース、リストなど)。前述の例で指定された問合せ型は、driverおよびraceでIDによって特定のドライバまたはレースをフェッチすることを定義しています。driversおよびracesは、使用可能なすべてのドライバおよび競合のリストを返します。
- 引数: 特定のデータをフェッチまたはフィルタリングするためのオプションの入力または必須の入力。前述の例で指定したdriver(id: ID!)のようなフィールドは、フェッチするオブジェクトを指定する引数を受け取ります:
```
query {
  driver(id: "101") {
    name
    team {
      name
    }
  }
}
```
  id引数によってドライバ101が正確にフェッチされるため、取得するデータを調整できます。
- 選択セット: 型から取得するフィールドを正確に指定できるため、オーバーフェッチを最小限に抑えることができます。次の問合せでは、レース名、日付および各ドライバの最終順位と名前が返されます。要求されていないフィールド(laps、podiumなど)は省略されます。
```
query {
  race(id:"202") {
    name 
    date 
    result {
      finalPosition 
      driver {
        name
      }
    }
  }
}
```
フラグメント: フラグメントを使用すると、フィールドのセットを構成し、必要に応じて問合せに含めることができます。これにより、複数の問合せで同じフィールドを問い合せるのではなく、定義済のフラグメントを問い合せるだけで再利用できます。
ディレクティブ: GraphQLディレクティブは、@という接頭辞が付いた注釈で、GraphQLスキーマまたは操作(フィールド、フラグメント、問合せなど)の一部にアタッチして、実行時に実行動作を変更できます。@includeおよび@skipは、標準のGraphQL仕様で定義されている2つのネイティブ・ディレクティブです。Oracleでは、カスタムのGraphQLディレクティブがサポートされています。カスタム・ディレクティブの詳細は、Oracle GraphQLのカスタム・ディレクティブを参照してください。
変数: 変数は、再利用性のために問合せをパラメータ化するのに役立ちます。これにより、問合せが汎用的で再利用可能になります。問合せでフィールド値をハード・コーディングするかわりに、OracleのGraphQL変数を使用すると、値を変数に個別に渡すことができます。使用方法と例は、「GraphQL変数」を参照してください。