Requêtes GraphQL

Cette partie de la série pour GraphQL et Adobe Commerce. Dans ce tutoriel et vidéo, découvrez les requêtes GraphQL et comment les exécuter sur Adobe Commerce.

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

Exemple de syntaxe GraphQL

Examinons la syntaxe des requêtes GraphQL avec un exemple complet. (N’oubliez pas que vous pouvez essayer par vous-même contre https://venia.magento.com/graphql.)

Observez la requête GraphQL suivante, qui est ventilée pièce par pièce :

{
    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 peut ê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 d’usine 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 que vous souhaitez et les données renvoyées sont formatées.
de la même manière que la requête elle-même.

Requête pour 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 de terminaison distincts et explicites pour chaque type de données. GraphQL vous offre la possibilité d’interroger un seul point de terminaison avec une expression qui peut récupérer simultanément de nombreux types de données.

De même, la requête spécifie exactement les champs souhaités pour country (id et full_name_english) et categories (items, qui comporte lui-même une sous-sélection de champs), et les données que vous recevez en retour 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 récupérez que ce que vous avez demandé.

Arguments

Bien que les champs que vous souhaitez renvoyer soient spécifiés entre les accolades de chaque type, les arguments et valeurs nommés 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 des requêtes sont filtrés, formatés ou transformés.

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

Champs tout en 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 réalité que de champs. L’expression de products n’est syntaxiquement pas différente de celle de categories. Ce sont des champs, et il n'y a pas de différence entre leur construction.

Tout graphique de données GraphQL possède un seul type "root" (généralement appelé Query) pour démarrer l’arborescence, et 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 les sous-champs de ces champs, et ainsi de suite, potentiellement à plusieurs niveaux de profondeur. Si le type de retour d’un champ est complexe (par exemple, un champ ayant ses propres champs plutôt qu’un type scalaire), continuez à sélectionner les champs de votre choix.

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

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 l’ajout du mot-clé query avant l’accolade d’ouverture de la requête, ainsi que d’un nom d’opération (getProducts). Ce nom d’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 les valeurs des arguments de vos champs directement, sous la forme de chaînes ou d’entiers. Toutefois, la spécification GraphQL prend en charge la première classe pour séparer les entrées utilisateur de la requête principale à l’aide de variables.

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

Lorsqu’une requête contient des variables, il est prévu que la requête GraphQL inclue un dictionnaire de valeurs codé JSON distinct en même temps que la requête elle-même. Pour la requête ci-dessus, vous pouvez envoyer le 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.

Comme vous avez pu constater 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 une "variable: {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 GraphQL.

Ressources GraphQL utiles