Beständiga GraphQL-frågor

Beständiga frågor är GraphQL-frågor som skapas och lagras på Adobe Experience Manager (AEM) server. De kan begäras med en GET-begäran från klientprogram. Svaret på en begäran om GET kan cachas i skikten Dispatcher och Content Delivery Network (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.

The GraphiQL IDE finns i AEM för att du ska kunna utveckla, testa och behålla dina GraphQL-frågor innan överföra till produktionsmiljön. För ärenden som behöver anpassas (till exempel när anpassa cachen) kan du använda API:t, se exemplet med cURL i Så här behåller du en GraphQL-fråga.

Beständiga frågor och slutpunkter

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 Om du vill skapa en beständig fråga för en specifik platskonfiguration måste du ha 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.

Om det till exempel finns en viss fråga som heter my-query, som använder en modell my-model från platskonfigurationen my-conf:

• Du kan skapa en fråga med my-conf en specifik slutpunkt, och därefter sparas frågan enligt följande:
  /conf/my-conf/settings/graphql/persistentQueries/my-query
• Du kan skapa samma fråga med global slutpunkten, men frågan sparas sedan enligt följande:
  /conf/global/settings/graphql/persistentQueries/my-query

Så här behåller du en GraphQL-fråga

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

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

• GraphiQL IDE - se Sparar beständiga frågor (föredragen metod)
• cURL - se följande exempel
• Andra verktyg, inklusive Postman

GraphiQL IDE är standard metod för beständiga frågor. Bevara en given fråga med cURL kommandoradsverktyg:

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:

   $ 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:

   {
     "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 the URL /graphql/execute.json/<shortPath>.

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

   $ 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:

   $ 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:

   $ 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:

   $ 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:

   $ 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

Om du vill köra en fråga som är permanent skapar ett klientprogram en GET-begäran med följande syntax:

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

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

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

   $ curl -X GET \
       https://localhost:4502/graphql/execute.json/wknd/plain-article-query
   

2. Kör en fråga med parametrar.

   OBSERVERA

   Frågevariabler och -värden måste vara korrekta kodad när en fråga som är sparad körs.

   Till exempel:

   $ 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
   

   Se använda frågevariabler för mer information.

Använda frågevariabler

Frågevariabler kan användas med beständiga frågor. Frågevariablerna läggs till i begäran med ett 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 en variabel activity om du vill 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 en sökväg wknd/adventures-by-activity. Så här anropar du den beständiga frågan där activity=Camping begäran skulle se ut så här:

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

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

Cachelagra beständiga frågor

Beständiga frågor rekommenderas eftersom de kan cachelagras på Dispatcher och CDN-lager (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:

Författarinstanser

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; bör innehålla lämpliga inställningar för cache-control och/eller surrogate-control; finns i Hantera cache på nivån för beständig fråga

Publicera instanser

Standardvärdena för publiceringsinstanser är:

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

Dessa kan skrivas över:

• på den beständiga frågenivån; detta innebär att skicka frågan till AEM med cURL i kommandoradsgränssnittet och att publicera den beständiga frågan.

• med en OSGi-konfiguration

Hantera cache på nivån för beständig fråga

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

The cache-control kan anges vid skapande (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, för ett exempel på beständig fråga med cURL.

Hantera cache med en OSGi-konfiguration

Om du vill hantera cachen globalt kan du konfigurera OSGi-inställningarna för Konfiguration av beständig frågetjänst. Annars använder den här OSGi-konfigurationen standardvärden för publiceringsinstanser.

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

Om det används av ett program används alla specialtecken som används för att skapa frågevariabler (t.ex. semikolon (;), likhetstecken (=), snedstreck /) måste 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:

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 AEM headless Client 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

Beständiga frågor bör alltid skapas i en AEM Author-tjä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å och i slutänden göra dem tillgängliga i en AEM Publish-produktionsmiljö så att klientapplikationerna kan använda dem.

Paketera beständiga frågor

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

Så här skapar du ett paket:

1. Navigera till verktyg > Distribution > Paket.
2. Skapa ett nytt paket genom att trycka Skapa paket. Då öppnas en dialogruta där du kan definiera paketet.
3. I dialogrutan Paketdefinition, under Allmänt ange Namn som "wknd-persistent-queries".
4. Ange ett versionsnummer som "1.0".
5. Under Filter lägg till en ny Filter. Använd Sökväg för att välja persistentQueries under konfigurationen. Till exempel wknd konfiguration den fullständiga sökvägen kommer att /conf/wknd/settings/graphql/persistentQueries.
6. Tryck Spara för att spara den nya paketdefinitionen och stänga dialogrutan.
7. Tryck på Bygge i den nyligen skapade paketdefinitionen.

När paketet har byggts kan du:

• Hämta paketet och ladda upp det igen i en annan miljö.
• Replikera paketet genom att trycka Mer > Replikera. Paketet kommer att replikeras till den anslutna AEM-publiceringsmiljön.

Resurser för Business.Adobe.com