でのリアルタイムデータアプリケーションのサブスクリプションの使用 AWS AppSync

AWS AppSync では、サブスクリプションを使用して、ライブアプリケーションの更新、プッシュ通知などを実装できます。クライアントが GraphQL サブスクリプションオペレーションを呼び出すと、安全な WebSocket 接続が自動的に確立され、 によって維持されます AWS AppSync。その後、アプリケーションは、アプリケーションの接続とスケーリングの要件 AWS AppSync を継続的に管理しながら、データソースからサブスクライバーにデータをリアルタイムで配信できます。以下のセクションでは、 の AWS AppSyncサブスクリプションがどのように機能するかを示します。

GraphQL スキーマサブスクリプションディレクティブ

のサブスクリプション AWS AppSync は、ミューテーションへの応答として呼び出されます。つまり、ミューテーションに GraphQL スキーマディレクティブを指定することで、任意のデータソースを AWS AppSync リアルタイムで作成できます。

AWS Amplify クライアントライブラリは、サブスクリプション接続管理を自動的に処理します。ライブラリは、クライアントとサービス間のネットワークプロトコル WebSockets として pure を使用します。

注記

サブスクリプションへの接続時の承認を制御するには、 AWS Identity and Access Management （IAM） AWS Lambda、、Amazon Cognito ID プール、または Amazon Cognito ユーザープールをフィールドレベルの承認に使用できます。サブスクリプションのきめ細かなアクセスコントロールの場合、リゾルバーをサブスクリプションフィールドにアタッチし、発信者と AWS AppSync データソースの ID を使用してロジックを実行できます。詳細については、「GraphQL を保護するための認証と認可の設定 APIs」を参照してください。

サブスクリプションはミューテーションからトリガーされ、ミューテーション選択セットが受信者に送信されます。

次の例では、GraphQL サブスクリプションの操作方法を示します。データソースは Lambda、Amazon DynamoDB 、または Amazon OpenSearch Service である可能性があるため、データソースを指定しません。

サブスクリプションを開始するには、次のようにスキーマにサブスクリプションのエントリポイントを追加します。

schema {
    query: Query
    mutation: Mutation
    subscription: Subscription
}

ブログ投稿サイトを持っており、新しいブログにサブスクライブし、既存のブログに変わるものとします。これを行うには、スキーマに次の Subscription 定義を追加します。

type Subscription {
    addedPost: Post
    updatedPost: Post
    deletedPost: Post
}

さらに、次のミューテーションがあるとします。

type Mutation {
    addPost(id: ID! author: String! title: String content: String url: String): Post!
    updatePost(id: ID! author: String! title: String content: String url: String ups: Int! downs: Int! expectedVersion: Int!): Post!
    deletePost(id: ID!): Post!
}

通知を受け取る各サブスクリプションに @aws_subscribe(mutations: ["mutation_field_1", "mutation_field_2"]) ディレクティブを追加することで、これらのフィールドをリアルタイム対応にできます。手順は以下のとおりです。

type Subscription {
    addedPost: Post
    @aws_subscribe(mutations: ["addPost"])
    updatedPost: Post
    @aws_subscribe(mutations: ["updatePost"])
    deletedPost: Post
    @aws_subscribe(mutations: ["deletePost"])
}

@aws_subscribe(mutations: ["",..,""]) は、ミューテーション入力の配列を受け取るため、サブスクリプションを開始する複数のミューテーションを指定できます。クライアントからサブスクライブする場合、GraphQL クエリは次のようになります。

subscription NewPostSub {
    addedPost {
        __typename
        version
        title
        content
        author
        url
    }
}

このサブスクリプションクエリは、クライアント接続とツールに必要です。

純粋 WebSockets クライアントでは、各クライアントが独自の選択セットを定義できるため、選択セットのフィルタリングはクライアントごとに行われます。この場合、サブスクリプション選択セットは、ミューテーション選択セットのサブセットである必要があります。例えば、サブスクリプションが addedPost{author title} ミューテーションにリンクされていると、addPost(...){id author title url version} 投稿の作成者とタイトルのみを受け取ります。他のフィールドは受け取りません。ただし、ミューテーションの選択セットに作成者が欠けていた場合、サブスクライバーは作成者フィールドに対して null 値を取得します (または、スキーマ内で作成者フィールドが required/not-null と定義されている場合はエラー)。

サブスクリプション選択セットは、純粋な を使用する場合に不可欠です WebSockets。フィールドがサブスクリプションで明示的に定義されていない場合、 AWS AppSync は フィールドを返しません。

前の例では、サブスクリプションに引数はありませんでした。次のようなスキーマがあるとします。

type Subscription {
    updatedPost(id:ID! author:String): Post
    @aws_subscribe(mutations: ["updatePost"])
}

この場合、クライアントでサブスクリプションが次のように定義されます。

subscription UpdatedPostSub {
    updatedPost(id:"XYZ", author:"ABC") {
        title
        content
    }
}

スキーマの subscription フィールドの戻り値の型は、対応する mutation フィールドの戻り値の型に一致する必要があります。前の例では、これが addPost と addedPost の両方が Post タイプとして返され、表示されます。

クライアントでサブスクリプションをセットアップするには、「Amplify クライアントを使用したクライアントアプリケーションの構築」を参照してください。

サブスクリプション引数の使用

GraphQL サブスクリプションを使用する上で重要なのは、引数をいつ、どのように使うかを理解することです。微妙な変更を加えることで、発生したミューテーションをクライアントに通知する方法とタイミングを変更できます。そのためには、クイックスタートの章にある「Todos」を作成するサンプルスキーマを参照してください。このサンプルスキーマでは、以下のミューテーションが定義されます。

type Mutation {
    createTodo(input: CreateTodoInput!): Todo
    updateTodo(input: UpdateTodoInput!): Todo
    deleteTodo(input: DeleteTodoInput!): Todo
}

デフォルトのサンプルでは、クライアントは引数なしで onUpdateTodo subscription を使うことで、任意の Todo への更新を購読できます。

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

引数を使用して subscription をフィルタリングできます。例えば、特定の ID を含む todo が更新された場合に subscription のみをトリガーするには、ID 値を指定します。

subscription OnUpdateTodo {
  onUpdateTodo(id: "a-todo-id") {
    description
    id
    name
    when
  }
}

複数の引数を渡すこともできます。例えば、次の subscription は、特定の場所と時間に Todo 更新があった場合に通知を受ける方法を示しています。

subscription todosAtHome {
  onUpdateTodo(when: "tomorrow", where: "at home") {
    description
    id
    name
    when
    where
  }
}

引数はすべてオプションであることに注意してください。subscription で引数を指定しない場合、アプリケーションで発生するすべての Todo 更新を購読することになります。ただし、subscription のフィールド定義を更新して ID 引数を必須にすることはできます。これにより、すべての todo の代わりに、特定の todo への応答が強制されます。

onUpdateTodo(
  id: ID!,
  name: String,
  when: String,
  where: String,
  description: String
): Todo

引数値 null には意味があります。

でサブスクリプションクエリを作成する場合 AWS AppSync、null引数値では引数を完全に省略するのとは別の方法で結果をフィルタリングします。

Todos API サンプルに戻り、Todos を作成してみましょう。クイックスタートの章にあるサンプルスキーマを参照してください。

スキーマを変更して、所有者が誰であるかを記述する新しい owner フィールドを Todo タイプに追加してみましょう。owner フィールドは必須ではなく、UpdateTodoInput に設定することしかできません。スキーマの次の簡略版を参照してください。

type Todo {
  id: ID!
  name: String!
  when: String!
  where: String!
  description: String!
  owner: String
}

input CreateTodoInput {
  name: String!
  when: String!
  where: String!
  description: String!
}

input UpdateTodoInput {
  id: ID!
  name: String
  when: String
  where: String
  description: String
  owner: String
}

type Subscription {
    onUpdateTodo(
        id: ID,
        name: String,
        when: String,
        where: String,
        description: String
    ): Todo @aws_subscribe(mutations: ["updateTodo"])
}

次のサブスクリプションはすべての Todo 更新を返します。

subscription MySubscription {
  onUpdateTodo {
    description
    id
    name
    when
    where
  }
}

前のサブスクリプションを変更してフィールド引数 owner: null を追加すると、別の質問をすることになります。これで、所有者が指定されていないすべての Todo 更新について通知を受けることができるように、このサブスクリプションによってクライアントが登録されるようになりました。

subscription MySubscription {
  onUpdateTodo(owner: null) {
    description
    id
    name
    when
    where
  }
}

注記

2022 年 1 月 1 日現在、 MQTT 以降 WebSockets は の GraphQL サブスクリプションのプロトコルとして利用できなくなりました AWS AppSync APIs。Pure WebSockets は、 でサポートされている唯一のプロトコルです AWS AppSync。

2019 年 11 月以降にリリースされた AWS AppSync SDKまたは Amplify ライブラリに基づくクライアントは、 WebSockets デフォルトで pure を自動的に使用します。クライアントを最新バージョンにアップグレードすると、 AWS AppSyncの純粋な WebSockets エンジンを使用できます。

ピュア・ストレージ WebSockets には、ペイロードサイズ (240 KB) が大きくなり、クライアントオプションの種類が広がり、 CloudWatch メトリクスが改善されました。pure WebSocket クライアントの使用の詳細については、「」を参照してくださいでのリアルタイム WebSocket クライアントの構築 AWS AppSync。