Une introduction à GraphQL: abonnements

L'abonnement GraphQL vise à vous aider à intégrer des fonctionnalités en temps réel dans vos applications GraphQL, tout en ne permettant que les données dont vous avez besoin d'être renvoyées d'événements en direct.

GraphQL, décrit comme un langage de requête et de manipulation de données pour les API, et un runtime pour répondre aux requêtes avec les données existantes, permet à différents clients d'utiliser votre API et de rechercher uniquement les données dont ils ont besoin. Il permet de résoudre certains problèmes de performances rencontrés par certains services REST – sur-extraction et sous-extraction . La spécification GraphQL définit un système de type, un langage de requête et un langage de schéma pour votre API Web, ainsi qu'un algorithme d'exécution pour la manière dont un service (ou moteur) GraphQL doit valider et exécuter des requêtes par rapport au schéma GraphQL.

Dans cet article, je vais me concentrer sur l'abonnement GraphQL. Il serait utile que vous connaissiez déjà la mutation GraphQL et sur laquelle j'ai déjà écrit. Cet article s'appuiera sur l'exemple d'application créé à partir des articles précédents sur la mutation et la requête GraphQL. Si vous souhaitez coder, téléchargez le projet depuis GitHub et copiez les fichiers du dossier src-part-2 dans le dossier principal src . [19659004] Qu'est-ce que l'abonnement GraphQL?

Presque toutes les applications logicielles contiennent une certaine forme de temps réel. Prenez Uber par exemple. Vous souhaitez être averti à l'arrivée de votre chauffeur. S'il s'agit d'une application de score en direct, vous souhaitez voir les scores et le flux d'activités mis à jour en temps réel à mesure que les événements se produisent.

Le but de l'abonnement GraphQL est de vous aider à créer des fonctionnalités en temps réel dans vos applications GraphQL, tout en permettant uniquement aux données dont le client a besoin d'être renvoyées des événements au fur et à mesure qu'ils se produisent. La façon dont cela se produit est que le client établit un canal de communication bidirectionnel avec le serveur en envoyant une requête d'abonnement qui spécifie à quel événement il est intéressé et quelle forme de données doit lui être envoyée lorsque l'événement est déclenché. Une fois le canal établi, le client ou le serveur peut envoyer des données sur le canal ou le fermer. Les événements sont tout ce qui importe au système (par exemple, un nouveau livre créé) et peuvent contenir une charge utile.

Il existe un système d'abonnement qui gérera les opérations d'abonnement entrantes. Il analysera, validera et stockera les requêtes et les variables envoyées par les clients. Si l'opération d'abonnement est valide, elle associera la combinaison du champ racine et des variables de requête à un flux d'événements. Lorsqu'un événement du flux d'événements mappé est déclenché, la requête GraphQL stockée est exécutée, en utilisant la combinaison de variables enregistrées, du contexte et de la charge utile d'événement en entrée. Le résultat de cette exécution est ensuite envoyé au client qui s'est abonné à cet événement. Le client peut choisir de se désinscrire à tout moment en envoyant un message au serveur via le canal de communication établi, ou le serveur peut également choisir de se désinscrire du client à tout moment en raison d'erreurs, de chargement ou de délais d'attente.

Abonnement-désabonnement:

Scénario de publication:

Implémentation des abonnements

sur la mise en œuvre des abonnements. Si vous avez suivi les articles précédents, vous devez vous rappeler que nous avons installé un package npm graphql-yoga . Ce paquet est livré avec d'autres dépendances pour faciliter et accélérer la construction d'un backend GraphQL. Il est fourni avec la prise en charge de l'abonnement GraphQL via deux packages, graphql-subscriptions et subscriptions-transport-ws . Si vous avez cloné le projet en suivant les instructions précédentes, il est également inclus.

Nous voulons que les clients soient avertis lorsque de nouveaux livres sont créés, alors ajoutons une opération d'abonnement à l'API GraphQL pour le permettre. La première chose que nous faisons est de mettre à jour notre schéma avec le type d'opération d'abonnement racine, qui aura un seul champ racine. Ouvrez le fichier src / index.js passez à la ligne 27 et ajoutez le code ci-dessous au schéma.

 type Subscription {
  newBook: Réservez!
}

Ensuite, nous ajoutons le résolveur pour cette opération et son champ racine. Allez à la ligne 34, où nous avons défini la variable résolveurs et modifiez-la pour inclure le code du résolveur ci-dessous:

 Abonnement: {
  nouveau livre: {
    s'abonner: (parent, arguments, contexte, info) => {
      return context.prisma. $ subscribe
        .book ({mutation_in: ["CREATED"]})
        .nœud();
    },
    résoudre: charge utile => {
      retour de la charge utile;
    }
  };
}

La façon dont vous implémentez le résolveur pour les champs du type d'opération d'abonnement est différente de celle de la requête et de la mutation. Plutôt qu'une fonction mappée au champ, elle est mappée à un objet avec deux propriétés, abonnez-vous et résolvez . La propriété subscribe est mappée à une fonction qui renverra AsyncIterator qui est utilisée par le serveur GraphQL pour envoyer les données d'événement au client. Cette fonction a la même définition que la fonction résolveur que vous avez définie pour les opérations de mutation et de requête. La propriété resolver est ce qui renvoie réellement les données de ce qui est émis par le AsyncIterator .

Prisma facilite également la création d'un abonnement à votre API GraphQL. Il vous permet de vous abonner à des événements sur les types de votre modèle de données. Vous pouvez vous abonner à trois types d'événements différents en fonction des types de votre modèle de données: les événements créés mis à jour ou supprimés . Le code que vous venez d'ajouter souscrit à l'événement créé pour le modèle Book.

Vous pouvez également filtrer un événement d'abonnement à partir de l'API Prisma pour vérifier si certains champs sont mis à jour ou qu'un champ particulier contient certaines valeurs. Notre exigence pour notre application n'est pas compliquée, donc je n'entrerai pas dans les détails. Cependant, vous pouvez lire la documentation si vous voulez en savoir plus.

Test de l'abonnement GraphQL

Nous avons notre serveur prêt à répondre à la requête d'abonnement GraphQL. Nous allons maintenant tester la nouvelle fonctionnalité que nous venons d'ajouter. Ouvrez la ligne de commande et exécutez node src / index.js pour démarrer le serveur. Ouvrez votre navigateur sur http: // localhost: 4000. Dans l'éditeur de jeux, copiez et exécutez la requête d'abonnement ci-dessous.

 abonnement {
  nouveau livre {
    Titre
    pages
    chapitres
    auteurs {
      Nom
    }
  }
}

Cela devrait initier une connexion à long terme entre le serveur et le client. Vous n'obtiendrez aucun résultat immédiatement, contrairement à vos opérations de mutation et de requête. Le client attendra les données du serveur et lorsque cela arrivera, le client les affichera.

Déclenchons maintenant un événement en exécutant une requête de mutation pour créer un livre. Cliquez sur l'icône plus dans la cour de récréation GraphQL qui devrait ouvrir un nouvel onglet. Saisissez et exécutez la requête de mutation ci-dessous:

 mutation {
  livre (titre: "SVG pour novice", pages: 290, chapitres: 20,
    auteurs: ["Sarah Jimoh", "Brimoh Aje"])
  {
    Titre
  }
}

La mutation s'exécute avec succès et renvoie des données. Revenez à l'onglet de l'abonnement. Vous remarquerez qu'il contient les données que nous venons de créer.

Mettons à jour le schéma de telle sorte que même si nous pouvons nous abonner à un nouvel événement créé par un livre, nous pouvons également choisir pour être averti uniquement lorsque le titre du nouveau livre contient certains mots clés.

Mettez à jour le type d'abonnement dans le schéma comme suit:

 type Subscription {
  newBook ​​(containsTitle: String): Book!
}

Mettez ensuite à jour le résolveur comme suit:

 abonnez-vous: (parent, arguments, contexte, info) => {
  laissez filter = {mutation_in: ["CREATED"]};
  if (args.containsTitle)
    filter.node = {title_contains: args.containsTitle};

  return context.prisma. $ subscribe.book (filter) .node ();
},

Pour tester cela, redémarrez GraphQL. Exécutez la requête d'abonnement suivante:

 abonnement {
  newBook ​​(containsTitle: "GraphQL") {
    Titre
    pages
    chapitres
    auteurs {
      Nom
    }
  }
}

Ouvrez ensuite un onglet distinct pour exécuter la mutation, qui créera de nouveaux livres. Créez deux livres: un dont le titre ne contient pas le mot GraphQL et un autre dont le titre comprend GraphQL. Vous devriez remarquer que vous ne voyez les données de la requête d'abonnement que si le nouveau livre créé a GraphQL dans son titre.

Et ensuite [19659005] Vous avez vu comment GraphQL vous permet non seulement de créer des API dotées de fonctionnalités CRUD, mais également des API en temps réel à l'aide des abonnements GraphQL. La différence entre les abonnements et les requêtes ou mutations réside dans l'exécution. Bien que les requêtes et les mutations suivent un modèle typique de demande-réponse, les abonnements ne renvoient pas immédiatement les données demandées. Au lieu de cela, lorsqu'un serveur GraphQL reçoit une demande d'abonnement, il crée une connexion à long terme avec le client. Je vous ai montré comment créer un abonnement à votre serveur GraphQL et nous avons utilisé quelques liaisons de Prisma pour que cela fonctionne.

Vous pouvez trouver le code complet sur GitHub dans le répertoire src- partie 3 . J'espère que vous avez aimé apprendre de cette pièce autant que j'ai aimé l'écrire afin de vous éduquer. Si c'est le cas, je vous invite à rester pour le prochain où je vais vous montrer quelques façons de gérer l'authentification dans un serveur GraphQL.

À bientôt! ??

---