Données en temps réel

AWS AppSyncvous permet d'utiliser des abonnements pour mettre en œuvre des mises à jour d'applications en direct, des notifications push, etc. Lorsque les clients invoquent les opérations d'abonnement GraphQL, une WebSocket connexion sécurisée est automatiquement établie et maintenue par. AWS AppSync Les applications peuvent ensuite distribuer des données en temps réel à partir d'une source de données aux abonnés tout en gérant en AWS AppSync permanence les exigences de connexion et de dimensionnement de l'application. Les sections suivantes vous montreront comment AWS AppSync fonctionnent les abonnements.

Directives d'abonnement au schéma GraphQL

Les abonnements dans AWS AppSync sont appelés en tant que réponse à une mutation. Cela signifie que vous pouvez transformer n'importe quelle source de données dans AWS AppSync en source de données en temps réel, en spécifiant une directive de schéma GraphQL lors d'une mutation.

Les bibliothèques AWS Amplify clientes gèrent automatiquement la gestion des connexions par abonnement. Les bibliothèques utilisent Pure WebSockets comme protocole réseau entre le client et le service.

Note

Pour contrôler l'autorisation au moment de la connexion à un abonnement, vous pouvez utiliser AWS Identity and Access Management (IAM)AWS Lambda, les groupes d'identités Amazon Cognito ou les groupes d'utilisateurs Amazon Cognito pour l'autorisation au niveau du champ. Pour le contrôle précis des accès sur les abonnements, vous pouvez attacher des résolveurs à vos champs d'abonnement et appliquer une logique en utilisant l'identité de l'appelant et les sources de données AWS AppSync . Pour plus d'informations, veuillez consulter Autorisation et authentification.

Les abonnements sont déclenchés à partir des mutations et le jeu de sélection de mutations est envoyé aux abonnés.

L'exemple suivant montre comment utiliser les abonnements GraphQL. Il ne spécifie pas de source de données, car celle-ci peut être Lambda, Amazon DynamoDB ou Amazon Service. OpenSearch

Pour commencer à utiliser les abonnements, vous devez ajouter un point d'entrée d'abonnement à votre schéma comme suit :

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

Supposons que vous disposez d'un site de blog et que vous souhaitez vous abonner à de nouveaux blogs et à des modifications de blogs existants. Pour ce faire, vous devez ajouter la définition Subscription suivante à votre schéma :

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

Supposons encore que vous disposez des mutations suivantes :

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!
}

Vous pouvez transformer ces champs en temps réel en ajoutant une directive @aws_subscribe(mutations: ["mutation_field_1", "mutation_field_2"]) pour chacun des abonnements pour lesquels vous souhaitez recevoir des notifications, comme suit :

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

Comme il @aws_subscribe(mutations: ["",..,""]) prend un ensemble d'entrées de mutation, vous pouvez spécifier plusieurs mutations, ce qui déclenche un abonnement. Si vous vous abonnez à partir d'un client, votre requête GraphQL peut ressembler à ce qui suit :

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

Cette requête d'abonnement est nécessaire pour les connexions client et l'outillage.

Avec le WebSockets client pur, le filtrage des ensembles de sélection est effectué par client, car chaque client peut définir son propre ensemble de sélection. Dans ce cas, le jeu de sélection d'abonnement doit être un sous-ensemble du jeu de sélection de mutation. Par exemple, un abonnement addedPost{author title} lié à la mutation ne addPost(...){id author title url version} reçoit que l'auteur et le titre de l'article. Il ne reçoit pas les autres champs. Cependant, si la mutation n'avait pas l'auteur dans son ensemble de sélection, l'abonné obtiendrait une valeur null pour le champ auteur (ou une erreur dans le cas où le champ auteur est défini comme « required/not-null » dans le schéma).

L'ensemble de sélection des abonnements est essentiel lors de l'utilisation de Pure WebSockets. Si un champ n'est pas explicitement défini dans l'abonnement, il AWS AppSync ne renvoie pas le champ.

Dans l'exemple précédent, les abonnements n'avaient pas d'arguments. Supposons que votre schéma ressemble à ce qui suit :

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

Dans ce cas, votre client définit un abonnement ainsi :

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

Le type de retour d'un champ subscription dans votre schéma doit correspondre au type de retour du champ de mutation correspondant. L'exemple précédent illustrait cela avec addPost et addedPost qui ont été renvoyés en tant que type de Post.

Pour configurer les abonnements sur le client, voirCréation d'une application client.

Utilisation d'arguments d'abonnement

Pour utiliser les abonnements GraphQL, il est important de comprendre quand et comment utiliser les arguments. Vous pouvez apporter des modifications subtiles pour modifier comment et quand informer les clients des mutations survenues. Pour ce faire, consultez l'exemple de schéma du chapitre de démarrage rapide, qui crée « Todos ». Pour cet exemple de schéma, les mutations suivantes sont définies :

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

Dans l'exemple par défaut, les clients peuvent s'abonner aux mises à jour de n'importe quel produit en Todo utilisant le onUpdateTodo subscription paramètre sans argument :

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

Vous pouvez filtrer votre subscription en utilisant ses arguments. Par exemple, pour déclencher un uniquement subscription lorsqu'un fichier todo contenant un élément spécifique ID est mis à jour, spécifiez la ID valeur :

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

Vous pouvez également transmettre plusieurs arguments. Par exemple, ce qui suit subscription montre comment être informé de toute Todo mise à jour à un endroit et à une heure spécifiques :

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

Notez que tous les arguments sont facultatifs. Si vous ne spécifiez aucun argument dans votre applicationsubscription, vous serez abonné à toutes les Todo mises à jour effectuées dans votre application. Cependant, vous pouvez mettre à jour votre définition subscription de champ pour exiger l'IDargument. Cela forcerait la réponse d'un todo s spécifique todo au lieu de tous :

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

La valeur null de l'argument a une signification

Lorsque vous effectuez une requête d'abonnement dans AWS AppSync, une valeur d'argument null filtre les résultats différemment de l'omission complète de l'argument.

Revenons à l'exemple d'API todos où nous pourrions créer des todos. Consultez l'exemple de schéma du chapitre de démarrage rapide.

Modifions notre schéma pour inclure un nouveau owner champ, sur le Todo type, qui décrit le propriétaire. Le owner champ n'est pas obligatoire et peut uniquement être activéUpdateTodoInput. Consultez la version simplifiée suivante du schéma :

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"])
}

L'abonnement suivant renvoie toutes les Todo mises à jour :

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

Si vous modifiez l'abonnement précédent pour ajouter l'argument de champowner: null, vous posez maintenant une autre question. Cet abonnement enregistre désormais le client pour qu'il soit informé de toutes les Todo mises à jour pour lesquelles aucun propriétaire n'a été fourni.

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

Note

Depuis le 1er janvier 2022, MQTT over n' WebSockets est plus disponible en tant que protocole pour les abonnements AWS AppSync GraphQL dans les API. Pure WebSockets est le seul protocole pris en charge dansAWS AppSync.

Les clients basés sur le AWS AppSync SDK ou les bibliothèques Amplify, publiés après novembre 2019, utilisent automatiquement WebSockets pure par défaut. La mise à niveau des clients vers la dernière version leur permet AWS AppSync d'utiliser le WebSockets moteur pur.

Pure WebSockets propose une charge utile plus importante (240 Ko), une plus grande variété d'options client et des CloudWatch indicateurs améliorés. Pour plus d'informations sur l'utilisation de WebSocket clients purs, consultezCréation d'un WebSocket client en temps réel.