Beständiga GraphQL-frågor persisted-queries-caching

Beständiga frågor är GraphQL-frågor som skapas och lagras på Adobe Experience Manager (AEM)-servern. De kan begäras med en GET-begäran från klientprogram. Svaret på en GET-förfrågan kan cachas i Dispatcher- och Content Delivery Network-lager (CDN), vilket i slutänden förbättrar prestanda för det begärande klientprogrammet. Detta skiljer sig från vanliga GraphQL-frågor, som körs med förfrågningar från POSTER där svaret inte enkelt kan cachas.

GraphiQL IDE är tillgänglig i AEM så att du kan utveckla, testa och behålla dina GraphQL-frågor innan du överför till produktionsmiljön. Om du behöver anpassa (till exempel när du anpassar cachen) kan du använda API:t, se exemplet på cURL i Så här gör du för att behålla en GraphQL-fråga.

Beständiga frågor och slutpunkter persisted-queries-and-endpoints

Beständiga frågor måste alltid använda den slutpunkt som är relaterad till lämplig platskonfiguration, så att de kan använda antingen eller båda:

  • Den globala konfigurationen och slutpunkten
    Frågan har åtkomst till alla modeller för innehållsfragment.
  • Specifika platskonfigurationer och slutpunkter
    För att skapa en beständig fråga för en specifik platskonfiguration krävs en motsvarande platskonfigurationsspecifik slutpunkt (för att ge åtkomst till relaterade modeller för innehållsfragment).
    Om du till exempel vill skapa en beständig fråga specifikt för WKND-platskonfigurationen, måste en motsvarande WKND-specifik platskonfiguration och en WKND-specifik slutpunkt skapas i förväg.
NOTE
Mer information finns i Aktivera funktionen för innehållsfragment i konfigurationsläsaren.
GraphQL beständiga frågor måste aktiveras för rätt platskonfiguration.

Om det till exempel finns en viss fråga med namnet my-query som använder modellen my-model från platskonfigurationen my-conf:

  • Du kan skapa en fråga med den my-conf specifika slutpunkten och sedan sparas frågan så här:
    /conf/my-conf/settings/graphql/persistentQueries/my-query
  • Du kan skapa samma fråga med global-slutpunkten, men sedan sparas frågan så här:
    /conf/global/settings/graphql/persistentQueries/my-query
NOTE
Det här är två olika frågor - sparade under olika sökvägar.
De råkar bara använda samma modell, men via olika slutpunkter.

Så här behåller du en GraphQL-fråga how-to-persist-query

Vi rekommenderar att du till att börja med behåller frågor i en AEM redigeringsmiljö och sedan överför frågan till din AEM publiceringsmiljö, som kan användas av program.

Det finns olika metoder för beständiga frågor, bland annat:

GraphiQL IDE är den föredragna metoden för beständiga frågor. Så här behåller du en given fråga med kommandoradsverktyget cURL:

  1. Förbered frågan genom att PUTing den till den nya slutpunkts-URL:en /graphql/persist.json/<config>/<persisted-label>.

    Skapa till exempel en beständig fråga:

    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. Kontrollera svaret nu.

    Kontrollera till exempel om åtgärden lyckades:

    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. Du kan sedan begära den beständiga frågan genom att GETing anger URL:en /graphql/execute.json/<shortPath>.

    Använd till exempel den beständiga frågan:

    code language-shell
    $ curl -X GET \
        http://localhost:4502/graphql/execute.json/wknd/plain-article-query
    
  4. Uppdatera en beständig fråga genom POSTing till en redan befintlig frågesökväg.

    Använd till exempel den beständiga frågan:

    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. Skapa en omsluten vanlig fråga.

    Till exempel:

    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. Skapa en omsluten oformaterad fråga med cachekontroll.

    Till exempel:

    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. Skapa en beständig fråga med parametrar:

    Till exempel:

    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
            }
          }
        }
      }'
    

Så här kör du en fråga som är sparad execute-persisted-query

För att köra en Persistent-fråga gör ett klientprogram en GET-begäran med följande syntax:

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

Där PERSISTENT_PATH är en förkortad sökväg till den plats där den beständiga frågan sparas.

  1. wknd är till exempel konfigurationsnamnet och plain-article-query är namnet på den beständiga frågan. Så här kör du frågan:

    code language-shell
    $ curl -X GET \
        https://localhost:4502/graphql/execute.json/wknd/plain-article-query
    
  2. Kör en fråga med parametrar.

    note note
    NOTE
    Frågevariabler och -värden måste vara korrekt kodade när en Persisted-fråga körs.

    Till exempel:

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

    Mer information finns i Använda frågevariabler.

Använda frågevariabler query-variables

Frågevariabler kan användas med beständiga frågor. Frågevariablerna läggs till i begäran med prefixet semikolon (;) med variabelnamnet och variabelvärdet. Flera variabler avgränsas med semikolon.

Mönstret ser ut så här:

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

Följande fråga innehåller till exempel variabeln activity för att filtrera en lista baserat på ett aktivitetsvärde:

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

Den här frågan kan sparas under sökvägen wknd/adventures-by-activity. Så här anropar du den beständiga frågan där activity=Camping begäran skulle se ut:

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

Observera att %3B är UTF-8-kodning för ; och %3D är kodning för =. Frågevariablerna och eventuella specialtecken måste vara kodade korrekt för att den beständiga frågan ska kunna köras.

Cachelagra beständiga frågor caching-persisted-queries

Beständiga frågor rekommenderas eftersom de kan cachelagras på Dispatcher - och CDN-lagren (Content Delivery Network), vilket i slutänden förbättrar prestandan för det begärande klientprogrammet.

Som standard blir cachen ogiltig AEM baserat på en TTL-definition (Time To Live). Dessa TTL:er kan definieras med följande parametrar. Dessa parametrar kan nås på olika sätt, med variationer i namnen beroende på vilken mekanism som används:

Cache-typ
HTTP-huvud
cURL
OSGi-konfiguration
Webbläsare
max-age
cache-control : max-age
cacheControlMaxAge
CDN
s-maxage
surrogate-control : max-age
surrogateControlMaxAge
CDN
stale-while-revalidate
surrogate-control : stale-while-revalidate
surrogateControlStaleWhileRevalidate
CDN
stale-if-error
surrogate-control : stale-if-error
surrogateControlStaleIfError

Författarinstanser author-instances

För författarinstanser är standardvärdena:

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

De var:

  • kan inte skrivas över med en OSGi-konfiguration
  • kan skrivas över av en begäran som definierar inställningar för HTTP-huvudet med cURL; den bör innehålla lämpliga inställningar för cache-control och/eller surrogate-control; se till exempel Hantera cache på den beständiga frågenivån

Publish-instanser publish-instances

Standardvärdena för publiceringsinstanser är:

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

Dessa kan skrivas över:

Hantera cache på nivån för beständig fråga cache-persisted-query-level

Detta innebär att skicka frågan till AEM med cURL i kommandoradsgränssnittet.

Ett exempel på metoden PUT (skapa):

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} }'

Ett exempel på metoden 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} }'

cache-control kan anges när den skapas (PUT) eller senare (till exempel via en POST-förfrågan). Cachekontrollen är valfri när du skapar den beständiga frågan, eftersom AEM kan ange standardvärdet. Se Så här behåller du en GraphQL-fråga om du vill se ett exempel på hur en fråga bevaras med cURL.

Hantera cache med en OSGi-konfiguration cache-osgi-configration

Om du vill hantera cacheminnet globalt kan du konfigurera OSGi-inställningarna för konfigurationen för den beständiga frågetjänsten. Annars använder den här OSGi-konfigurationen standardvärdena för publiceringsinstanser.

NOTE
OSGi-konfigurationen passar bara för publiceringsinstanser. Konfigurationen finns på författarinstanser, men ignoreras.

Kodning av fråge-URL för användning av ett program encoding-query-url

Om du vill använda ett program måste alla specialtecken som används för att skapa frågevariabler (t.ex. semikolon (;), likhetstecken (=), snedstreck /) konverteras till motsvarande UTF-8-kodning.

Till exempel:

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

URL:en kan delas upp i följande delar:

URL-del
Beskrivning
/graphql/execute.json
Beständig frågeslutpunkt
/wknd/adventure-by-path
Sökväg för beständig fråga
%3B
Kodning av ;
adventurePath
Frågevariabel
%3D
Kodning av =
%2F
Kodning av /
%2Fcontent%2Fdam...
Kodad sökväg till innehållsfragmentet

I vanlig text ser URI:n för begäran ut så här:

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

Om du vill använda en beständig fråga i en klientapp bör den AEM huvudlösa klientens SDK användas för JavaScript, Java eller NodeJS. SDK för den Headless-klienten kodar automatiskt alla frågevariabler som behövs i begäran.

Överför en beständig fråga till produktionsmiljön transfer-persisted-query-production

Beständiga frågor ska alltid skapas på en AEM författartjänst och sedan publiceras (replikeras) till en AEM Publish-tjänst. Vanligtvis skapas och testas beständiga frågor i miljöer som lokala miljöer och utvecklingsmiljöer. Det är sedan nödvändigt att befordra beständiga frågor till miljöer på högre nivå, vilket i slutänden gör dem tillgängliga i en AEM Publish-miljö för att klientprogram ska kunna använda dem.

Paketera beständiga frågor

Beständiga frågor kan byggas in i AEM paket. AEM paket kan sedan laddas ned och installeras i olika miljöer. AEM paket kan också replikeras från en AEM redigeringsmiljö till AEM Publish-miljöer.

Skapa ett paket:

  1. Navigera till Verktyg > Distribution > Paket.
  2. Skapa ett paket genom att trycka på Skapa paket. Då öppnas en dialogruta där du kan definiera paketet.
  3. I dialogrutan Paketdefinition, under Allmänt, anger du ett Namn som "wknd-persistent-queries".
  4. Ange ett versionsnummer som "1.0".
  5. Lägg till ett nytt Filter under Filter. Använd Sökväg till Finder för att välja mappen persistentQueries under konfigurationen. För konfigurationen wknd blir till exempel den fullständiga sökvägen /conf/wknd/settings/graphql/persistentQueries.
  6. Välj Spara om du vill spara den nya paketdefinitionen och stänga dialogrutan.
  7. Välj knappen Skapa i den nya paketdefinitionen.

När paketet har byggts kan du:

  • Hämta paketet och överföra det igen till en annan miljö.
  • Replikera paketet genom att trycka på Mer > Replikera. Paketet kommer att replikeras till den anslutna AEM Publish-miljön.
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2