Das Shopify-Lernkit für GraphQL

静脉Gastbeitrag布拉德利·冯·亚历克斯

ImJuli 2020haben wir die Admin-API von Shopify inGraphQL(engl.) angekündigt – eine moderne, leistungsstarke und benutzerfreundliche API für dich als Entwickler.Die Nutzung von GraphQLbietet eine spannende Erfahrung mit APIs zu interagieren und eröffnet App-Entwicklern eine neue Welt voller Möglichkeiten.

Ganz gleich, ob du effizient Informationen zu verschiedenen zugehörigen Objekten abrufen möchtest oder nur dieses eine Informationsfeld abfragen musst, ohne einen wesentlichen Teil deines REST-Aufruflimits zu verbrauchen – es gab nie einen besseren Zeitpunkt, um sich mit der Verwendung unsererGraphQL-Admin-API(engl.) vertraut zu machen.

Damit du alle von der Admin-API in GraphQL gebotenen Optionen nutzen kannst, haben wir dieses Lernkit zusammengestellt. Es wird dich durch verschiedene Aufrufe der GraphQL-Admin API von Shopify führen, wobei derInsomnia API-Client(engl.) verwendet wird.

1. Voraussetzungen

Um dieser Anleitung folgen zu können, wirst du einige Dinge benötigen:

• Deine eigeneprivate App, die du in deinem Shop erstellt hast
• Sie benötigt Lese- und Schreibberechtigungen für:
• Products (Produkte)
• Customers (Kunden)
• Orders (Bestellungen)
• DraftOrders (Bestellentwürfe)
• Klicke auf „Deaktivierte Admin-API-Berechtigungen überprüfen“ und scrolle nach unten, um diese letzte Berechtigung zu finden
• DenInsomnia API-Client
  
  
• DieInsomnia-Sammlung für den Shopify GraphQL Walkthrough

Konfiguration von Insomnia

Nachdem du Insomnia installiert hast, importiere die Sammlung und stelle sicher, dass sie richtig konfiguriert ist, um Aufrufe mit deinen API-Anmeldeinformationen an deinem Shop tätigen zu können. Nachfolgend findest du die Schritte dazu:

Schritt 1: Importiere die Sammlung

Sobald du den Walkthroughals Sammlung heruntergeladen hast, importiere sie in Insomnia.

Öffne das FensterImport / Exportin Insomnia:

Navigiere auf dem TabData (Daten)zur Sammlung:

Wechsle zumShopify GraphQL-Arbeitsbereich:

Schritt 2: Konfiguriere deine Environment-Variablen

Environment-Variablen sind JSON-Schlüssel-Wertepaare, mit denen du auf Werte (values) verweisen kannst, ohne sie jedes Mal ausschreiben zu müssen.

Für unser Setup definieren wir zwei Environment-Variablen:

• Dershop, mit dem wir interagieren werden
• Wenn dein Shop mydevstore.myshopify.com ist, gibst du hier „mydevstore“ ein

• Dasaccess_token, das wir verwenden werden
• Dies ist das Passwort deiner privaten App, das auf der Seite dieser App angezeigt wird

Auf diese Weise kannst du alle Queries in dieser Sammlung in verschiedenen Shopify-Shops wiederverwenden, indem du ganz einfach deine Insomnia-Environment-Variablen änderst.

Du kannst deineEnvironment-Variablenfestlegen, indem du das Fenster „Manage Environments“öffnest und deine Details zum Sub-Environment„my-test-store-details“hinzufügst:

Schritt 3: Führe die Testabfrage aus

Jetzt ist es an der Zeit, das Ganze zu testen.

Öffne in Insomnia die zweite Query unterShopify GraphQL Walkthrough > Insomnia Configurationmit dem TitelRun the rest query.

Oben im Fenster solltest du sehen, dass wir den „Shop“ bzw. „Store“ verwenden, um die Adresse für den Endpunkt zu erstellen.

杜kannst欧什oben汪汪汪Headerklicken, um zu sehen, welche Header wir mit unserer Anfrage senden, einschließlich desaccess_token.

Wenn du den Cursor über einen dieser beiden Punkte bewegst, solltest du den Wert sehen, der in der Anfrage ersetzt wird.

Wenn du deine Werte nicht siehst, solltest du sicherstellen, dass du das richtige Environment ausgewählt hast.

Sobald du diese beiden Felder in deinem Environment eingerichtet hast, kannst du die unten stehende Query ausführen. Du solltest den Namen deines Shops ausgespielt bekommen.

2. Beispiele für Query-Strukturen

Zunächst wollen wir uns anschauen, wie wir unsere Queries strukturieren können, um GraphQL optimal zu nutzen.

QueryRoot-Objekte

DieQueryRoot(engl.) stellt leicht zugängliche Einstiegspunkte in die GraphQL-Admin-API dar.

Auf dieser Seite kannst du nach einer für dich interessanten Ressource suchen und dich dann durchklicken, um mehr zu erfahren.

In unserem Beispiel sehen wir uns nochmals die Shop-Ressource an, da es sich hier um ein einzelnes Objekt handelt. Objekte stellen Konzepte wie denShop(engl.) oder eine einzelneBestellung(engl.) dar und enthalten Daten in Feldern.

In GraphQL müssen wir immer auswählen, was wir aus den verfügbaren Feldern zurückerhalten möchten. Alternativ dazu vervollständigt Insomnia gültige Felder automatisch, während du tippst. Du kannst also die folgende Query ändern, um mehr oder weniger Informationen zurückzuerhalten.

Diese Query ruft das Shop-Objekt ab und gibt an, welche Felder zurückgegeben werden sollen.

Moglicherweise腕du菲ststellen, dass du das bekommst, was du angefordert hast und zudem noch etwas mehr. In der zurückgegebenen JSON-Nutzlast solltest du zwei übergeordnete Schlüssel sehen: “Data“ (Daten) und „Extensions“ (Erweiterungen).

• „Data“ ist immer das, was du gerade in deiner Query angefordert hast.
• „Extensions“ sind zusätzliche Informationen, die Shopify hinzugefügt hat (zum Beispiel die Kosten deiner Query).

Wir werden uns die科斯tenein anderes Mal genauer ansehen und vorerst außer Acht lassen.

Connections und Edges

Connections sind Verknüpfungen zwischen ähnlichen Objekten. Diese ermöglichen dir, verschachtelte Abfragen durchzuführen und Informationen von mehreren Objekten zu sammeln, indem deine Connections in einem einzigen GraphQL-Aufruf durchlaufen werden.

Wenn duConnectionsverwendest, solltest du das Feld „Edges“ auswählen. Das „Edges“-Feld ist eine Anordnung von Objekten desselben Typs, zum Beispiel Bestellungen in einem Shop. Nachdem du die Edges ausgewählt hast, greifst du über das Node-Feld auf die einzelnen Objekte zu.

Im Node-Feld kannst du die Objektfelder auswählen, die du zurückgeben lassen möchtest. Diese Felder werden für jedes Objekt in der Edges-Anordnung ausgewählt.

Schließlich musst du bei der Verwendung einerConnectionimmer die Anzahl der zurückzugebenden Objekte auswählen (entweder die erste oder letzte in der Gruppe). Mehr dazu weiter unten imAbschnitt Paginierung.

Diese Abfrage erhält die Connection des Produkts, die über die QueryRoot verfügbar ist, und fragt nach den ersten drei Produkten. Es wählt Edges, Nodes und Felder aus den zurückgegebenen Produktobjekten aus.

Da auch Produkte eine Varianten-Connection haben, wiederholen wir einen ähnlichen Prozess, um Informationen über die ersten fünf Varianten zu jedem dieser Produkte zu erhalten.

Filtern von Connections mithilfe des Query-Parameters

Bei vielen Connections empfiehlt es sich, die Liste der Edges nach unten zu filtern, um das spezifische Objekt zu finden, an dem du tatsächlich interessiert bist (d. h. die spezifischenNodesin der Auswahl derEdges).

Du kannst herausfinden, für welche Felder eine Conncetion die Filterung unterstützt, indem du auf denQuery-Parameterauf der Referenzseite dieser Connection in den Dokumenten verweist. Was die Formatierung des Filters betrifft, folgt die Syntax demLeitfaden für die Suchsyntax(engl.).

Diese Query findet die ersten zehn ausgeführten Bestellungen.

Einzelobjekt nach ID

Der Zugang über Conncetions ist zwar sehr gut, aber manchmal wünschen wir uns vielleicht etwas Direkteres.

Glücklicherweise können wir auf ein Objekt auch direkt über seine GraphQL-ID zugreifen.

Ein erneuter Blick auf unsereQueryRoot(engl.)-Dokumentation zeigt, dass es mehrere Queries gibt, die eine einzige GraphQL-ID als Eingabe erfordern und dieses Objekt zurückgeben. Es wird empfohlen, immer die ID aller von dir abgefragten Objekte auszuwählen, damit du später direkt darauf zugreifen kannst.

Diese Query erhält ein einzelnes Produkt über die ID und gibt an, welche Felder zurückgegeben werden sollen.

Die GraphQL-ID eines Produkts für diese Query kannst du ganz einfach aus der Antwort auf unsere vorherige Abfrage „Connections und Edges“ entnehmen. Machst du das nicht, wirst du eine „Null“-Antwort erhalten, da du nach einer Produkt-ID suchst, die es in deinem Shop nicht gibt.

3. Beispiele für Mutationsstrukturen

Da wir jetzt wissen, wie man mit GraphQL-Daten anfordert, werden wir uns mit der Modifizierung dieser Daten befassen.

Basics and Inputs

Mutationen sind das Äquivalent zu den POST/PUT/DELETE-Aktionen von REST und ermöglichen dir das Erstellen und Ändern von Objekten. Sie sind nicht direkt an Ressourcen gebunden. Daher hängt es in der Regel von der Namenskonvention und dem Lesen der Dokumentation ab, welche Aufgabe sie haben.

真美贝查询你们杜在GraphQL音麦盟swählen, welche Daten zurückgegeben werden sollen. Gewöhnlich geben Mutationen das Objekt zurück, das erstellt/geändert wurde, was dir eine hervorragende Möglichkeit bietet, die GraphQL-ID auszuwählen und alle wesentlichen Daten zu überprüfen.

Und schließlich enthalten Mutationen immer einuserErrors-Feld.

Dieses Feld gibt an, ob mit deiner Mutation etwas nicht stimmt und warum sie möglicherweise nicht wie erwartet verarbeitet wurde.

Du solltest also immer das FelduserErrorsauswählen, um darüber die eigene Fehlerbehebung zu erleichtern. Wenn nichts schiefgelaufen ist, wird das FelduserErrorsleer sein.

Diese Mutation legt einen neuen Customer (Kunden) an. Wir übergeben auch den Input, bei dem es sich um ein JSON-Objekt handelt, welcher die Daten enthält, die unser Customer erhalten soll.

Mutationen erfordern in der Regel Inputs. In der Dokumentation kannst du nachlesen, welche Felder du diesem Input-Hash hinzufügen kannst. Betrachte zunächst die Mutation und schau dir an, welche Art von Input sie erwartet. Überprüfe zweitens die Dokumente zu diesem Input für alle verfügbaren Felder. Beispielsweise listetdie SeiteCustomerInputim Help Center(engl.) alle verfügbaren Inputs auf.

Wir werden auch diese Felder auswählen, um zu bestätigen, dass sie richtig festgelegt wurden.

Inputs v2

Mutationsinputs können auch IDs erfordern, so zum Beispiel beim Erstellen einer Order (Bestellung).

Von der vorherigen Mutation solltest du die GraphQL-ID des Kunden nach der Erstellung zurückerhalten haben (falls du diese Option ausgewählt hast). Nun wollen wir fortfahren und einen neuen Bestellentwurf für diesen Kunden anlegen.

Um unseren Input richtig zu formatieren, verweisen wir auf die Referenzdokumente fürDraftOrderCreate,DraftOrderInputundDraftOrderLineItemInput.

Insomnia sollte die Feldnamen aus dem, was dir zur Verfügung steht, automatisch ausfüllen. Somit sind die Dokumente nicht unbedingt notwendig, da das Schema von Insomnia automatisch geladen wird.

4. GraphQL-Variablen

Um unsere Arbeit zu beschleunigen und wiederzuverwenden, werden wir die native Implementierung von Variablen von GraphQL nutzen.

Variablen

GraphQL-Variablen ermöglichen dir die Wiederverwendung derselben Abfragen/Mutationen mit unterschiedlichen Argumenten.

In Insomnia werden die Abfragevariablen in dem unteren Abschnitt des Editors getrennt. Für jedes folgende Beispiel musst du deine Werte den Variablen hinzufügen. Wenn du diesen Schritt umgehst, bedeutet es, dass du versuchst die Daten von „my shop“ abzufragen, worauf du eine „Null“-Antwort erhalten wirst.

Für unser Beispiel suchen wir den gerade erstellten Bestellentwurf und verwenden die ID, die uns als Teil der Variablen zurückgegeben wurde.

Lass uns das Ganze Zeile für Zeile durchgehen und sehen, wie die Variablen in die Query gezogen werden.

5. Paginierung

Um die von uns abgefragte Datenmenge zu optimieren, werfen wir einen Blick darauf, wie man Objekte in GraphQL durchlaufen kann.

Was ist pageInfo?

Wenn wir Connections anfordern, müssen wir immer eine Teilmenge der vollständigen Ergebnisse anfordern, entweder mit dem „ersten“ oder „letzten“ Argument. Das bedeutet, dass wir bei „orders“ nur die ersten X Bestellungen sehen und dann auswählen können, welche Felder wir aus diesen Bestellungen wünschen. Dies ist ideal für Elemente, die im ersten (oder letzten) X angezeigt werden. Wie erhalten wir jedoch zentralere Elemente?

Auf jeder Conection gibt es ein „pageInfo“-Feld, das sich auf der gleichen Ebene wie die Edges befindet. Das „pageInfo“-Feld enthält Informationen über die aktuelle Teilmenge der Connection, die wir angefordert haben. Wir schauen uns hier auch das Feld „hasNextPage“ an, das „true“ zurückgibt, wenn die Connection mehr Elemente enthält, die in der aktuellen Teilmenge nicht angezeigt werden.

Diese Abfrage erhält die ersten zehn Bestellungen und fragt auch, ob es noch weitere Bestellungen gibt.

Der Cursor

Für die Paginierung reicht es nicht aus, zu wissen, dass die nächste Menge (von X Objekten) in der Connection existiert. Wir müssen auch einen Weg finden, uns darauf zu beziehen.

Cursors sind Referenzen zu einem Node (Objekt) im Kontext der Edges einer Conncetion. Indem wir unsere Query leicht modifizieren, können wir nach Nodes vor oder nach diesem Cursor fragen.

Schauen wir uns unsere vorherige Query noch einmal an und fragen auch nach dem Cursor der aktuellen Edge.

Diese Query erhält die ersten zehn Bestellungen und fragt auch, ob es noch weitere Bestellungen gibt. Es wird auch nach dem Cursor dieser Edge gefragt.

Der Cursor v2

Mit dem Cursor sind wir bereit, unsere gesamte Connection zu durchlaufen.

Bei jeder Connection kannst du das „after“-Argument angeben, das den Server anweist, dir die Ergebnisse nach diesem speziellen Cursor zurückzugeben. Verwende den Wert, der für „cursor“ in der vorherigen Abfrage als „after“-Argument in dieser Abfrage zurückgegeben wurde, um den nächsten Satz von Edges zu erhalten. Vergiss nicht, den enthaltenen Wert der Cursor-Variablen durch deinen eigenen Wert zu ersetzen.

Schauen wir uns unsere vorherige Query noch einmal an und fragen auch nach dem Cursor der aktuellen Edge.

6. Fortgeschritten

Nun hast du alles gelernt, was du für den Einstieg in deine Reise mit GraphQL benötigst. Wenn du neugierig auf weitere Tipps und Tricks bist, dann lies weiter.

Fragmente: Bediene mehrerer Fälle

Fragmente sind ein GraphQL-Konzept, mit dem du deine Query flexibel gestalten kannst. Sie sind durch die Syntax „... on “ gekennzeichnet.

Mit dem „node“-Feld auf der QueryRoot können wir anhand ihrer ID nach bestimmten Objekten fragen. Dadurch erhalten wir das Objekt (unter dem „node“-Feld oder als Edges unter der „node“-connection) als Node-Objekt mit einem Grundtyp, wodurch wir keine genaueren Informationen anfordern können. Wenn wir jedoch ein Fragment verwenden, können wir nach spezifischeren Typdaten fragen, sofern der Node diesem Typ entspricht. Dies ist besonders nützlich bei Nodes, die keinen einfachen Zugriffspunkt über die QueryRoot haben, wie zum Beispiel einen Einzelposten bzw. ein „lineItem“.

Lass uns alles bisher Gelernte anwenden, um herauszufinden, wo sich ein „lineItem“ befindet, damit wir es von dieser Location aus ausführen können.

Diese Query verwendet das QueryRoot-Feld für den Node. Wir fragen nach einer ID, die wir irgendwo erhalten haben, z. B. einen Line Item aus unserer früheren Bestellung oder eine Cursor-Query.

Mehrere Queries: Eine Anfrage

杜kannst mehrere查询奥得河Mutationen静脉einzigen GraphQL-Anfrage einreichen. Dies hat keine wirklich ratenbegrenzenden Vorteile, da die Komplexität der Queries immer noch dazu addiert wird. Bei allen anderen Einschränkungen, die es dir leichter machen, nur eine Mehrfachanforderung zu senden, gehst du wie folgt vor.

Die wichtigsten Punkte sind:

1. Bestimme oben den Typ, Query oder Mutation
2. Jede einzelne Query muss wie folgt benannt werden::
3. Die Queries müssen nicht identisch sein
4. Jede einzelne Query muss auswählen, welche Felder zurückgegeben werden sollen

Diese Mehrfachmutation setzt drei verschiedene Tags bei drei verschiedenen Kunden.

Füge deiner App noch heute GraphQL hinzu

Anhand der gezeigten Queries hast du gesehen, wie schnell und flexibel die GraphQL Admin-API von Shopify sein kann. Mit der Möglichkeit auf Daten aus mehreren Objekten in einem einzigen Aufruf zuzugreifen und dir die spezifischen Daten zu liefern, die du benötigst,verbessert GraphQL garantiert Fahigkeiten戴恩死去er Appund erspart dir einige REST-Aufrufe.