GraphQL-query's

Dit is deel 2 van de reeks voor GraphQL en Adobe Commerce. In deze zelfstudie en video leert u meer over GraphQL-query's en hoe u deze kunt uitvoeren tegen Adobe Commerce.

Verwante video's en zelfstudies over GraphQL in deze serie

Voorbeeld van GraphQL Syntax

Laten we meteen naar de GraphQL-querysyntaxis duiken met een volledig voorbeeld. (Herinner me, kunt u dit tegen https://venia.magento.com/graphql proberen.)

Bekijk de volgende GraphQL-query, die stuk voor stuk wordt opgesplitst:

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

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

Een plausibele reactie van een GraphQL-server voor de bovenstaande query zou kunnen zijn:

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

In het bovenstaande voorbeeld wordt uitgegaan van het GraphQL-schema voor Adobe Commerce dat buiten de box wordt weergegeven en dat op de server is gedefinieerd. In deze aanvraag
U kunt meerdere typen gegevens tegelijk opvragen. De query geeft exact de gewenste velden weer en de geretourneerde gegevens worden opgemaakt
vergelijkbaar met de query zelf.

Zoeken naar wat je wilt

country en categories in het voorbeeld vertegenwoordigen twee verschillende 'query's' voor twee verschillende soorten gegevens. In tegenstelling tot een traditioneel API-paradigma zoals REST, dat afzonderlijke en expliciete eindpunten voor elk gegevenstype definieert. GraphQL geeft u de flexibiliteit om één enkel eindpunt met een uitdrukking te vragen die vele soorten gegevens in één keer kan halen.

Op dezelfde manier specificeert de vraag precies de gebieden die voor zowel country (id en full_name_english) als categories (items worden gewenst, die zelf een subselectie van gebieden) heeft, en de gegevens u achterspiegels ontvangt die gebiedsspecificatie. Er zijn waarschijnlijk nog veel meer velden beschikbaar voor deze gegevenstypen, maar u krijgt alleen de gewenste velden terug.

Argumenten

Terwijl de velden die u wilt retourneren, tussen de accolades van elk type zijn opgegeven, worden benoemde argumenten en waarden voor deze velden tussen haakjes achter de typenaam opgegeven. Argumenten zijn vaak optioneel en hebben vaak invloed op de manier waarop queryresultaten worden gefilterd, opgemaakt of op een andere manier worden getransformeerd.

U geeft een id -argument door aan country , waarbij u opgeeft welk land u wilt opvragen, en een filters -argument voor categories .

Velden helemaal omlaag

Hoewel u country en categories wellicht als afzonderlijke query's of entiteiten wilt zien, bestaat de volledige structuur die in de query wordt uitgedrukt, eigenlijk alleen uit velden. De expressie van products verschilt syntactisch niet van die van categories . Beide zijn velden, en er is geen verschil tussen hun constructie.

Elke GraphQL-gegevensgrafiek heeft één 'root'-type (meestal Query genoemd) om de structuur te starten. De typen die vaak als entiteiten worden beschouwd, worden toegewezen aan velden in deze hoofdmap. Met de voorbeeldquery wordt eigenlijk één algemene query voor het hoofdtype uitgevoerd en worden de velden country en categories geselecteerd. Vervolgens selecteert u subvelden van die velden enzovoort, mogelijk verschillende niveaus diep. Wanneer het retourneringstype van een veld een complex type is (bijvoorbeeld een type met eigen velden in plaats van een scalair type), blijft u de gewenste velden selecteren.

Dit concept van geneste velden is ook de reden waarom u argumenten voor products (pageSize en currentPage) kunt doorgeven, net als voor het veld op hoofdniveau categories .

Variabelen

Probeer een andere query:

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

fragment productDetails on ProductInterface {
    sku
    name
}

Het eerste ding om van nota te nemen is toegevoegd het sleutelwoord query vóór het openen van de steun van de vraag, samen met een verrichtingsnaam (getProducts). Deze naam van de bewerking is willekeurig en komt niet overeen met iets in het serverschema. Deze syntaxis is toegevoegd ter ondersteuning van de introductie van variabelen.

In de vorige vraag, hebt u hard-gecodeerde waarden voor de argumenten van uw gebieden direct, als koorden of gehelen. De GraphQL-specificatie biedt echter ondersteuning van de eerste klasse voor het scheiden van gebruikersinvoer van de hoofdquery met behulp van variabelen.

In de nieuwe query gebruikt u haakjes vóór het accolade openen van de gehele query om een $search variabele te definiëren (variabelen gebruiken altijd de syntaxis van het voorvoegsel van het dollarteken). Deze variabele wordt aan het argument search for products doorgegeven.

Wanneer een query variabelen bevat, wordt verwacht dat het GraphQL-verzoek een afzonderlijk JSON-gecodeerd woordenboek met waarden naast de query zelf bevat. Voor de vraag hierboven, zou u volgende JSON van veranderlijke waarden naast het vraaglichaam kunnen verzenden:

{
    "search": "VT01"
}

In om het even welke GraphQL-bewuste cliënt die u voor het testen (zoals Altair en GraphiQL) gebruikt, steunt UI het ingaan van de variabelen JSON afzonderlijk van de vraag.

Zoals u ziet dat de feitelijke HTTP-aanvraag voor een GraphQL-query de hoofdtekst van de query ''query: {string}'' bevat, bevat elke aanvraag met een Variables-woordenboek gewoon een extra 'variables: {json}' in dezelfde hoofdtekst, waarbij {json} de JSON-tekenreeks met de variabelenwaarden is.

De nieuwe vraag gebruikt ook a fragment (productDetails) om de zelfde gebiedsselectie op veelvoudige plaatsen opnieuw te gebruiken. las meer over fragmenten{target=“_blank”} in de documentatie van GraphQL.

Handige GraphQL-bronnen