Blog für Webdesign und Webentwicklung

Das Shopify-Lernkit für GraphQL

shopify-graphql-learning-kit

Ein Gastbeitrag von Alex Bradley

Im Juli 2020 haben wir die Admin-API von Shopify in GraphQL (engl.) angekündigt – eine moderne, leistungsstarke und benutzerfreundliche API für dich als Entwickler. Die Nutzung von GraphQL bietet 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 unserer GraphQL-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 der Insomnia API-Client (engl.) verwendet wird.

Apps für Shopify-Händler erstellen

Ob du nun Apps für den Shopify App Store erstellst, private Dienstleistungen zur Entwicklung von Apps anbietest oder nach Möglichkeiten suchst, deine Benutzerbasis zu vergrößern – mit dem Shopify-Partnerprogramm stellst du die Weichen auf Erfolg. Melde dich kostenlos an und erhalte Zugang zu Bildungsressourcen, Vorschauumgebungen für Entwickler und Optionen für wiederkehrende Umsatzbeteiligungen.



1. Voraussetzungen

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

shopify-graphql-learning-kit-admin
Überprüfe, ob deine private App über Lese- und Schreibberechtigungen für Produkte, Kunden, Bestellungen und Bestellentwürfe verfügt. Klicke auf „Deaktivierte Admin-API-Berechtigungen überprüfen“, um auf Bestellentwürfe zuzugreifen.

Du bist bereits ein erfahrener GraphQL-Experte?

Dann begib dich auf unsere Seite bei GitHub Gist, um die Abfragen direkt und ohne die Verwendung von Insomnia zu kopieren.

GitHub Gist aufrufen

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 Walkthrough als Sammlung heruntergeladen hast, importiere sie in Insomnia.

Öffne das Fenster Import / Export in Insomnia:

shopify-graphql-learning-kit-import-export

Navigiere auf dem Tab Data (Daten) zur Sammlung:

shopify-graphql-learning-kit-walkthrough

Wechsle zum Shopify GraphQL-Arbeitsbereich:

shopify-graphql-learning-kit-walkthrough

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:

  • Der shop, mit dem wir interagieren werden
    • Wenn dein Shop mydevstore.myshopify.com ist, gibst du hier „mydevstore“ ein
    • Das access_token, das wir verwenden werden
      • Dies ist das Passwort deiner privaten App, das auf der Seite dieser App angezeigt wird
      shopify-graphql-learning-kit-password
      Das Passwort deiner privaten App wird auf deiner App-Seite angezeigt.

      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 deine Environment-Variablen festlegen, indem du das Fenster „Manage Environments“ öffnest und deine Details zum Sub-Environment „my-test-store-details“ hinzufügst:

      shopify-graphql-learning-kit-manage-environments
      Öffne das Fenster „Manage Environments“.  
      shopify-graphql-learning-kit-my-test-store-details

      Füge deine Daten zum Sub-Environment „my-test-store-details“ hinzu.

      Schritt 3: Führe die Testabfrage aus

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

      Öffne in Insomnia die zweite Query unter Shopify GraphQL Walkthrough > Insomnia Configuration mit dem Titel Run 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.

      Du kannst auch oben auf Header klicken, um zu sehen, welche Header wir mit unserer Anfrage senden, einschließlich des access_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.

      shopify-graphql-learning-kit-query-environment
      Überprüfe, ob du das richtige Environment ausgewählt hast. In GitHub Gist anzeigen

      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.

      shopify-graphql-learning-kit-run-test-query

      Führe die Query aus, um den Namen deines Shops zu erhalten.

      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

      Die QueryRoot (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 den Shop (engl.) oder eine einzelne Bestellung (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.

      shopify-graphql-learning-kit-query-root-objects
      Query, um das Shop-Objekt mit einigen Feldern zu erhalten. In GitHub Gist anzeigen.

      Möglicherweise wirst du feststellen, 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 Kosten ein 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 du Connections verwendest, 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 einer Connection immer die Anzahl der zurückzugebenden Objekte auswählen (entweder die erste oder letzte in der Gruppe). Mehr dazu weiter unten im Abschnitt 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.

      shopify-graphql-learning-kit-query-variants
      Abfrage der Connection des Produkts für die ersten drei Produkte. In GitHub Gist anzeigen.

      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 spezifischen Nodes in der Auswahl der Edges).

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

      Diese Query findet die ersten zehn ausgeführten Bestellungen.

      shopify-graphql-learning-kit-query-first-orders
      Query für die ersten zehn Bestellungen, die ausgeführt werden. In GitHub Gist anzeigen.

      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 unsere QueryRoot (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.

      Hinweis: Achte darauf, dass du hier eine GraphQL-ID verwendest und nicht einfach eine REST-ID kopierst und einfügst.

      Der Leitfaden Migrating from REST (engl.) enthält weitere Informationen zur Ermittlung von GraphQL-IDs über REST.

      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.

      shopify-graphql-learning-kit-accessing-object
      Direkter Zugriff auf ein Objekt über seine GraphQL-ID. In GitHub Gist anzeigen.

      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.

      Wie schon bei Queries musst du in GraphQL immer auswä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 ein userErrors-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 Feld userErrors auswählen, um darüber die eigene Fehlerbehebung zu erleichtern. Wenn nichts schiefgelaufen ist, wird das Feld userErrors leer 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 listet die Seite CustomerInput im Help Center (engl.) alle verfügbaren Inputs auf.

      Hinweis: Wenn du die Fehlermeldung „Acces Denied“ (Zugriff verweigert) erhältst, solltest du sicherstellen, dass deine App über die Customer Lese-/Schreibberechtigung verfügt.

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

      shopify-graphql-learning-kit-customer-create-mutation
      Erstellen eines Customer mithilfe der Mutation „customerCreate“. In GitHub Gist anzeigen.

      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ür DraftOrderCreate, DraftOrderInput und DraftOrderLineItemInput.

      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.

      Hinweis: Wenn du die Fehlermeldung „Acces Denied“ (Zugriff verweigert) erhältst, solltest du sicherstellen, dass deine App über die Lese-/Schreibberechtigung für Bestellentwürfe (DraftOrders) verfügt.

      shopify-graphql-learning-kit-draft-order-create-mutation
      Erstellen eines Bestellentwurfs mit der Mutation „DraftOrderCreate“. In GitHub Gist anzeigen.

      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.

      shopify-graphql-learning-kit-reusable-query
      Verwenden von GraphQL-Variablen zum Erstellen einer wiederverwendbaren Query. In GitHub Gist anzeigen.

      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.

      shopify-graphql-learning-kit-page-info-retrieve

      Verwenden von „pageInfo“, um festzustellen, ob zusätzliche Seiten abgerufen werden müssen. In GitHub Gist anzeigen.

      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.

      shopify-graphql-learning-kit-select-cursor
      Auswahl des Cursors. In GitHub Gist anzeigen.

      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.

      Hinweis: Dies entspricht im Wesentlichen der Verwendung von „since_id“ auf der REST Admin-API.

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

      shopify-graphql-learning-kit-cursor-paginate
      Paginieren mit dem Cursor. In GitHub Gist anzeigen.

      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 <TYPE>“ 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.

      shopify-graphql-learning-kit-transversing-connections
      Durchlaufen von Connections, um festzustellen, wo ein Line Item auf Lager ist. In GitHub Gist anzeigen.

      Mehrere Queries: Eine Anfrage

      Du kannst mehrere Queries oder Mutationen in einer 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: <dein-benutzerdefinierter-name>: <query/name-der-aufzurufenden-mutation>
      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.

      shopify-graphql-learning-kit-multiple-mutations
      Durchführen mehrerer Mutationen innerhalb eines einzigen Aufrufs. In GitHub Gist anzeigen.

      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 die Fähigkeiten deiner App und erspart dir einige REST-Aufrufe.

      Apps für Shopify-Händler erstellen

      Ganz gleich, ob du Apps für den Shopify App Store erstellst, private Dienstleistungen zur Entwicklung von Apps anbietest oder nach Möglichkeiten suchst, deine Benutzerbasis zu vergrößern – mit dem Shopify-Partnerprogramm stellst du die Weichen auf Erfolg. Melde dich kostenlos an und erhalte Zugang zu Bildungsressourcen, Vorschauumgebungen für Entwickler und Möglichkeiten für wiederkehrende Umsatzbeteiligungen.



      Dieser Beitrag von Alex Bradley erschien zuerst auf dem englischen Shopify Blog und wurde übersetzt.

      Bring dein Geschäft mit dem Shopify-Partnerprogramm voran

      Mehr Informationen