GraphQL-Abfragen

Dies ist Teil 2 der Serie für GraphQL und Adobe Commerce. In diesem Tutorial und Video erfahren Sie mehr über GraphQL-Abfragen und wie Sie diese mit Adobe Commerce durchführen.

Verwandte Videos und Tutorials zu GraphQL in dieser Reihe

Beispiel für eine GraphQL-Syntax

Lassen Sie uns mit einem vollständigen Beispiel direkt in die GraphQL-Abfragesyntax eintauchen. (Denken Sie daran, dass Sie dies selbst gegen https://venia.magento.com/graphql versuchen können.)

Beachten Sie die folgende GraphQL-Abfrage, die Stück für Stück aufgeschlüsselt ist:

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

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

Eine plausible Antwort eines GraphQL-Servers für die obige Abfrage könnte sein:

{
  "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"
              }
            ]
          }
        }
      ]
    }
  }
}

Das obige Beispiel stützt sich auf das vorkonfigurierte GraphQL-Schema für Adobe Commerce, das auf dem -Server definiert ist. In dieser Anfrage gilt Folgendes:
Gleichzeitiges Abfragen mehrerer Datentypen. Die Abfrage gibt genau die gewünschten Felder aus, und die zurückgegebenen Daten sind formatiert
Ähnlich wie die Abfrage selbst.

Fragen nach dem, was Sie möchten

country und categories im Beispiel stellen zwei verschiedene „Abfragen“ für zwei verschiedene Arten von Daten dar. Im Gegensatz zu einem herkömmlichen API-Paradigma wie REST, mit dem separate und explizite Endpunkte für jeden Datentyp definiert werden. GraphQL bietet Ihnen die Flexibilität, einen einzelnen Endpunkt mit einem Ausdruck abzufragen, der viele Datentypen gleichzeitig abrufen kann.

Ebenso gibt die Abfrage genau die Felder an, die sowohl für country (id und full_name_english) als auch für categories (items, das selbst eine Unterauswahl von Feldern aufweist) gewünscht sind, und die empfangenen Daten spiegeln diese Feldspezifikation wider. Für diese Datentypen stehen vermutlich noch viel mehr Felder zur Verfügung, Sie erhalten jedoch nur das zurückgegeben, was Sie angefordert haben.

Argumente

Während die Felder, die zurückgegeben werden sollen, in den geschweiften Klammern jedes Typs angegeben werden, werden benannte Argumente und Werte für sie in Klammern nach dem Typnamen angegeben. Argumente sind häufig optional und beeinflussen oft die Art und Weise, wie Abfrageergebnisse gefiltert, formatiert oder anderweitig transformiert werden.

Sie übergeben ein id Argument an country, das das jeweilige Land angibt, das abgefragt werden soll, und ein filters Argument für categories.

Felder ganz nach unten

Während Sie dazu neigen, country und categories als separate Abfragen oder Entitäten zu betrachten, besteht die gesamte in Ihrer Abfrage ausgedrückte Baumstruktur tatsächlich nur aus Feldern. Der Ausdruck von products unterscheidet sich syntaktisch nicht von dem von categories. Beide sind Felder, und es gibt keinen Unterschied zwischen ihrer Konstruktion.

Jedes GraphQL-Datendiagramm hat einen einzigen „Stamm“-Typ (in der Regel als "Query" bezeichnet), um die Baumstruktur zu starten, und die Typen, die häufig als Entitäten betrachtet werden, werden den Feldern auf diesem Stamm zugewiesen. Die Beispielabfrage erstellt tatsächlich eine generische Abfrage für den Stammentyp und wählt die Felder country und categories aus. Anschließend werden Unterfelder dieser Felder ausgewählt usw., die möglicherweise mehrere Ebenen tief sind. Wenn der Rückgabetyp eines Felds ein komplexer Typ ist (z. B. eines mit eigenen Feldern statt eines Skalartyps), wählen Sie weiterhin die gewünschten Felder aus.

Dieses Konzept verschachtelter Felder ist auch der Grund, warum Sie Argumente für products (pageSize und currentPage) auf die gleiche Weise übergeben können wie für das categories der obersten Ebene.

Variablen

Versuchen Sie eine andere Abfrage:

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

fragment productDetails on ProductInterface {
    sku
    name
}

Zunächst ist zu beachten, dass der vor der öffnenden Klammer der Abfrage hinzugefügte query das Keyword ist, zusammen mit einem Vorgangsnamen (getProducts). Dieser Vorgangsname ist beliebig und entspricht keinem Element im Server-Schema. Diese Syntax wurde hinzugefügt, um die Einführung von Variablen zu unterstützen.

In der vorherigen Abfrage haben Sie die Werte für die Argumente Ihrer Felder direkt als Zeichenfolgen oder Ganzzahlen hartcodiert. Die GraphQL-Spezifikation bietet jedoch erstklassige Unterstützung für die Trennung der Benutzereingabe von der Hauptabfrage mithilfe von Variablen.

In der neuen Abfrage verwenden Sie Klammern vor der öffnenden Klammer der gesamten Abfrage, um eine $search Variable zu definieren (Variablen verwenden immer die Dollarzeichen-Präfixsyntax). Diese Variable wird dem search-Argument für products bereitgestellt.

Wenn eine Abfrage Variablen enthält, wird erwartet, dass die GraphQL-Anfrage neben der Abfrage selbst ein separates JSON-kodiertes Wertewörterbuch enthält. Für die obige Abfrage können Sie zusätzlich zum Abfragetext die folgende JSON-Datei mit Variablenwerten senden:

{
    "search": "VT01"
}

In jedem GraphQL-fähigen Client, den Sie zum Testen verwenden (z. B. Altair und GraphiQL), unterstützt die Benutzeroberfläche die Eingabe der JSON-Variablen getrennt von der Abfrage.

Wie Sie gesehen haben, dass die eigentliche HTTP-Anfrage für eine GraphQL-Abfrage „query: {string}" in ihrem Hauptteil enthält, enthält jede Anfrage mit einem Variablenwörterbuch einfach ein zusätzliches „variables: {json}" in demselben Hauptteil, wobei {json} die JSON-Zeichenfolge mit den Variablenwerten ist.

Die neue Abfrage verwendet auch ein Fragment (productDetails), um dieselbe Feldauswahl an mehreren Stellen wiederzuverwenden. Weitere Informationen über Fragmente findenin der Dokumentation zu GraphQL.

Nützliche GraphQL-Ressourcen