Intégrations GraphQL et NodeJS à l’aide de Cloud Code Functions

GraphQL apporte du sucre, du piment et tout ce qui est agréable aux développeurs d’API, mais il s’agit essentiellement d’un langage de requête qui vous permet de spécifier ce que vous recherchez.

Et si vous avez besoin de plus de renseignements commerciaux que cela dans votre application ?

Et si vous avez besoin d’une certaine logique ?

Et si vous voulez le module NPM qui va avec ?

Eh bien, attachez vos ceintures, car aujourd’hui je vais vous montrer quelque chose de très puissant. Et avec de grands pouvoirs, viennent de grands… eh bien… de grands gains de temps, de grandes possibilités, beaucoup de bonnes choses…

Si vous voulez en savoir plus sur GraphQL, jetez un coup d’œil à cet article : Qu’est-ce que GraphQL ?

Vous devez être grand comme ça pour monter…

Et utilisez Parse 3.5.0 ou plus pour jouer avec GraphQL.
Allez dans Paramètres du serveur et Gérer le serveur Parse et assurez-vous que vous utilisez une version compatible.

Notre toute nouvelle fonctionnalité : GraphQL + Cloud Code Functions

Si vous êtes déjà un utilisateur de Parse/Back4app, vous avez probablement utilisé ou au moins entendu parler de Cloud Code.

Cloud Code est essentiellement du code NodeJS qui s’exécute à partir des serveurs d’applications de Back4app au lieu des appareils finaux.

Cela apporte quelques avantages clés en fonction de vos besoins, mais essentiellement cela vous permet de :

• Economiser les batteries des téléphones portables

  Lorsque vous transférez la charge de traitement de l’appareil vers le Cloud, le traitement intense n’est pas effectué sur l’appareil, ce qui permet d’économiser de la batterie. Le traitement est effectué sur nos serveurs et seul le résultat final est transmis au client. Plus de téléphone portable brûlant dans votre poche. Plus de “OMG cette application vide ma batterie”.

• Économisez sur les plans de données

  Vous avez une tonne d’objets à récupérer pour obtenir un rapport. Des milliers ? Des millions ?
  Cela fait beaucoup de données que vous devez récupérer et si vous n’êtes pas en WiFi, vous feriez mieux de mettre à jour votre plan de données de téléphone portable.
  Nous savons tous que les forfaits de données sont assez coûteux (plus personne ne paie pour des SMS, n’est-ce pas ?), alors pourquoi ne pas adopter une approche plus intelligente ?
  Et si nous pouvions obtenir le rapport entièrement calculé dans le nuage et ne récupérer que le tout dernier résultat sur l’appareil ? Une charge utile plus petite qui consommerait beaucoup moins de votre plan de données et fonctionnerait également plus rapidement ?
  C’est génial ? C’est ce que fait Cloud Code…

• Déploiement plus rapide du code

  Il fut un temps où les développeurs devaient republier leurs logiciels sur les App Stores. À l’époque, c’était une loterie : si vous obtenez un évaluateur rapide, votre application sera disponible pour les utilisateurs le jour même. Si l’évaluateur était plus lent ou plus pointilleux, la publication de l’application pouvait prendre des semaines. Si elle était publiée.
  Pourquoi prendre ce risque ?
  Ne livrez que la partie frontale de votre application à l’App Store et laissez autant de logique que possible dans le code cloud.
  Vous avez besoin d’apporter une petite modification à la logique ? Ou une grosse modification ? Pas de problème.
  Changez le code cloud, déployez-le à nouveau et vous serez comme neuf. Pas de révision de la part d’un gars qui vient d’ailleurs et une disponibilité instantanée pour vos clients.

Mais encore une fois… qu’en est-il de GraphQL ?

GraphQL vous permet de faire des requêtes. Vous pouvez faire des requêtes très intelligentes, mais ce ne sont que des requêtes.

Lorsque notre PDG, Davi, discutait de la manière de le rendre plus intelligent, l’intégration avec Cloud Code Functions est apparue comme une simple logique : vous avez le meilleur des deux mondes ! La puissance et l’intelligence de Cloud Code Functions, ET la facilité et la maintenabilité de GraphQL.

Grâce à notre nouvelle fonctionnalité, vous pouvez étendre les types de GraphQL pour exécuter Cloud Code Functions et récupérer ses résultats.

Vous pouvez appliquer n’importe quelle logique métier que vous pouvez imaginer à vos fonctions Cloud Code, y inclure des modules NPM et les interroger avec GraphQL.

Assez parlé. Prenons les choses en main…

Les classes et objets que nous allons utiliser

Pour ce billet, j’ai créé deux classes distinctes : Employee et Pet, qui contiendront les employés de Back4app et leurs animaux de compagnie respectifs.

Un employé possède les propriétés suivantes :

• nom (Chaîne)
• age (Nombre)
• email (Chaîne)
• position (Chaîne)
• hasThisPet (Pointeur vers la classe Pet)

Un animal de compagnie possède les propriétés suivantes :

• name (Chaîne)
• espèce (Chaîne)

Et quelques fonctions de code cloud

Pour nos fonctions de code cloud, j’écrirai un fichier nommé main.js et j’y inclurai le code suivant.

Il contient cinq fonctions de code cloud entièrement commentées qui feront l’affaire :

• checkGraphQLSupport
  vérifier si l’application prend en charge GraphQL
• retrieveFirstEmployeeByName (récupérer le premier employé par nom)
  récupérer tous les détails du premier employé trouvé dans la base de données avec un nom donné
• retrieveAllEmployees
  récupère tous les détails concernant tous les employés
• retrieveOnwerOfPetByName
  Récupérer les données d’un employé qui a un animal de compagnie portant un nom donné.
• retrieveEmployeeByNameWithPet (Récupérer un employé par son nom avec un animal de compagnie)
  récupère tous les détails d’un employé et de son animal de compagnie

Parse.Cloud.define("checkGraphQLSupport", async req => {
  /*
    Cette fonction retourne si l'application supporte GraphQL. 
    Le serveur parseGraphQLS est vrai si l'application supporte GraphQL, ou faux dans le cas contraire.
  */
  if (parseGraphQLServer){
    return "Cette application supporte GraphQL" ;
  } else {
    return "Cette application ne supporte pas GraphQL. Mauvaise version de Parse peut-être ?";
  }
}) ;

Parse.Cloud.define("retrieveFirstEmployeeByName", async req => {
  /*
    Cette fonction récupère le premier employé trouvé avec un nom donné.
    Toutes les propriétés de l'employé sont récupérées.
    Un seul employé est retourné s'il y en a plusieurs dans la base de données.
    S'il n'y a pas d'employé, null est récupéré.
  */
  const query = new Parse.Query("Employés") ; 
  query.equalTo("nom", req.params.nom) ;
  const result = await query.first() ;
  return result ;
}) ;

Parse.Cloud.define("retrieveAllEmployees", async req => {
  /*
    Cette fonction récupère tous les employés.
    Toutes les propriétés de la classe Employee sont récupérées, mais uniquement cette classe.
    Aucun détail sur les pointeurs ou les relations n'est récupéré, seulement l'identifiant de l'objet.
    Un tableau d'employés est retourné. Vide s'il n'y a pas d'employés.
  */
  const query = new Parse.Query("Employés") ; 
  const results = await query.find() ;
  retourne les résultats ;
}) ;

Parse.Cloud.define("retrieveOnwerOfPetByName", async req => {
  /*
    Cette fonction récupère les informations sur l'employé lié à un animal de compagnie,
    par le nom de l'animal.
    Toutes les propriétés de la classe Employé sont récupérées.
    Aucun détail sur l'animal n'est récupéré.
    Un tableau d'animaux est retourné. Il est vide si aucun animal n'est trouvé.
  */

  // Nous commençons par faire une requête pour récupérer les informations sur l'animal.
  const petQuery = new Parse.Query("Pet") ; 
  petQuery.equalTo("nom", req.params.nom) ;
  
  // Ensuite, nous effectuons une requête pour récupérer les détails de son employé sur la base de la propriété hasThisPet
  let employeeQuery = new Parse.Query("Employees") ; 
  employeeQuery.matchesQuery("hasThisPet", petQuery) ;
  const results = await employeeQuery.find() ;

  return results ;
  
}) ;

Parse.Cloud.define("retrieveEmployeeByNameWithPet", async req => {
  /*
    Cette fonction récupère les informations sur l'employé et son animal de compagnie,
    par le nom de l'employé.
    Toutes les propriétés de la classe Employé et de la classe Animal sont récupérées.
    Un tableau d'employés est renvoyé, y compris une propriété hasThisPet entièrement remplie
    avec les informations relatives à l'animal.
    Un tableau empy est renvoyé si aucun employé n'est trouvé.
  */
  const query = new Parse.Query("Employés") ; 
  query.equalTo("nom", req.params.nom) ;
  query.include("hasThisPet")
  const results = await query.find() ;
  retour des résultats ;
}) ;

Nous allons le télécharger dans notre Cloud Code Functions, dans le dossier Cloud.

Une petite étape supplémentaire

Les Cloud Code Functions que nous venons de publier peuvent maintenant être utilisées, mais pour qu’elles fonctionnent avec GraphQL, nous devons créer un fichier nommé schema.graphql et exposer ces fonctions.

La syntaxe est très simple, mais il faut y prêter attention :

extend type Query {
 GraphQLMethodName (parameterName: parameterType): ReturnType! @resolve(to :"CloudCodeFunctionName")
}

pour le code ci-dessus, la syntaxe représente :

• GraphQLMethodName
  Il s’agit du nom que vous appellerez dans votre requête GraphQL. Il n’est pas nécessaire qu’il corresponde au nom de la fonction du code cloud, mais vous devez choisir quelque chose qui permette de comprendre facilement ce que fait cette méthode.

• parameterName
  Le nom du paramètre que vous consommerez dans la requête lorsque vous serez dans la fonction de code cloud. Vous n’avez pas besoin de passer ce paramètre si vous n’utilisez pas de paramètres dans votre fonction de code cloud.

• parameterType
  Le type du paramètre que vous passez. Vous pouvez en savoir plus sur les schémas et voir toutes les possibilités. Vous n’avez pas besoin de passer ce paramètre si vous n’utilisez pas de paramètres dans votre fonction de code cloud.

• ReturnType
  Il s’agit du type de retour de votre méthode.

• CloudCodeFunctionName
  Ceci doit correspondre au nom de la fonction de code cloud que vous avez donné dans votre fichier main.js, car il appellera ce code par le nom de la fonction.

Ainsi, pour notre fichier main.js que nous venons de créer, notre schema.graphql serait :

extend type Query {
  checkGraphQLSupport : String ! @resolve(to : "checkGraphQLSupport")
  retrieveThisEmployeeByName (name:String) : EmployeesClass ! @resolve(to : "retrieveFirstEmployeeByName")
  giveMeAllEmployees : [ClasseEmployés !]! @resolve(to : "retrieveAllEmployees")
  whichEmployeeIsOnwerOfThisPet (name:String) : [EmployeesClass !]! @resolve(to : "retrieveOnwerOfPetByName")
  gatherEmployeeAndPetByEmployeeName (name:String) : [EmployeesClass !]! @resolve(to : "retrieveEmployeeByNameWithPet")
}

Ce n’est pas si difficile, n’est-ce pas ?

Remarquez que j’ai utilisé des noms très étendus qui ne correspondent pas au nom des fonctions du code cloud, juste pour que vous sachiez que vous pouvez renommer lors de l’exposition.

Retournez maintenant à la section Cloud Code Functions de votre application et téléchargez également ce fichier. Assurez-vous qu’il se trouve également dans le dossier Cloud. Vous pouvez le faire glisser et le déposer si nécessaire.
Si vous avez déjà un fichier avec ce nom et que vous ne pouvez pas en télécharger un nouveau, vous pouvez faire un clic droit et le supprimer avant de le télécharger.

Déployez tout et nous sommes prêts à partir :

Maintenant, place à la magie…

Allez dans votre console GraphQL. Commencez à taper “query” et utilisez la fonction d’auto-complétion (CTRL + barre d’espace sur Windows, OPTION + barre d’espace sur Mac), et voyez la magie opérer :

Toutes nos méthodes sont là et nous pouvons interroger chacune d’entre elles. Essayons une à une :

• checkGraphQLSupport

  (renvoie à notre fonction de code Cloud checkGraphQLSupport)
  

• retrieveThisEmployeeByName (name:String)

  (Résout notre fonction de code cloud retrieveFirstEmployeeByName)
  

• giveMeAllEmployees

  (Résout notre fonction de code cloud retrieveAllEmployees)
  
  Remarquez dans l’exemple ci-dessus que les propriétés name et age ont été récupérées correctement, mais que la propriété hasThisPet a des valeurs nulles pour le nom et l’espèce de l’animal.
  Cela est dû au fait que dans cette fonction de code cloud, nous n’avons pas inclus (à l’aide de la méthode include()) les informations relatives à l’animal de compagnie.
  L’autocomplétion nous montrera les possibilités, mais aucune donnée pour remplir ces informations n’a été fournie dans la fonction de code cloud.
  Voir l’exemple gatherEmployeeAndPetByEmployeeNameresolves ci-dessous pour savoir comment inclure des informations.

• whichEmployeeIsOnwerOfThisPet

  (se résout à notre fonction de code cloud retrieveOnwerOfPetByName)
  

• gatherEmployeeAndPetByEmployeeName 

  (résout notre fonction de code cloud retrieveEmployeeByNameWithPet)
  

Vos définitions géniales ont été mises à jour

C’est ainsi que l’on apporte de la logique métier à GraphQL.

Je t’aime 3000 !

Conclusion

GraphQL est un langage de requête et un runtime multiplateforme puissant et facile à utiliser, mais en fin de compte, il s’agit uniquement d’un langage de requête.
Avec cette toute nouvelle intégration avec Cloud Code Functions, nous vous avons apporté le meilleur des deux mondes, en libérant la puissance de Cloud Code (y compris les modules NPM, bébé !).

Maintenant, c’est à vous et à votre créativité de jouer ! Dites-nous ce que vous en pensez et comment vous l’utilisez dans vos projets dans les commentaires ci-dessous !