Requêtes GraphQL

Il s’agit de la partie 2 de la série pour GraphQL et Adobe Commerce. Dans ce tutoriel et cette vidéo, découvrez les requêtes GraphQL et comment les exécuter par rapport à Adobe Commerce.

Vidéos et tutoriels connexes sur GraphQL dans cette série

Exemple de syntaxe GraphQL

Plongeons directement dans la syntaxe de requête de GraphQL avec un exemple complet. (Souvenez-vous que vous pouvez essayer vous-même contre https://venia.magento.com/graphql.)

Observez la requête GraphQL suivante, qui est répartie morceau par morceau :

{
    country (
        id: "US"
    ) {
        id
        full_name_english
    }

    categories(
        filters: {
            name: {
                match: "Tops"
            }
        }
    ) {
        items {
            name
            products(
                pageSize: 10,
                currentPage: 2
            ) {
                items {
                    sku
                }
            }
        }
    }
}

Une réponse plausible d’un serveur GraphQL pour la requête ci-dessus pourrait être :

{
  "data": {
    "country": {
      "id": "US",
      "full_name_english": "United States"
    },
    "categories": {
      "items": [
        {
          "name": "Tops",
          "products": {
            "items": [
              {
                "sku": "VSW06"
              },
              {
                "sku": "VT06"
              },
              {
                "sku": "VSW07"
              },
              {
                "sku": "VT07"
              },
              {
                "sku": "VSW08"
              },
              {
                "sku": "VT08"
              },
              {
                "sku": "VSW09"
              },
              {
                "sku": "VT09"
              },
              {
                "sku": "VSW10"
              },
              {
                "sku": "VT10"
              }
            ]
          }
        }
      ]
    }
  }
}

L’exemple ci-dessus repose sur le schéma GraphQL prêt à l’emploi pour Adobe Commerce, défini sur le serveur. Dans cette requête, vous
interroger plusieurs types de données à la fois ; La requête exprime exactement les champs souhaités et les données renvoyées sont formatées
de la même manière que pour la requête elle-même.

Effectuer une requête pour obtenir ce que vous souhaitez

country et categories dans l’exemple représentent deux « requêtes » différentes pour deux types de données différents. Contrairement à un paradigme d’API traditionnel comme REST, qui définirait des points d’entrée distincts et explicites pour chaque type de données. GraphQL vous offre la possibilité d’interroger un seul point d’entrée avec une expression qui peut récupérer plusieurs types de données à la fois.

De même, la requête spécifie exactement les champs souhaités à la fois pour country (id et full_name_english) et categories (items, qui comporte elle-même une sous-sélection de champs), et les données que vous recevez reflètent cette spécification de champ. Il y a probablement beaucoup plus de champs disponibles pour ces types de données, mais vous ne recevez que ce que vous avez demandé.

Arguments

Bien que les champs que vous souhaitez renvoyer soient spécifiés entre accolades de chaque type, les arguments nommés et leurs valeurs sont spécifiés entre parenthèses après le nom du type. Les arguments sont souvent facultatifs et affectent souvent la manière dont les résultats de la requête sont filtrés, formatés ou transformés.

Vous transmettez un argument id à country, spécifiant le pays particulier à interroger, ainsi qu’un argument filters pour categories.

Champs jusqu’au bas

Bien que vous ayez tendance à considérer country et categories comme des requêtes ou des entités distinctes, l’arborescence entière exprimée dans votre requête ne se compose en fait que de champs. L'expression de products n'est pas syntaxiquement différente de celle de categories. Les deux sont des champs, et il n'y a aucune différence entre leur construction.

Tout graphique de données GraphQL comporte un seul type « racine » (généralement appelé Query) pour démarrer l’arborescence. Les types souvent considérés comme des entités sont affectés aux champs de cette racine. L’exemple de requête crée en fait une requête générique pour le type racine et sélectionne les champs country et categories. Il sélectionne ensuite des sous-champs de ces champs, etc., potentiellement à plusieurs niveaux de profondeur. Lorsque le type de valeur renvoyée d’un champ est un type complexe (par exemple, un champ doté de ses propres champs, plutôt qu’un type scalaire), continuez à sélectionner les champs de votre choix.

Ce concept de champs imbriqués explique également pourquoi vous pouvez transmettre des arguments pour products (pageSize et currentPage) de la même manière que pour le champ de categories de niveau supérieur.

Arborescence de champs de GraphQL

Variables

Essayons une autre requête :

query getProducts(
    $search: String
) {
    products(
        search: $search
    ) {
        items {
            ...productDetails
            related_products {
                ...productDetails
            }
        }
    }
}

fragment productDetails on ProductInterface {
    sku
    name
}

La première chose à noter est le mot-clé query ajouté avant l’accolade d’ouverture de la requête, avec un nom d’opération (getProducts). Le nom de cette opération est arbitraire ; il ne correspond à rien dans le schéma du serveur. Cette syntaxe a été ajoutée pour prendre en charge l’introduction de variables.

Dans la requête précédente, vous avez codé en dur des valeurs pour les arguments de vos champs directement, sous forme de chaînes ou d’entiers. La spécification GraphQL, cependant, prend en charge de première classe pour séparer l’entrée utilisateur de la requête principale à l’aide de variables.

Dans la nouvelle requête, vous utilisez des parenthèses avant l’accolade ouvrante de l’ensemble de la requête pour définir une variable $search (les variables utilisent toujours la syntaxe du préfixe du signe dollar). C’est cette variable qui est fournie à l’argument search pour products.

Lorsqu’une requête contient des variables, la requête GraphQL doit inclure un dictionnaire de valeurs codé JSON distinct avec la requête elle-même. Pour la requête ci-dessus, vous pouvez envoyer le fichier JSON suivant de valeurs de variable en plus du corps de la requête :

{
    "search": "VT01"
}

Dans tout client compatible avec GraphQL que vous utilisez pour les tests (comme Altair et GraphiQL), l’interface utilisateur prend en charge la saisie des variables JSON séparément de la requête.

Tout comme vous avez vu que la requête HTTP réelle pour une requête GraphQL contient « query: {string} » dans son corps, toute requête contenant un dictionnaire de variables inclut simplement un « variables: {json} » supplémentaire dans ce même corps, où {json} est la chaîne JSON avec les valeurs de variable.

La nouvelle requête utilise également un fragment (productDetails) pour réutiliser la même sélection de champ à plusieurs endroits. En savoir plus sur les fragments dans la documentation de GraphQL.

Ressources GraphQL utiles