GraphQL スキーマ - AWS AppSync GraphQL

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

GraphQL スキーマ

GraphQL スキーマは GraphQL API の基盤です。データの形状を定義する設計図として機能します。また、データの取得方法や変更方法を定義する、クライアントとサーバー間の契約でもあります。

GraphQL スキーマは スキーマ定義言語 (SDL) で記述されています。SDL は、構造が確立された型とフィールドで構成されています。

  • タイプ: タイプとは、GraphQL がデータの形状と動作を定義する方法です。GraphQL は、このセクションの後半で説明する多数の型をサポートしています。スキーマで定義されている各タイプには、独自のスコープが含まれます。スコープ内には、GraphQL サービスで使用される値またはロジックを含むことができる 1 つ以上のフィールドがあります。型にはさまざまな役割がありますが、最も一般的なのはオブジェクトまたはスカラー (プリミティブ値型) です。

  • フィールド: フィールドはタイプのスコープ内に存在し、GraphQL サービスから要求された値を保持します。これらは他のプログラミング言語の変数とよく似ています。フィールドで定義するデータの形状によって、リクエスト/レスポンス操作におけるデータの構造が決まります。これにより、開発者はサービスのバックエンドがどのように実装されているかを知らなくても、何が返されるかを予測できます。

スキーマがどのようなものかを視覚化するために、単純な GraphQL スキーマの内容を確認してみましょう。プロダクションコードでは、スキーマは通常、schema.graphql または schema.json というファイルにあります。GraphQL サービスを実装するプロジェクトを覗き見していると仮定しましょう。このプロジェクトには会社の人事データが保存されており、schema.graphql ファイルを使用して人事データを取得したり、データベースに新しい人員を追加したりしています。コードは次のようになります。

schema.graphql
type Person {                                  
   id: ID!
   name: String                                  
   age: Int
}
type Query {                                   
  people: [Person]
}
type Mutation {
  addPerson(id: ID!, name: String, age: Int): Person
}

スキーマには、Person、Query、Mutation の 3 つのタイプが定義されていることがわかります。Person を見てみると、これが会社の従業員のインスタンスの設計図であり、それによってこの型がオブジェクトになることが推測できます。そのスコープ内には、id、name、age があります。これらは Person のプロパティを定義するフィールドです。つまり、データソースはそれぞれのPersonのnameをStringスカラー (プリミティブ) タイプとして、age をスカラー (プリミティブ) タイプとして格納します。id はそれぞれの Person に対して固有の特別な識別子として機能します。! 記号で示されているように、これは必須の値でもあります。

次の 2 つのオブジェクトタイプは動作が異なります。GraphQL は、スキーマへのデータの入力方法を定義する特別なオブジェクトタイプ用にいくつかのキーワードを予約しています。Query タイプはソースからデータを取得します。この例では、クエリはデータベースから Person オブジェクトを取得する場合があります。これは、RESTful 用語で使われる GET 操作を思い起こさせるかもしれません。Mutation はデータを変更します. この例では、ミューテーションによってデータベースにさらに Person オブジェクトが追加される可能性があります。これにより、PUT や POST のような状態を変更する操作を思い起こさせるかもしれません。特殊なオブジェクトタイプの動作については、このセクションの後半で説明します。

この例では、Query がデータベースから何かを取得すると仮定しましょう。Query のフィールドを見ると、people というフィールドが 1 つあります。フィールドの値は [Person] です。つまり、データベース内の Person の一部のインスタンスを取得したいということです。ただし、括弧を追加すると、特定のインスタンスだけでなく、すべての Person インスタンスのリストを返したいということになります。

データ変更などの状態を変更する操作は Mutation タイプが担当します。ミューテーションは、データソースに対して何らかの状態変更操作を実行する役割を果たします。この例では、データベースに新しい addPerson オブジェクトを追加する Person という操作がミューテーションに含まれています。このミューテーションは Person を使用し、id、name、age フィールドへの入力を期待しています。

この時点で、このような操作は何らかの動作を行い、関数名とパラメータを持つ関数によく似ているはずなのに、コード実装なしで addPerson がどのように動作するのか疑問に思われるかもしれません。現在のところ、スキーマは宣言の役割を果たすだけなので、機能しません。addPerson の動作を実装するには、リゾルバーを追加する必要があります。リゾルバーは、関連するフィールド (この場合は addPerson オペレーション) が呼び出されるたびに実行されるコードの単位です。オペレーションを使いたい場合は、どこかの時点でリゾルバーの実装を追加する必要があります。ある意味では、スキーマ操作は関数宣言、リゾルバーは定義と考えることができます。リゾルバーについては別のセクションで説明します。

この例は、スキーマがデータを操作する最も簡単な方法のみを示しています。GraphQL と AWS AppSync の機能を活用して、複雑で堅牢でスケーラブルなアプリケーションを構築します。次のセクションでは、スキーマで使用できるさまざまなタイプとフィールドの動作をすべて定義します。

ご覧のとおり、GraphQL には動くコンポーネントがたくさんあります。このセクションでは、単純なスキーマの構造と、スキーマがサポートするさまざまなタイプとフィールドを示しました。次のセクションでは、GraphQL API の他のコンポーネントと、それらがスキーマとどのように連携するかを説明します。