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

Beständiga frågor är GraphQL-frågor som skapas och lagras på Adobe Experience Manager (AEM) as a Cloud Service server. De kan begäras med en GET-begäran från klientprogram. Svaret på en GET-begäran kan cachas i skikten dispatcher och 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:

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

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:

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.

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

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

Använda frågevariabler - Bästa praxis query-variables-best-practices

När du använder variabler i dina frågor finns det några metodtips som du bör följa:

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:

Författarinstanser author-instances

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

De var:

Publish-instanser publish-instances

Standardvärdena för publiceringsinstanser är:

Dessa kan skrivas över:

Hantera rubriker för HTTP-cache i GraphiQL IDE http-cache-headers-graphiql-ide

GraphiQL IDE - se Spara beständiga frågor

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 Cloud Manager-variabler cache-cloud-manager-variables

Cloud Manager miljövariabler kan definieras med Cloud Manager för att definiera de värden som krävs:

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.

Standardkonfigurationen för OSGi för publiceringsinstanser:

Konfigurera frågesvarskoden configuring-query-response-code

Som standard skickar PersistedQueryServlet ett 200-svar när en fråga körs, oavsett det faktiska resultatet.

Du kan konfigurera OSGi-inställningarna för konfigurationen för den beständiga frågetjänsten för att kontrollera om mer detaljerade statuskoder returneras av /execute.json/persisted-query-slutpunkten, om det finns ett fel i den beständiga frågan.

Fältet Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) kan definieras enligt behov:

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 (d.v.s. semikolon (;), likhetstecken (=), snedstreck /) konverteras till motsvarande UTF-8-kodning.

Till exempel:

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"

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

När paketet har byggts kan du: