Beständiga frågor är GraphQL-frågor som skapas och lagras på den as a Cloud Service Adobe Experience Manager-servern (AEM). 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.
Beständiga frågor rekommenderas. Se GraphQL Query Best Practices (Dispatcher) för mer information och den relaterade Dispatcher-konfigurationen.
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 på cURL i Så här behåller du en GraphQL-fråga.
Beständiga frågor måste alltid använda den slutpunkt som är relaterad till lämplig platskonfigurationså att de kan använda antingen eller båda:
Se Aktivera funktionen för innehållsfragment i konfigurationsläsaren för mer information.
The GraphQL Beständiga frågor måste aktiveras för rätt platskonfiguration.
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
:
my-conf
en specifik slutpunkt, och därefter sparas frågan så här:/conf/my-conf/settings/graphql/persistentQueries/my-query
global
slutpunkt, men frågan sparas sedan som följer:/conf/global/settings/graphql/persistentQueries/my-query
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.
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 är standard metod för beständiga frågor. Bevara en given fråga med cURL kommandoradsverktyg:
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
}
}
}
}'
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"
}
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
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
}
}
}
}'
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 } } } }"}'
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 }}'
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
}
}
}
}'
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>
Plats PERSISTENT_PATH
är en förkortad sökväg där den beständiga frågan sparas.
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://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
Kör en fråga med parametrar.
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://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
Se använda frågevariabler för mer information.
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 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
}
}
}
Frågan kan sparas under en sökväg wknd/adventures-by-activity
. Anropa 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
UTF-8-kodning %3B
är 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.
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:
Cache-typ | HTTP-huvud | cURL | OSGi-konfiguration | Cloud Manager |
---|---|---|---|---|
Webbläsare | 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 |
För författarinstanser är standardvärdena:
max-age
: 60s-maxage
: 60stale-while-revalidate
: 86400stale-if-error
: 86400De var:
cache-control
och/eller surrogate-control
; för exempel, se Hantera cache på nivån för beständig frågaStandardvärdena för publiceringsinstanser är:
max-age
: 60s-maxage
: 7200stale-while-revalidate
: 86400stale-if-error
: 86400Dessa 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.
GraphiQL IDE - se Sparar beständiga frågor
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.
Miljövariabler för Cloud Manager kan definieras med Cloud Manager för att definiera de värden som krävs:
Namn | Värde | Tjänsten används | Typ |
---|---|---|---|
graphqlStaleIfError |
86400 | efter behov | efter behov |
graphqlSurrogateControl |
600 | efter behov | efter behov |
Om du vill hantera cachen globalt kan du konfigurera OSGi-inställningarna för Konfiguration av beständig frågetjänst.
För cachekontroll är OSGi-konfigurationen endast lämplig för publiceringsinstanser. Konfigurationen finns på författarinstanser, men ignoreras.
The Konfiguration av beständig frågetjänst används också för konfigurera frågesvarskoden.
Standardkonfigurationen för OSGi för publiceringsinstanser:
läser Cloud Manager-variabler om de är tillgängliga:
OSGi-konfigurationsegenskap | läser detta | Cloud Manager-variabel |
---|---|---|
cacheControlMaxAge |
läsningar | graphqlCacheControl |
surrogateControlMaxAge |
läsningar | graphqlSurrogateControl |
surrogateControlStaleWhileRevalidate |
läsningar | graphqlStaleWhileRevalidate |
surrogateControlStaleIfError |
läsningar | graphqlStaleIfError |
Om den inte är tillgänglig använder OSGi-konfigurationen standardvärden för publiceringsinstanser.
Som standard är PersistedQueryServlet
skickar en 200
svar när den kör en fråga, oavsett det faktiska resultatet.
Du kan konfigurera OSGi-inställningarna för Konfiguration av beständig frågetjänst för att kontrollera vilken statuskod som returneras av /execute.json/persisted-query
slutpunkten, om det finns ett fel i den beständiga frågan.
The Konfiguration av beständig frågetjänst används också för hantera cache.
Fältet Respond with application/graphql-response+json
(responseContentTypeGraphQLResponseJson
) kan definieras enligt behov:
false
(standardvärde): Det spelar ingen roll om den beständiga frågan lyckas eller inte. The /execute.json/persisted-query
returnerar statuskoden 200
och Content-Type
header returned is application/json
.
true
: Slutpunkten returneras 400
eller 500
om det finns någon form av fel när den beständiga frågan körs. Dessutom returneras Content-Type
är application/graphql-response+json
.
Se https://graphql.github.io/graphql-over-http/draft/#sec-Status-Codes
Om det används av ett program används alla specialtecken som används för att konstruera frågevariabler (d.v.s. semikolon (;
), likhetstecken (=
), snedstreck /
) måste 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:
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 ; |
adventurePath |
Frågevariabel |
%3D |
Kodning = |
%2F |
Kodning / |
%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 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.
Beständiga frågor ska alltid skapas på en AEM författartjänst och sedan publiceras (replikeras) till en AEM publiceringstjä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 publiceringsmiljö för att klientprogram ska kunna använda dem.
Beständiga frågor kan byggas in i AEM. AEM paket kan sedan laddas ned och installeras i olika miljöer. AEM paket kan också replikeras från en AEM redigeringsmiljö till AEM publiceringsmiljöer.
Skapa ett paket:
persistentQueries
under konfigurationen. För wknd
konfiguration, den fullständiga sökvägen /conf/wknd/settings/graphql/persistentQueries
.När paketet har byggts kan du: