Salut, habrozhiteli! Nous avons publié un livre sur le langage de requête GraphQL. Nous avons décidé de partager la traduction du chapitre «Anatomie des requêtes GraphQL»
Snowtooth est une station de ski fictive. Pour des exemples dans ce chapitre, nous prétendrons que c'est une vraie montagne et nous y travaillons. Nous verrons comment l'équipe Web Snow Fang utilise GraphQL pour fournir des informations en temps réel: des informations sur l'état des remontées mécaniques et des pistes de ski. Snow Fang Ski Patrol peut ouvrir et fermer les remontées mécaniques et les pistes directement depuis votre smartphone. Pour suivre les exemples de ce chapitre, reportez-vous à l'interface Snow Fang sur la plateforme GraphQL Playground (snowtooth.moonhighway.com/).
Vous pouvez utiliser l'opération de requête pour interroger les données de l'API. La requête décrit les données que vous souhaitez recevoir du serveur GraphQL. Lorsque vous soumettez une demande, vous demandez des unités de données par champ. Ces champs sont affichés dans le même champ dans la réponse de données JSON que vous recevez du serveur. Par exemple, si vous envoyez une demande allLifts et demandez les champs de nom et d'état, vous devez obtenir une réponse JSON contenant un tableau d'allLifts et les chaînes de nom et d'état de chaque ascenseur, comme illustré ici:
query { allLifts { name status } }
Gestion des erreurs
Les demandes réussies renvoient un document JSON contenant la clé de données. Les demandes ayant échoué renvoient un document JSON contenant la clé d'erreur. Les détails de ce qui s'est mal passé sont transmis sous forme de données JSON sous cette clé. Une réponse JSON peut contenir à la fois des «données» et des «erreurs».
Vous pouvez ajouter plusieurs requêtes à un document de requête, mais une seule opération peut être lancée à la fois. Par exemple, vous pouvez placer deux opérations de requête dans un document de requête:
query lifts { allLifts { name status } } query trails { allTrails { name difficulty } }
Lorsque vous cliquez sur le bouton de lecture, GraphQL Playground vous invite à sélectionner l'une de ces deux opérations.
Si vous souhaitez envoyer une demande pour toutes les données spécifiées, vous devez tout mettre dans la même demande:
query liftsAndTrails { liftCount(status: OPEN) allLifts { name status } allTrails { name difficulty } }
Voici les avantages de GraphQL. Nous pouvons recevoir différents types de données en une seule demande. Nous demandons un liftCount par statut, ce qui nous permet de connaître le nombre d'ascenseurs qui ont actuellement ce statut. Nous demandons également le nom et le statut de chaque ascenseur. Enfin, nous demandons le nom et l'état de chaque trace.
la requête est un type de GraphQL. Nous l'appelons le type racine car c'est le type qui correspond à l'opération, et les opérations sont les racines de notre document de requête. Les champs disponibles pour les requêtes dans l'API GraphQL sont définis dans ce schéma d'API. La documentation indique quels champs sont disponibles pour la sélection dans le type de requête.
La documentation nous indique que nous pouvons sélectionner les champs liftCount, allLifts et allTrails lors de l'appel de cette API. Il définit également plus de champs disponibles pour la sélection, mais le but de la demande est que nous pouvons choisir les champs dont nous avons besoin et ceux que nous devons omettre.
Lorsque nous écrivons des requêtes, nous sélectionnons les champs dont nous avons besoin, en les enfermant entre accolades. Ces blocs sont appelés échantillons. Les champs que nous définissons dans la sélection sont directement liés aux types GraphQL. Les champs liftCount, allLifts et allTrails sont définis dans le type de requête.
Vous pouvez incorporer plusieurs sélections les unes dans les autres. Étant donné que le champ allLifts renvoie une liste Lift, nous devons utiliser des accolades pour créer une nouvelle sélection pour ce type. Il existe toutes sortes de données que nous pouvons demander sur l'ascenseur, mais dans cet exemple, nous n'avons besoin que du nom et de l'état de l'ascenseur. De même, une demande allTrails renverra des types Trail.
La réponse JSON contient toutes les données que nous avons demandées. Ces données sont formatées en JSON et livrées sous la même forme que notre demande. Chaque champ JSON porte le même nom que le champ de notre exemple. Nous pouvons modifier les noms de champ dans l'objet de réponse dans la demande en spécifiant des alias, comme indiqué ci-dessous:
query liftsAndTrails { open: liftCount(status: OPEN) chairlifts: allLifts { liftName: name status } skiSlopes: allTrails { name difficulty } }
Voici la réponse:
{ "data": { "open": 5, "chairlifts": [ { "liftName": "Astra Express", "status": "open" } ], "skiSlopes": [ { "name": "Ditch of Doom", "difficulty": "intermediate" } ] } }
Maintenant, nous renvoyons les données sous la même forme, mais dans notre réponse, nous avons renommé plusieurs champs. Un moyen de filtrer les résultats d'une requête GraphQL consiste à passer les arguments de la requête. Les arguments sont une paire de valeurs clés (ou paires) associées à un champ de requête. Si seuls les noms des ascenseurs fermés sont requis, nous pouvons envoyer un argument qui filtrera notre réponse:
query closedLifts { allLifts(status: "CLOSED" sortBy: "name") { name status } }
Vous pouvez également utiliser des arguments pour sélectionner des données. Par exemple, supposons que nous devons demander le statut d'un téléphérique individuel. On peut choisir un ascenseur par son identifiant unique:
query jazzCatStatus { Lift(id: "jazz-cat") { name status night elevationGain } }
Ici, nous voyons que la réponse contient le nom, l'état, la nuit et le gain d'élévation pour le téléphérique Jazz Cat.
»Plus d'informations sur le livre sont disponibles sur
le site Web de l'éditeur»
Contenu»
Extrait25% de réduction sur les
colporteurs -
GraphQLLors du paiement de la version papier du livre, une version électronique du livre est envoyée par e-mail.