GraphQL

Une requête GraphQL contient une query, ses variables et le schéma contre lequel elle est écrite. Echolot se sert du schéma pour compléter les champs pendant la saisie, signaler les erreurs avant l’envoi et afficher les types à côté de la réponse.

Créer une requête GraphQLCopy Anchor Link

Choisissez Fichier › Nouvelle requête GraphQL, ou Nouvelle requête GraphQL dans le menu + à côté de Requêtes dans la barre latérale. Saisissez le endpoint dans le champ d’adresse : pour la boutique de démonstration, {{baseURL}}/graphql. L’espace de travail Alpenglow en a une toute prête : Catalog › Search products.

L’éditeur a ces onglets : Docs, Query, Variables, En-têtes, Paramètres, Auth, Variables (les variables propres à la requête), Tests, Scripts et Réglages. Les en-têtes, l’authentification, les tests et les scripts fonctionnent comme pour les requêtes HTTP.

Query et variablesCopy Anchor Link

Écrivez la query dans l’onglet Query :

query SearchProducts($text: String!, $first: Int = 10) {
  search(text: $text, first: $first) {
    totalCount
    nodes { sku name price { amount currency } rating stock { warehouse available } }
  }
}

et ses variables en JSON dans l’onglet Variables. Les {{variables}} fonctionnent à l’intérieur du JSON :

{
  "text": "{{searchTerm}}"
}

Quand le document contient plusieurs opérations, saisissez celle à envoyer dans Opération, au-dessus de la query. Laissez le champ vide pour un document qui n’a qu’une opération.

Envoyez avec Envoyer ou ⌘R.

Comment la requête est envoyéeCopy Anchor Link

Le badge GQL devant l’adresse est un menu. Sous Envoyer via :

Deux interrupteurs en dessous :

• Requêtes persistées (APQ) envoie d’abord le hachage SHA-256 de la query, sans la query. Quand le serveur répond qu’il ne connaît pas ce hachage, Echolot renvoie la requête avec la query, pour que le serveur la conserve.
• Regrouper toutes les opérations envoie toutes les opérations nommées du document ensemble, sous forme d’un seul tableau JSON.

Le schémaCopy Anchor Link

Le menu du schéma se trouve à droite de l’onglet Query. Il affiche le fichier de schéma et son nombre de types, comme shop.graphql · … types, ou Aucun schéma.

• Récupérer depuis le serveur exécute la query d’introspection sur l’adresse de la requête et garde le résultat dans un fichier du dossier specs/ de l’espace de travail. Choisissez-le de nouveau pour actualiser le schéma.
• Utiliser le schéma liste les fichiers de schéma déjà présents dans l’espace de travail (.graphql, .graphqls et .json), pour en choisir un.
• Ajouter un fichier de schéma… prend un fichier SDL (.graphql) ou un résultat d’introspection (.json) sur votre Mac.
• Afficher l’explorateur de schéma ouvre le schéma à côté de la réponse.
• Ne plus utiliser ce schéma retire le schéma de la requête.

Un fichier de schéma dans specs/ peut être partagé par toutes les requêtes GraphQL visant ce serveur, et commité avec l’espace de travail. Quand une récupération remplace un fichier de schéma et que le schéma a changé, Le schéma a changé liste les changements en Incompatible, Dangereux et Sûr, comme un champ supprimé ou un nouvel argument obligatoire. Les changements incompatibles sont ceux qui font échouer les queries utilisant ce qui a été supprimé ou modifié. En ligne de commande, echolot graphql diff compare deux schémas de la même façon : voir echolot graphql.

Quand le schéma ne peut pas être lu, le menu affiche Problème de schéma, et la barre sous la query en donne la raison.

Complétion, problèmes et survolCopy Anchor Link

Avec un schéma, l’éditeur de query vous aide pendant la saisie :

• La Complétion propose les champs, arguments, champs d’entrée, types, valeurs d’enum, variables, directives et fragments qui conviennent à l’endroit du curseur, avec leur documentation. Les éléments obsolètes sont signalés.
• Les Problèmes sont soulignés pendant la saisie : champs inconnus, mauvais types d’argument, arguments obligatoires manquants et plus encore. La barre sous la query montre le premier et compte les erreurs et les avertissements ; pointez-la pour les lire tous.
• Le Survol d’un champ ou d’un type affiche sa signature et sa documentation, et indique s’il est obsolète.
• Un clic avec ⌘ sur un champ ou un type ouvre son type dans l’explorateur de schéma.

L’explorateur de schéma et le constructeurCopy Anchor Link

L’onglet Schéma du volet de réponse montre le schéma de la requête, même avant le premier envoi. Si la requête n’a pas encore de schéma, choisissez-y Récupérer depuis le serveur.

Explorer commence aux Points d’entrée (Query, Mutation et Subscription). Cliquez sur un type pour voir ses champs, ses champs d’entrée, ses valeurs d’enum, ou les types qui l’implémentent ou qui lui appartiennent, les éléments obsolètes étant signalés. Retour revient au type précédent. Rechercher des types et des champs trouve n’importe quoi dans le schéma par son nom.

Construire écrit la query à votre place. Choisissez query, mutation ou subscription sous Opération, puis cochez des champs dans l’arborescence : chaque case cochée ajoute le champ au texte de la query, et la décocher le retire. Ce que vous avez tapé autour reste. Le constructeur travaille sur l’opération nommée dans Opération, ou sur la première opération de ce type dans le document ; s’il n’y en a aucune, il en ajoute une.

RéponsesCopy Anchor Link

La réponse apparaît dans l’onglet Corps sous forme de JSON, comme toute réponse. Echolot lit aussi ce que GraphQL dit à côté des données :

• N erreurs GraphQL dans le résumé de la réponse : le serveur a envoyé un tableau errors, même avec un HTTP 200. Cliquez dessus pour lire chaque message et le chemin auquel il se rapporte.
• Données partielles : des données sont revenues avec des erreurs, si bien que certains champs valent null parce qu’ils ont échoué.
• Extensions : les extensions de la réponse, comme des informations de traçage ou de coût.

Ajoutez dans l’onglet Tests une vérification Erreurs GraphQL égale à 0 pour qu’une exécution échoue dans ce cas. Voir scripts et tests.

Abonnements et livraison incrémentaleCopy Anchor Link

Un abonnement continue d’envoyer des résultats jusqu’à sa fin :

• Via HTTP (POST ou GET), Echolot demande des server-sent events quand l’opération est un abonnement.
• Via WebSocket (graphql-transport-ws), Echolot ouvre le WebSocket, envoie l’abonnement avec les en-têtes et l’authentification de la requête, et répond aux pings du serveur.

Une query avec @defer ou @stream revient en plusieurs parties (multipart/mixed).

Dans les deux cas, le volet de réponse reçoit un onglet Événements : chaque événement ou partie dans l’ordre, numéroté, avec son type (comme next ou part), son id et ses erreurs. Pour @defer et @stream, Résultat fusionné en haut montre le premier résultat avec toutes les parties suivantes appliquées. L’onglet suit les nouveaux événements pendant que le flux tourne, avec À l’écoute… Arrêter y met fin. Choisissez Annuler (⌘.) pour y mettre fin. Un flux qui a démarré n’est pas coupé par le délai d’attente total de la requête.

Envoi de fichiersCopy Anchor Link

Pour une mutation avec une variable Upload, ajoutez le fichier sous Fichiers pour les variables dans l’onglet Variables :

1. Choisissez +.
2. Saisissez la variable, comme file, ou files.0 pour le premier élément d’une liste.
3. Saisissez le chemin du fichier, relatif à l’espace de travail.

Le POST suit alors la spécification GraphQL multipart request : la variable vaut null dans operations, et le fichier part dans une partie à part.