Blijvende GraphQL-query's persisted-graphql-queries

Blijvende query's zijn GraphQL query's die worden gemaakt en opgeslagen op de Adobe Experience Manager (AEM) as a Cloud Service server. Ze kunnen worden aangevraagd met een GET-aanvraag door clienttoepassingen. De reactie van een verzoek van de GET kan bij de verzender en lagen CDN in het voorgeheugen ondergebracht worden, die uiteindelijk de prestaties van de het verzoeken cliënttoepassing verbeteren. Dit verschilt van standaard GraphQL query's, die worden uitgevoerd met behulp van POST-aanvragen waarbij de reactie niet gemakkelijk in cache kan worden geplaatst.

NOTE
Blijvende query's worden aanbevolen. Zie Aanbevolen werkwijzen voor GraphQL-query (Dispatcher) voor details, en de verwante configuratie van de Verzender.

De GraphiQL IDE is beschikbaar in AEM voor u om uw GraphQL-query's te ontwikkelen, te testen en voort te zetten voordat overbrengen naar uw productieomgeving. Voor gevallen die aanpassing vereisen (bijvoorbeeld wanneer cache aanpassen) u de API kunt gebruiken; zie het cURL-voorbeeld in Een GraphQL-query laten doorgaan.

Blijvende query's en eindpunten persisted-queries-and-endpoints

De aanhoudende vragen moeten altijd het eindpunt met betrekking tot de geschikte configuratie van Plaatsen; dus kunnen ze beide of beide gebruiken:

  • De globale configuratie en het eindpunt de vraag heeft toegang tot alle Modellen van het Fragment van de Inhoud.
  • De specifieke configuratie(s) van Plaatsen en eindpunt(s) Creërend een persisted vraag voor een specifieke configuratie van Plaatsen vereist een overeenkomstig plaats-configuratie-specifiek eindpunt (om toegang tot de verwante Modellen van het Fragment van de Inhoud te verlenen).
    Bijvoorbeeld, om een voortgeduurde vraag specifiek voor de configuratie van Plaatsen te creëren WKND, moet een overeenkomstige WKND-Specifieke configuratie van Plaatsen, en een WKND-Specifiek eindpunt vooraf worden gecreeerd.
NOTE
Zie Functionaliteit van inhoudsfragment inschakelen in configuratievenster voor meer informatie .
De Aangehouden GraphQL-query's moet worden toegelaten, voor de aangewezen configuratie van Plaatsen.

Als er bijvoorbeeld een bepaalde query wordt uitgevoerd, my-query, die een model gebruikt my-model vanuit de configuratie Sites my-conf:

  • U kunt een query maken met de opdracht my-conf specifiek eindpunt, en dan wordt de vraag bewaard als volgt:
    /conf/my-conf/settings/graphql/persistentQueries/my-query
  • U kunt dezelfde query maken met global eindpunt, maar dan wordt de vraag bewaard als volgt:
    /conf/global/settings/graphql/persistentQueries/my-query
NOTE
Dit zijn twee verschillende query's die zijn opgeslagen onder verschillende paden.
Ze gebruiken gewoon hetzelfde model, maar via verschillende eindpunten.

Een GraphQL-query laten doorgaan how-to-persist-query

Aanbevolen wordt om query's in een AEM ontwerpomgeving in eerste instantie voort te zetten en vervolgens de query overdragen naar uw productie AEM publicatieomgeving, voor gebruik door toepassingen.

Er zijn verschillende methoden om query's te blijven uitvoeren, waaronder:

GraphiQL IDE is de voorkeur methode voor het voortduren van vragen. Om een bepaalde vraag voort te zetten gebruikend cURL opdrachtregelgereedschap:

  1. Bereid de vraag door PUTing het aan het nieuwe eindpunt URL voor /graphql/persist.json/<config>/<persisted-label>.

    Maak bijvoorbeeld een doorlopende query:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
        -d \
    '{
      articleList {
        items{
            _path
            author
            main {
                json
            }
        }
      }
    }'
    
  2. Controleer nu het antwoord.

    Controleer bijvoorbeeld of het programma is gelukt:

    code language-json
    {
      "action": "create",
      "configurationName": "wknd",
      "name": "plain-article-query",
      "shortPath": "/wknd/plain-article-query",
      "path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
    }
    
  3. U kunt de voortgezette vraag dan verzoeken door URL te winnen /graphql/execute.json/<shortPath>.

    Gebruik bijvoorbeeld de voortgezette query:

    code language-shell
    $ curl -X GET \
        http://localhost:4502/graphql/execute.json/wknd/plain-article-query
    
  4. Werk een voortgezette vraag door POSTing aan een reeds bestaand vraagweg bij.

    Gebruik bijvoorbeeld de voortgezette query:

    code language-shell
    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
        -d \
    '{
      articleList {
        items{
            _path
            author
            main {
                json
            }
          referencearticle {
            _path
          }
        }
      }
    }'
    
  5. Een onbewerkte query maken.

    Bijvoorbeeld:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-wrapped" \
        -d \
    '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }"}'
    
  6. Creeer een verpakte onbewerkte vraag met geheim voorgeheugencontrole.

    Bijvoorbeeld:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
        -d \
    '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'
    
  7. Maak een doorlopende query met parameters:

    Bijvoorbeeld:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-parameters" \
        -d \
    'query GetAsGraphqlModelTestByPath($apath: String!, $withReference: Boolean = true) {
      articleByPath(_path: $apath) {
        item {
          _path
            author
            main {
            plaintext
            }
            referencearticle @include(if: $withReference) {
            _path
            }
          }
        }
      }'
    

Hoe te om een Verlengde vraag uit te voeren execute-persisted-query

Een clienttoepassing vraagt een aanvraag tot GET met de volgende syntaxis uit om een query met behoud van waarden uit te voeren:

GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>

Wanneer PERSISTENT_PATH is een verkort pad naar de opslaglocatie van de Persisted-query.

  1. Bijvoorbeeld: wknd is de configuratienaam en plain-article-query is de naam van de Persisted-query. De query uitvoeren:

    code language-shell
    $ curl -X GET \
        https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
    
  2. Een query uitvoeren met parameters.

    note note
    NOTE
    De variabelen en de waarden van de vraag moeten behoorlijk zijn gecodeerd bij het uitvoeren van een blijvende query.

    Bijvoorbeeld:

    code language-xml
    $ curl -X GET \
        "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query-parameters%3Bapath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fmagazine%2Falaska-adventure%2Falaskan-adventures%3BwithReference%3Dfalse
    

    Zie gebruiken queryvariabelen voor meer informatie .

Query-variabelen gebruiken query-variables

De variabelen van de vraag kunnen met Verblijfsde Vragen worden gebruikt. De vraagvariabelen worden toegevoegd aan het verzoek vooraf bepaald met een puntkomma (;) met de naam en de waarde van de variabele. Meerdere variabelen worden gescheiden door puntkomma's.

Het patroon ziet er als volgt uit:

<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2

De volgende query bevat bijvoorbeeld een variabele activity een lijst filteren op basis van een activiteitwaarde:

query getAdventuresByActivity($activity: String!) {
      adventureList (filter: {
        adventureActivity: {
          _expressions: [
            {
              value: $activity
            }
          ]
        }
      }){
        items {
          _path
        adventureTitle
        adventurePrice
        adventureTripLength
      }
    }
  }

Deze query kan worden uitgevoerd onder een pad wknd/adventures-by-activity. Om de Permanente vraag te roepen waar activity=Camping het verzoek zou er als volgt uitzien :

<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping

De UTF-8-codering %3B is for ; en %3D is de codering voor =. De vraagvariabelen en om het even welke speciale karakters moeten correct gecodeerd voor de Persisted query die moet worden uitgevoerd.

Query-variabelen gebruiken - Aanbevolen werkwijzen query-variables-best-practices

Wanneer het gebruiken van variabelen in uw vragen zijn er een paar beste praktijken die zouden moeten worden gevolgd:

  • Codering als algemene aanpak wordt altijd aangeraden alle speciale tekens te coderen, bijvoorbeeld ;, =, ?, &, onder andere.

  • Semicolon Persisted query's die meerdere variabelen gebruiken (die door puntkomma's worden gescheiden) moeten een van de volgende opties hebben:

    • de gecodeerde puntkomma (%3B); dit wordt ook bereikt door de URL te coderen
    • of een volgpuntkomma die aan het einde van de query is toegevoegd
  • CACHE_GRAPHQL_PERSISTED_QUERIES
    Wanneer CACHE_GRAPHQL_PERSISTED_QUERIES wordt toegelaten voor de Dispatcher, dan parameters die bevatten / of \ tekens in hun waarde worden twee keer gecodeerd op Dispatcher-niveau.
    Om deze situatie te voorkomen:

    • Inschakelen DispatcherNoCanonURL op de Dispatcher.
      Hierdoor wordt de Dispatcher opgedragen de oorspronkelijke URL door te sturen naar AEM, zodat dubbele coderingen worden voorkomen.
      Deze instelling werkt momenteel echter alleen op het tabblad vhost niveau, dus als u al Dispatcher-configuraties hebt om URL's te herschrijven (bijvoorbeeld bij het gebruik van verkorte URL's) hebt u mogelijk een aparte vhost voor doorlopende vraag-URL's.

    • Verzenden / of \ tekens niet gecodeerd.
      Wanneer het roepen van persistente vraag URL zorg ervoor dat allen / of \ tekens blijven niet gecodeerd in de waarde van aanhoudend queryvariabelen.

      note note
      NOTE
      Deze optie wordt alleen aanbevolen als de DispatcherNoCanonURL oplossing kan om welke reden dan ook niet worden geïmplementeerd.
  • CACHE_GRAPHQL_PERSISTED_QUERIES

    Wanneer CACHE_GRAPHQL_PERSISTED_QUERIES is ingeschakeld voor de Dispatcher, en vervolgens de ; kan niet worden gebruikt in de waarde van een variabele.

Door uw doorlopende query's in cache te plaatsen caching-persisted-queries

De blijvende vragen worden geadviseerd aangezien zij in het voorgeheugen onder kunnen brengen bij Dispatcher en de lagen van het Netwerk van de Levering van de Inhoud (CDN), uiteindelijk verbeterend de prestaties van de het vragen cliënttoepassing.

AEM maakt de cache standaard ongeldig op basis van de definitie Tijd tot live (TTL). Deze TTLs kan door de volgende parameters worden bepaald. Deze parameters zijn op verschillende manieren toegankelijk, waarbij de namen variëren volgens het gebruikte mechanisme:

Cachetype
HTTP-header
cURL
OSGi-configuratie
Cloud Manager
Browser
max-age
cache-control : max-age
cacheControlMaxAge
graphqlCacheControl
CDN
s-maxage
surrogate-control : max-age
surrogateControlMaxAge
graphqlSurrogateControl
CDN
stale-while-revalidate
surrogate-control : stale-while-revalidate
surrogateControlStaleWhileRevalidate
graphqlStaleWhileRevalidate
CDN
stale-if-error
surrogate-control : stale-if-error
surrogateControlStaleIfError
graphqlStaleIfError

Auteursinstanties author-instances

Voor auteur-instanties zijn de standaardwaarden:

  • max-age : 60
  • s-maxage : 60
  • stale-while-revalidate : 86400
  • stale-if-error : 86400

Hiervoor gold het volgende:

Publish-instanties publish-instances

Voor publicatie-instanties zijn de standaardwaarden:

  • max-age : 60
  • s-maxage : 7200
  • stale-while-revalidate : 86400
  • stale-if-error : 86400

Deze kunnen worden overschreven:

Het beheren van de Kopballen van het Geheime voorgeheugen van HTTP in GrahiQL winde http-cache-headers-graphiql-ide

GraphiQL IDE - zie Blijvende query's opslaan

Het beheren van Geheime voorgeheugen op het Aanhoudende Niveau van de Vraag cache-persisted-query-level

Dit omvat het posten van de vraag aan AEM gebruikend cURL in uw interface van de bevellijn.

Een voorbeeld van de methode PUT (create):

curl -u admin:admin -X PUT \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

Een voorbeeld van de methode POST (update):

curl -u admin:admin -X POST \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

De cache-control kan worden ingesteld tijdens het maken (PUT) of later (bijvoorbeeld via een aanvraag voor een POST). Het cache-control is optioneel wanneer u de aanhoudend query maakt, omdat AEM de standaardwaarde kan opgeven. Zie Een GraphQL-query laten doorgaan, bijvoorbeeld om een query met cURL voort te zetten.

Cache beheren met variabelen van Cloud Manager cache-cloud-manager-variables

Omgevingsvariabelen van Cloud Manager U kunt de vereiste waarden definiëren in Cloud Manager:

Naam
Waarde
Toegepaste service
Type
graphqlStaleIfError
86400
passend
passend
graphqlSurrogateControl
600
passend
passend

Het beheren van Geheime voorgeheugen met een configuratie OSGi cache-osgi-configration

Als u de cache wereldwijd wilt beheren, kunt u vorm de montages OSGi voor de Configuratie van blijvende query-service.

NOTE
Voor geheim voorgeheugencontrole, is de configuratie OSGi slechts aangewezen voor publiceer instanties. De configuratie bestaat bij de instanties van de auteur, maar wordt genegeerd.
NOTE
De Configuratie van blijvende query-service wordt ook gebruikt voor configureren van antwoordcode voor query.

De standaard configuratie OSGi voor publiceer instanties:

  • leest de variabelen van de Manager van de Wolk als beschikbaar:

    table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 layout-auto
    OSGi-configuratieeigenschap leest dit Variabele voor wolkenbeheer
    cacheControlMaxAge leest graphqlCacheControl
    surrogateControlMaxAge leest graphqlSurrogateControl
    surrogateControlStaleWhileRevalidate leest graphqlStaleWhileRevalidate
    surrogateControlStaleIfError leest graphqlStaleIfError
  • en als niet beschikbaar, gebruikt de configuratie OSGi standaardwaarden voor publicatie-instanties.

De antwoordcode voor de query configureren configuring-query-response-code

Standaard worden de PersistedQueryServlet verzendt een 200 reactie wanneer het een vraag uitvoert, ongeacht het daadwerkelijke resultaat.

U kunt vorm de montages OSGi voor de Configuratie van blijvende query-service om te controleren of meer gedetailleerde statuscodes door de /execute.json/persisted-query eindpunt, wanneer er een fout in de persisted vraag is.

NOTE
De Configuratie van blijvende query-service wordt ook gebruikt voor cache beheren.

Het veld Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) kan worden gedefinieerd als vereist:

  • false (standaardwaarde): het maakt niet uit of de voortgezette query succesvol is of niet. De Content-Type header returned is application/jsonen de /execute.json/persisted-query altijd retourneert de statuscode 200.

  • true: De geretourneerde Content-Type is application/graphql-response+json, en het eindpunt zal de aangewezen antwoordcode terugkeren wanneer er om het even welke vorm van fout bij het runnen van de persisted vraag is:

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
    Code Beschrijving
    200 Geslaagd antwoord
    400 Geeft aan dat er koppen ontbreken of dat er een probleem is met het voortgezette querypad. Configuratienaam niet opgegeven, achtervoegsel niet opgegeven en andere.
    Zie Problemen oplossen - GraphQL-eindpunt niet geconfigureerd.
    404 Kan de gewenste bron niet vinden. Bijvoorbeeld, is het eindpunt Graphql niet beschikbaar op de server.
    Zie Problemen oplossen - Ontbrekend pad in de GraphQL-URL voor blijvende query.
    500 Interne serverfout. Bijvoorbeeld validatiefouten, persistentiefout en andere.
    note note
    NOTE
    Zie ook https://graphql.github.io/graphql-over-http/draft/#sec-Status-Codes

De URL van de query coderen voor gebruik door een app encoding-query-url

Voor gebruik door een toepassing worden speciale tekens gebruikt bij het samenstellen van queryvariabelen (puntkomma's (;), gelijkteken (=), slashes /) moet worden omgezet om de overeenkomstige UTF-8-codering te gebruiken.

Bijvoorbeeld:

curl -X GET \ "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/adventure-by-path%3BadventurePath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fadventures%2Fbali-surf-camp%2Fbali-surf-camp"

De URL kan worden opgesplitst in de volgende onderdelen:

URL-onderdeel
Beschrijving
/graphql/execute.json
Blijvend vraageindpunt
/wknd/adventure-by-path
Pad voor permanente query
%3B
Codering van ;
adventurePath
Query-variabele
%3D
Codering van =
%2F
Codering van /
%2Fcontent%2Fdam...
Gecodeerd pad naar het inhoudsfragment

In onbewerkte tekst ziet de aanvraag-URI er als volgt uit:

/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp

Als u een voortgezette query in een client-app wilt gebruiken, moet de SDK van de client zonder kop worden gebruikt voor JavaScript, Java, of NodeJS. De Headless Client SDK codeert alle queryvariabelen automatisch naar behoren in de aanvraag.

Het overbrengen van een blijvende vraag aan uw milieu van de Productie transfer-persisted-query-production

De gepersisteerde vragen zouden altijd op de dienst van de Auteur van de AEM moeten worden gecreeerd en dan (herhaald) aan de dienst van AEM Publish gepubliceerd. Vaak, worden de Persisted vragen gecreeerd en op lagere milieu's zoals lokale of milieu's van de Ontwikkeling getest. Het is dan noodzakelijk om Persisted query's naar omgevingen op een hoger niveau te promoten, zodat ze uiteindelijk beschikbaar worden gesteld op een productie AEM Publish-omgeving voor gebruik door clienttoepassingen.

Voorbehouden query's verpakken

De blijvende vragen kunnen in worden gebouwd AEM. AEM pakketten kunnen vervolgens worden gedownload en geïnstalleerd in verschillende omgevingen. AEM Pakketten kunnen ook worden gerepliceerd vanuit een AEM Auteur-omgeving naar AEM Publish-omgevingen.

Een pakket maken:

  1. Navigeren naar Gereedschappen > Implementatie > Pakketten.
  2. Een nieuw pakket maken door te tikken Pakket maken. Hiermee wordt een dialoogvenster geopend waarin het pakket wordt gedefinieerd.
  3. In het dialoogvenster Pakketdefinitie, onder Algemeen Voer een Naam zoals "wknd-persistent-questions".
  4. Voer een versienummer in, bijvoorbeeld "1.0".
  5. Onder Filters een nieuwe Filter. Gebruik de Finder van de Weg om te selecteren persistentQueries onder de configuratie. Bijvoorbeeld voor wknd configuratie, het volledige pad is /conf/wknd/settings/graphql/persistentQueries.
  6. Selecteren Opslaan om de nieuwe pakketdefinitie op te slaan en het dialoogvenster te sluiten.
  7. Selecteer de Opbouwen in de gemaakte pakketdefinitie.

Nadat het pakket is gemaakt, kunt u:

  • Downloaden het pakket en heruploaden in een andere omgeving.
  • Repliceren het pakket door te tikken Meer > Repliceren. Hierdoor wordt het pakket gerepliceerd naar de aangesloten AEM Publish-omgeving.
recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab