Exemples
Cette rubrique fournit quelques exemples illustrant comment créer des requêtes et des mutations pour l'API Shopify. Dans tous les exemples, nous nous connectons à l'API Admin Shopify. Notre boutique s'appelle altovamapforcetest.
Pour obtenir des instructions sur la connexion à l'API Shopify, consultez la rubrique API Shopify et API GraphQL. Pour plus d'informations sur l'utilisation de l'éditeur dans le dialogue Paramètres GraphQL, consultez la rubrique Éditeur de requêtes/mutations.
Exemple 1 : Récupérer les 10 premiers produits
Dans cet exemple, notre objectif est de récupérer les détails des 10 premiers produits de notre boutique. Le dialogue Paramètres GraphQL ci-dessous affiche l'URL de notre boutique et le jeton d'accès en tant que paramètre d'en-tête, ainsi que la définition d'une opération de requête.
L'opération de requête a été définie comme suit :
•Le type d'opération racine est le type d'objet de requête - il sert de point d'entrée à l'API.
•La structure de requête spécifie l'ensemble de champs qui nous intéresse. Dans notre exemple, nous souhaitons récupérer une liste de produits.
•Le champ products comporte un argument first : 10 qui limite le nombre de produits récupérés aux 10 premiers éléments.
•Le champ nodes est un champ de connexion qui permet d'accéder aux données individuelles des produits à partir de la liste des products.
•Les champs id et title spécifient les attributs du produit à renvoyer.
Définition de la requête illustrée dans le GIF
Pour une démonstration rapide de la création d'une requête dans l'éditeur du dialogue Paramètres GraphQL, veuillez consulter le GIF dans la rubrique Éditeur de requêtes/mutations.
Mappage
Dès que vous cliquez sur OK dans le dialogue Paramètres GraphQL, un composant d'appel de service web apparaît dans la zone de mappage. La structure de la réponse dans le composant est déterminée par le schéma Shopify GraphQL et les champs sélectionnés dans la requête (dans notre exemple, id et title des 10 premiers produits). La réponse est mappée à un fichier CSV (capture d'écran ci-dessous).
Sortie
La réponse suivante a été récupérée du serveur :
gid://shopify/Product/9881539871060,Very Nice Gift Card
gid://shopify/Product/9881539903828,Cool Snowboard
gid://shopify/Product/9881539936596,Super Snowboard
gid://shopify/Product/9881539969364,Epic Ski Wax
gid://shopify/Product/9881540002132,Super-Duper Snowboard
gid://shopify/Product/9881540034900,Crazy Snowboard
gid://shopify/Product/9881540067668,Best Snowboard
gid://shopify/Product/9881540100436,Incredible Snowboard
gid://shopify/Product/9881540133204,Fantastic Snowboard
gid://shopify/Product/9881540165972,Terrific Snowboard
Exemple 2 : Récupérer les détails d'un produit particulier
Dans cet exemple, notre objectif est de récupérer les détails d'un produit avec un ID particulier. L'opération de requête (capture d'écran ci-dessous) a été définie comme suit :
•La requête utilise une variable appelée $productId. La variable est de type ID!. Le signe ! indique qu'une entrée est requise. Une valeur d'entrée sera fournie à la partie Request du composant d'appel de service Web.
•Le champ product récupère un seul produit dans Shopify, à l'aide du productId du produit.
•Le champ variants récupère les variantes du produit (en termes de taille, de couleur, etc.).
•Le champ variants comporte un argument first : 10, ce qui signifie que seules les 10 premières variantes seront récupérées.
•Dans la sous-arborescence variants, nous demandons des données sur chaque variante en sélectionnant les champs suivants dans le champ nodes : displayName, price, updatedAt, availableForSale et taxable.
Mappage
Le mappage avec l'appel de service web configuré est présenté ci-dessous. La partie Request de l'appel contient le paramètre d'entrée (productId) que nous avons précédemment défini dans l'opération de requête. Ce paramètre d'entrée reçoit l'ID d'un produit à partir de la constante. La structure de réponse est mappée à un fichier JSON.
Sortie
Les données suivantes ont été récupérées depuis le serveur :
[
{
"displayName": "Legendary Snowboard",
"price": "749,95",
"updatedAt": "2024-10-29T19:55:34Z",
"availableForSale": true,
"taxable": true
}
]
Exemple 3 : Créer un nouveau produit
Dans cet exemple, notre objectif est de créer un nouveau produit sur le serveur. À cette fin, nous avons défini une mutation (capture d'écran ci-dessous) comme suit :
•La mutation comporte une variable appelée $product qui contient les données d'entrée pour la fonction de mutation productCreate. Cette variable nous permettra de fournir les détails du produit de manière dynamique, dans la partie Request de l'appel de service web. La variable est de type ProductCreateInput!, qui est un type de données prédéfini dans le schéma Shopify GraphQL. Le signe ! indique qu'une entrée est requise.
•La fonction de mutation productCreate crée un nouveau produit.
•La fonction de mutation productCreate dispose d'un argument product qui accepte la variable $product comme valeur.
•La sous-arborescence product définit les champs que nous voulons que Shopify renvoie après la création du nouveau produit. Ces champs comprennent : id, title et descriptionHtml.
Mappage
Le mappage avec l'appel de service web configuré est illustré ci-dessous. Étant donné que le champ id est généré automatiquement, nous n'avons fourni des valeurs que pour les champs title et descriptionHtml. Veuillez noter que les données que vous soumettez pour un nouveau produit ne doivent pas nécessairement correspondre aux champs sélectionnés dans la structure Response : Par exemple, vous pouvez fournir plusieurs détails sur le produit dans la structure Request (titres, prix, variantes, etc.), mais ne récupérer qu'une partie de ces données (par exemple, uniquement les titres).
La réponse est mappée vers un fichier JSON.
Sortie
Les données suivantes ont été récupérées depuis le serveur :
[
{
"productCreate": {
"product": {
"id": "gid://shopify/Product/11863012147540",
"title": "Awesome Snowboard",
"descriptionHtml": "<p>Cette planche de snowboard exceptionnelle est destinée aux riders audacieux qui recherchent puissance et précision. Sélectionnez la couleur et la taille qui correspondent à votre style et à votre aventure.</p>"
}
}
}
]
Exemple 4 : Récupérer la réponse complète (débogage)
Conformément à la spécification GraphQL, les données renvoyées par la requête ou la mutation se trouvent dans la clé data. Outre la clé data, il existe également une clé errors et une clé extensions. La clé errors contient toutes les erreurs qui se produisent pendant l'exécution. La clé extensions fournit des données supplémentaires spécifiques au service, généralement à des fins de débogage et de journalisation.
Pour des raisons de test et de débogage, vous pouvez mapper la réponse complète. La manière la plus simple de procéder consiste à mapper l'objet de réponse contenant les valeurs des clés data, errors et extensions à un schéma JSON any. L'idée principale est que any est un type de données flexible qui peut correspondre à toutes les données JSON valides. Cela signifie également que vous n'avez pas besoin de créer un schéma spécial correspondant à la structure Response.
Pour définir un tel schéma JSON, créez un fichier de schéma JSON (par exemple, any.schema.json), ouvrez le schéma JSON dans un éditeur et saisissez la valeur {}.
Le mappage ci-dessous illustre un appel de service web dont la réponse est mappée à un schéma JSON any.
Sortie
Outre les identifiants et les noms de produits, les données suivantes ont été récupérées depuis le serveur :
"extensions": {
"cost": {
"requestedQueryCost": 6,
"actualQueryCost": 6,
"throttleStatus": {
"maximumAvailable": 2000,
"currentlyAvailable": 1994,
"restoreRate": 100
}
}
}