リアルタイムデータ

AWSAppSyncサブスクリプションを利用して、アプリケーションのライブアップデートやプッシュ通知などを実装できます。クライアントが GraphQL サブスクリプション操作を呼び出すと、WebSocketによって自動的に安全な接続が確立され、維持されますAWSAppSync。その後、アプリケーションは、AWSAppSyncアプリケーションの接続とスケーリング要件を継続的に管理しながら、データソースからサブスクライバーにデータをリアルタイムで配信できます。次のセクションでは、AWSAppSyncサブスクリプションの仕組みについて説明します。

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

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

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

注記

サブスクリプションへの接続時に認証を制御するには、フィールドレベルの認証に対して、AWS Identity and Access Management IAM、AWS Lambda Amazon Cognito Identity Pools、または Amazon Cognito User Pools を使用できます。サブスクリプションできめ細かなアクセスコントロールを実行する場合、サブスクリプションフィールドにリゾルバーをアタッチし、呼び出し元の IDAWSAppSync とデータソースと呼び出し元の ID を使用してロジックを実行できます。詳細については、「認可と認証」を参照してください。

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

次の例では、GraphQL サブスクリプションの操作方法を示します。データソースを指定しません。これは、データソースが、Lambda、Amazon DynamoDB、または AmazonOpenSearch サービスであるからです。

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

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 と定義されている場合はエラー)。

pure を使用する場合は、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 タイプとして返され、表示されます。

クライアントでサブスクリプションを設定するには、を参照してくださいクライアントアプリケーションの構築。

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

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

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

デフォルトのサンプルでは、TodoonUpdateTodosubscriptionクライアントは引数なしでを使用して任意のアップデートをサブスクライブできます。

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

subscription引数を使用してをフィルタリングできます。たとえば、特定の内容の asubscriptionID が更新されたときにのみ a をトリガーするには、ID次の値を指定します。todo

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

複数の引数を渡すこともできます。たとえば、以下では、subscriptionTodo特定の場所と時間に更新が通知される方法を示しています。

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

引数はすべてオプションです。に引数を指定しない場合subscription、Todoアプリケーションで発生するすべての更新が購読されます。ただし、subscriptionIDのフィールド定義を更新して引数を必要とするようにすることはできます。これにより、すべてのtodo stodo の代わりに特定のレスポンスが強制されます。

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

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

サブスクリプションクエリを作成するときAWSAppSync、null引数の値を使用する場合と、引数を完全に省略する場合とでは、フィルター処理の結果は異なります。

Todo を作成できる todos API サンプルに戻りましょう。のサンプルスキーマを参照してくださいはじめてのGraphQL APIを起動。

スキーマを変更して、ownerTodo所有者が誰であるかを説明する新しいフィールドをタイプに追加しましょう。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日以降、WebSocketsAWS AppSync MQTTオーバーはAPIのGraphQLサブスクリプションのプロトコルとして利用できなくなりました。WebSocketsでサポートされているプロトコルは Pure だけですAWS AppSync。

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

Pure には、より大きなペイロードサイズ（240 KB）、幅広いクライアントオプション、WebSocketsCloudWatch改善されたメトリックスが付属しています。WebSocket純粋クライアントの使用方法については、「」を参照してくださいWebSocketリアルタイムクライアントの構築。