スキーマの設計

GraphQL スキーマは、あらゆる GraphQL サーバー実装の基盤です。各 GraphQL API は単一の GraphQL スキーマで定義されます。GraphQL 型システムは GraphQL サーバーの機能を記述し、クエリが有効かどうかを判断するために使用されます。サーバーのタイプシステムは、そのサーバーのスキーマと呼ばれます。これは、オブジェクトタイプ、スカラー、入力タイプ、インターフェイス、列挙、ユニオンのセットで構成されます。API および実行可能なオペレーションも通過するデータの形状を定義します。GraphQL は厳密に型指定されたプロトコルで、すべてのデータオペレーションはこのスキーマに対して検証されます。

AWS AppSyncGraphQL スキーマを定義および設定できます。次のセクションでは、AWS AppSyncのサービスを使用して GraphQL スキーマをゼロから作成する方法について説明します。

空のスキーマの作成

スキーマファイルはテキストファイルであり、通常は schema.graphql という名前です。AWS AppSync ユーザーは、コンソール、CLI、または API を使用して GraphQL API 用の新しいスキーマを作成できます。この例では、空白の API と空白のスキーマを作成します。

Console

1. AWS Management Console にサインインして、AppSync コンソールを開きます。

   1. API ダッシュボードで、お使いの GraphQL API を選択します。

   2. サイドバーで「スキーマ」を選択します。

2. 「スキーマ」AWS AppSync ウィンドウに以下を追加することで、schema.graphqlファイルを設定して送信できます。

   schema {
   }

3. [Save schema] を選択します。

   注記

   すべてのスキーマは、schema処理のためにルートから始まります。これは、ルートクエリ型を追加するまでは処理に失敗します。

API

1. API を呼び出して GraphQL CreateGraphqlApiAPI オブジェクトを作成します。

2. StartSchemaCreation API を呼び出します。

CLI

1. まだAWS CLI のインストールを行ってから、設定を追加します。

2. create-graphql-apiコマンドを実行して GraphQL API オブジェクトを作成します。

   この特定のコマンドには、次の 2 つのパラメータを入力する必要があります。

   1. お使いの APIname のです。

   2. authentication-type、または API へのアクセスに使用される認証情報のタイプ (IAM、OIDC など)。

   注記

   このようなパラメータは他にも設定する必要がありますが、Region通常はデフォルトで CLI 設定値になります。

   サンプルコマンドは、次のようになります。

   aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY

   出力は CLI に返されます。例を示します。

   {
       "graphqlApi": {
           "xrayEnabled": false,
           "name": "testAPI123",
           "authenticationType": "API_KEY",
           "tags": {},
           "apiId": "abcdefghijklmnopqrstuvwxyz",
           "uris": {
               "GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql",
               "REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
           },
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz"
       }
   }

3. start-schema-creation コマンドを実行します。

   この特定のコマンドには、次の 2 つのパラメータを入力する必要があります。

   1. api-id前のステップからのあなた。

   2. スキーマはdefinition、Base64 でエンコードされたバイナリブロブです。

   サンプルコマンドは、次のようになります。

    aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"

   出力が返されます。

   {
       "status": "PROCESSING"
   }

   このコマンドは、処理後の最終出力を返しません。結果を確認するにはget-schema-creation-status、別のコマンドを使用する必要があります。この 2 つのコマンドは非同期なので、スキーマの作成中でも出力ステータスを確認できることに注意してください。

ルートクエリタイプの追加

各 GraphQL スキーマにはルートクエリタイプが必要です。これらは GraphQL サーバーのエントリポイント (またはエンドポイント) と考えることができます。

このガイドでは、Todoサンプルアプリケーションを作成します。QuerygetTodosTodoオブジェクトを含むリストを返す単一フィールドという名前のルートタイプを追加します。

Console

1. AWS Management Console にサインインして、AppSync コンソールを開きます。

   1. API ダッシュボードで、お使いの GraphQL API を選択します。

   2. サイドバーで「スキーマ」を選択します。

2. 次のコードを schema.graphql ファイルに追加します。

   schema {
       query:Query
   }
   
   type Query {
       getTodos: [Todo]
   }

API

1. UpdateTypeAPI を呼び出してルートスキーマを更新します。

2. CreateTypeAPIQuery を呼び出してタイプを作成します。

CLI

1. update-typeコマンドを実行してルートスキーマを更新します。

   この特定のコマンドには、いくつかのパラメータを入力する必要があります。

   1. お使いの APIapi-id のです。

   2. type-nameあなたのタイプの。コンソールの例では、これでしたSchema。

   3. definition、またはあなたのタイプのコンテンツ。コンソールの例では、これは

      schema {
          query:Query
      }

   4. format入力の。この例では、を使用していますSDL。

   サンプルコマンドは、次のようになります。

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query:Query}" --format SDL

   出力は CLI に返されます。例を示します。

   {
       "type": {
           "definition": "schema {query:Query}",
           "name": "schema",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

2. Querycreate-typeコマンドを実行してタイプを作成します。

   この特定のコマンドには、いくつかのパラメータを入力する必要があります。

   1. お使いの APIapi-id のです。

   2. definition、またはあなたのタイプのコンテンツ。コンソールの例では、これは

      type Query {
          getTodos: [Todo]
      }

   3. format入力の。この例では、を使用していますSDL。

   サンプルコマンドは、次のようになります。

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getTodos: [Todos]}" --format SDL

   出力は CLI に返されます。例を示します。

   {
       "type": {
           "definition": "Query {getTodos: [Todos]}",
           "name": "Query",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
           "format": "SDL"
       }
   }

Todo オブジェクト型をまだ定義していないことに注目してください。では、それを定義しましょう。

ToDo タイプの定義

前のセクションでは、Todo動作を定義せずにオブジェクトタイプを宣言しました。

Console

1. AWS Management Console にサインインして、AppSync コンソールを開きます。

   1. API ダッシュボードで、お使いの GraphQL API を選択します。

   2. サイドバーで「スキーマ」を選択します。

2. ここで、Todo オブジェクトのデータが保存される型を作成します。

   schema {
       query:Query
   }
   
   type Query {
       getTodos: [Todo]
   }
   
   type Todo {
       id: ID!
       name: String
       description: String
       priority: Int
   }

API

• CreateTypeAPITodo を呼び出してタイプを作成します。

CLI

• Todocreate-typeコマンドを実行してタイプを作成します。

  この特定のコマンドには、いくつかのパラメータを入力する必要があります。

  1. お使いの APIapi-id のです。

  2. definition、またはあなたのタイプのコンテンツ。コンソールの例では、これは

     type Todo {
         id: ID!
         name: String
         description: String
         priority: Int
     }

  3. format入力の。この例では、を使用していますSDL。

  サンプルコマンドは、次のようになります。

  aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Todo{id:ID! name:String description:String priority:Int}" --format SDL

  出力は CLI に返されます。例を示します。

  {
      "type": {
          "definition": "type Todo{id:ID! name:String description:String priority:Int}",
          "name": "Todo",
          "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Todo",
          "format": "SDL"
      }
  }

Todoオブジェクト型には、文字列や整数などのスカラー型のフィールドがあることに注意してください。AWS AppSync スキーマで使用できるベース GraphQL スカラーに加えて、も強化しました。AWS AppSync名前が感嘆符で終わっているフィールドは必須フィールドです。ID スカラー型は、String または Int のいずれかである一意の識別子です。これらのフィールドは、リゾルバーのコードで自動割り当てを制御できます。

Query 型と Todo 型は類似しています。GraphQL では、ルート型 (つまり、Query、Mutation、Subscription) は、ユーザー定義の型と同様ですが、API のエントリポイントとしてスキーマから公開される点が異なります。詳細については、クエリとミューテーション型を参照してください。

ミューテーションタイプの追加

オブジェクト型を定義して、データをクエリできるので、API を介してデータを追加、更新、または削除する場合は、スキーマにミューテーション型を追加しておく必要があります。この Todo の例では、ミューテーション型に addTodo という名前のフィールドとして追加します。

Console

1. AWS Management Console にサインインして、AppSync コンソールを開きます。

   1. API ダッシュボードで、お使いの GraphQL API を選択します。

   2. サイドバーで「スキーマ」を選択します。

2. ミューテーションをスキーマに追加し、そのタイプを定義します。

   schema {
       query:Query
       mutation: Mutation
   }
   
   type Query {
       getTodos: [Todo]
   }
   
   type Mutation {
       addTodo(id: ID!, name: String, description: String, priority: Int): Todo
   }
   
   type Todo {
       id: ID!
       name: String
       description: String
       priority: Int
   }

API

• CreateTypeAPITodo を呼び出してタイプを作成します。

CLI

1. update-typeコマンドを実行してルートスキーマを更新します。

   この特定のコマンドには、いくつかのパラメータを入力する必要があります。

   1. お使いの APIapi-id のです。

   2. type-nameあなたのタイプの。コンソールの例では、これでしたSchema。

   3. definition、またはあなたのタイプのコンテンツ。コンソールの例では、これは

      schema {
          query:Query
          mutation: Mutation
      }

   4. format入力の。この例では、を使用していますSDL。

   サンプルコマンドは、次のようになります。

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query:Query mutation: Mutation}" --format SDL

   出力は CLI に返されます。例を示します。

   {
       "type": {
           "definition": "schema {query:Query mutation: Mutation}",
           "name": "schema",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

2. Mutationcreate-typeコマンドを実行してタイプを作成します。

   この特定のコマンドには、いくつかのパラメータを入力する必要があります。

   1. お使いの APIapi-id のです。

   2. definition、またはあなたのタイプのコンテンツ。コンソールの例では、これは

      type Mutation {
          addTodo(id: ID!, name: String, description: String, priority: Int): Todo
      }

   3. format入力の。この例では、を使用していますSDL。

   サンプルコマンドは、次のようになります。

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addTodo(id: ID! name: String description: String priority: Int): Todo}" --format SDL

   出力は CLI に返されます。例を示します。

   {
       "type": {
           "definition": "type Mutation {addTodo(id: ID! name: String description: String priority: Int): Todo}",
           "name": "Mutation",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation",
           "format": "SDL"
       }
   }

ミューテーションはルート型であるため、このスキーマにも追加していることに注意してください。

ステータス付きの To Do サンプルの修正

この時点で、GraphQL APITodo は構造的にオブジェクトの読み取りと書き込みで機能しています。データソースがないだけです。これについては次のセクションで説明します。この API をより高度な機能で変更できます。たとえば、として定義されている一連の値から取得されるステータスを自分に追加できますTodoENUM。例えば、以下のスニペットを参照してください。

schema {
    query:Query
    mutation: Mutation
}

type Query {
    getTodos: [Todo]
}

type Mutation {
    addTodo(id: ID!, name: String, description: String, priority: Int, status: TodoStatus): Todo
}

type Todo {
    id: ID!
    name: String
    description: String
    priority: Int
    status: TodoStatus
}

enum TodoStatus {
    done
    pending
}

ENUM は文字列に類似していますが、一連の値のいずれかを取ります。この例では、この型を追加し、Todo を変更し、この機能を持つ Todo フィールドを追加しています。

注記

「データソースの添付」に直接飛ばして、スキーマをデータソースに接続し始めることも、読み続けてページネーションやリレーショナル構造を使ってスキーマを変更することもできます。

サブスクリプション

AWS AppSync のサブスクリプションはミューテーションに対する応答として呼び出されます。サブスクリプションは、Subscription 型と @aws_subscribe() ディレクティブを使用してスキーマで設定して、どのミューテーションが 1 つまたは複数のサブスクリプションを呼び出すかを示します。サブスクリプションの設定について詳しくは、「リアルタイムデータ」を参照してください。

リレーションとページネーション (上級者向け)

百万個の todos があるとします。それらのすべてを毎回取得することは望ましくないため、代わりにそれらをページ分割します。スキーマを次のように変更します。

• getTodos フィールドに limit と nextToken の 2 つの入力引数を追加します。

• todos フィールドと nextToken フィールドを持つ新しい TodoConnection 型を追加します。

• getTodos を変更し、TodoConnection (Todo のリストではない) を返すようにします。

schema {
    query:Query
    mutation: Mutation
}

type Query {
    getTodos(limit: Int, nextToken: String): TodoConnection
}

type Mutation {
    addTodo(id: ID!, name: String, description: String, priority: Int, status: TodoStatus): Todo
}

type Todo {
    id: ID!
    name: String
    description: String
    priority: Int
    status: TodoStatus
}

type TodoConnection {
    todos: [Todo]
    nextToken: String
}

enum TodoStatus {
    done
    pending
}

TodoConnection 型により、todos のリストと、次の nextToken のバッチを取得するための todos を返すことができるようになります。これは 1 つの TodoConnection であり、接続のリストではないことに注意してください。接続内は、ページ分割トークンで返される todo 項目 ([Todo]) のリストです。ではAWS AppSync、これはリゾルバを使用して Amazon DynamoDB に接続され、暗号化されたトークンとして自動的に生成されます。マッピングテンプレートにより、limit 引数の値は maxResults パラメータに変換され、nextToken 引数の値は exclusiveStartKey パラメータに変換されます。AWS AppSync コンソールの例と組み込みテンプレートサンプルについては、VTLのリゾルバーリファレンス (JavaScript) JavaScript またはVTLのリゾルバーマッピングテンプレートリファレンス (VTL) を参照してください。

次に、Todo にコメントフィールドがあり、1 つの todo に対するすべてのコメントを返すクエリを実行することを考えます。これは完全に処理されますGraphQL connections。次のように、Comment 型を持つようにスキーマを変更し、comments 型に Todo フィールドを追加し、addComment 型に Mutation フィールドを追加します。

schema {
  query: Query
  mutation: Mutation
}

 type Query {
     getTodos(limit: Int, nextToken: String): TodoConnection
 }

 type Mutation {
     addTodo(id: ID!, name: String, description: String, priority: Int, status: TodoStatus): Todo
     addComment(todoid: ID!, content: String): Comment
 }

 type Comment {
     todoid: ID!
     commentid: String!
     content: String
 }

 type Todo {
     id: ID!
     name: String
     description: String
     priority: Int
     status: TodoStatus
     comments: [Comment]
 }

 type TodoConnection {
     todos: [Todo]
     nextToken: String
 }

 enum TodoStatus {
     done
     pending
 }

Comment 型に、commentid、および content に関連付けられた todoid が含まれていることに注意してください。これは、後で作成する Amazon DynamoDB テーブルのプライマリキーとソートキーの組み合わせに対応します。

AWS AppSync で既存のデータソースの上部にあるアプリケーショングラフを使用すると、1 回の GraphQL クエリで 2 つの異なるデータソースからのデータを返すことができます。この例では、Todo テーブルと Comment テーブルの両方が存在すると仮定しています。その方法については、「データソースをアタッチする」と「リゾルバーを設定する」 で説明します。