Le query persistenti sono query GraphQL create e memorizzate sul server di Adobe Experience Manager (AEM) as a Cloud Service. Possono essere richiamate tramite una richiesta GET da parte delle applicazioni client. La risposta di una richiesta GET può essere memorizzata nella cache ai livelli dispatcher e CDN, migliorando in definitiva le prestazioni dell’applicazione client richiedente. In questo sono diverse dalle query GraphQL standard, che vengono eseguite utilizzando richieste POST in cui la risposta non può essere facilmente memorizzata nella cache.
Si consiglia di effettuare query persistenti. Consulta Tecniche consigliate per le query GraphQL (Dispatcher) per informazioni dettagliate e la relativa configurazione di Dispatcher.
La IDE GraphiQL è disponibile in AEM per sviluppare, testare e mantenere le query GraphQL, prima del trasferimento all’ambiente di produzione. Per i casi che richiedono personalizzazione (come la personalizzazione della cache) puoi utilizzare l’API; vedi l’esempio curl fornito in Persistenza di una query GraphQL.
Le query persistenti devono sempre utilizzare l’endpoint correlato alla configurazione Sites adeguata in modo che possano utilizzare una delle due opzioni seguenti, oppure entrambe:
Per ulteriori dettagli, vedi Abilitare la funzionalità Frammenti di contenuto nel browser configurazioni.
Per la configurazione di Sites appropriata, è necessario abilitare query GraphQL persistenti.
Ad esempio, se vi è una particolare query denominata my-query
, che utilizza un modello my-model
della configurazione Sites my-conf
:
my-conf
specifico. La query viene salvata come segue:/conf/my-conf/settings/graphql/persistentQueries/my-query
global
, ma in questo caso la query viene salvata come segue:/conf/global/settings/graphql/persistentQueries/my-query
Si tratta di due query diverse, salvate in percorsi diversi.
Utilizzano lo stesso modello, ma tramite endpoint diversi.
Si consiglia di creare le query persistenti in un ambiente di authoring AEM per poi trasferire la query nell’ambiente di pubblicazione AEM di produzione, per l’utilizzo da parte delle applicazioni.
Esistono diversi metodi per le query persistenti, tra cui:
L’IDE GraphiQL è il metodo preferito per le query persistenti. Per rendere persistente una determinata query utilizzando lo strumento per riga di comando cURL:
Prepara la query inserendola mediante il metodo PUT nel nuovo URL dell’endpoint /graphql/persist.json/<config>/<persisted-label>
.
Ad esempio, crea una query persistente:
$ 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
}
}
}
}'
A questo punto, verifica la risposta.
Ad esempio, verifica se l’operazione è riuscita:
{
"action": "create",
"configurationName": "wknd",
"name": "plain-article-query",
"shortPath": "/wknd/plain-article-query",
"path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
}
Puoi quindi richiedere la query persistente utilizzando il metodo GET per l’URL /graphql/execute.json/<shortPath>
.
Ad esempio, utilizza la query persistente:
$ curl -X GET \
http://localhost:4502/graphql/execute.json/wknd/plain-article-query
Per aggiorna una query persistente, utilizza il metodo POST per un percorso di query già esistente.
Ad esempio, utilizza la query persistente:
$ 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
}
}
}
}'
Crea una query normale racchiusa.
Esempio:
$ 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 } } } }"}'
Crea una query normale racchiusa con il controllo della cache.
Esempio:
$ 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 }}'
Crea una query persistente con parametri:
Esempio:
$ 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
}
}
}
}'
Per eseguire una query persistente, un’applicazione client invia una richiesta GET utilizzando la seguente sintassi:
GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>
dove PERSISTENT_PATH
è un percorso abbreviato in cui viene salvata la query persistente.
Ad esempio wknd
è il nome della configurazione e plain-article-query
è il nome della query persistente. Per eseguire la query:
$ curl -X GET \
https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
Esegui una query con parametri.
Le variabili e i valori della query devono essere correttamente codificati durante l’esecuzione di una query persistente.
Esempio:
$ 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
Per ulteriori dettagli, consulta la sezione sulle variabili di query.
Le variabili di query possono essere utilizzate con le query persistenti. Le variabili di query aggiunte alla richiesta devono essere precedute da un punto e virgola (;
) e devono utilizzare il nome e il valore della variabile. Se si utilizzano più variabili, queste devono essere separate da un punto e virgola.
Il pattern si presenta come segue:
<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2
Ad esempio, la seguente query contiene una variabile activity
per filtrare un elenco in base a un valore di attività:
query getAdventuresByActivity($activity: String!) {
adventureList (filter: {
adventureActivity: {
_expressions: [
{
value: $activity
}
]
}
}){
items {
_path
adventureTitle
adventurePrice
adventureTripLength
}
}
}
Questa query può essere resa persistente in un percorso wknd/adventures-by-activity
. Per chiamare la query persistente dove activity=Camping
, la richiesta sarà simile alla seguente:
<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping
Tieni presente che %3B
è la codifica UTF-8 per ;
e %3D
è la codifica per =
. Affinché la query persistente possa essere eseguita, le variabili della query ed eventuali caratteri speciali devono essere codificati correttamente.
Le query persistenti sono consigliate in quanto possono essere memorizzate nella cache a livello di dispatcher e CDN, il che migliora le prestazioni dell’applicazione client richiedente.
Per impostazione predefinita, AEM renderà non valida la cache CDN (Content Delivery Network) in base a un valore Time To Live (TTL) predefinito.
Questo valore è impostato su:
Se desideri modificare il valore TTL per la query GraphLQ, quest’ultima deve essere impostata come:
GraphiQL IDE: vedi Salvataggio delle query persistenti
Ciò comporta la pubblicazione della query per AEM utilizzando CURL nell’interfaccia per riga di comando.
Esempio:
curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"https://publish-p123-e456.adobeaemcloud.com/graphql/persist.json/wknd/plain-article-query-max-age" \
-d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'
cache-control
può essere impostato al momento della creazione (PUT) o successivamente (ad esempio, tramite una richiesta POST). Il controllo cache è facoltativo quando si crea la query persistente, in quanto AEM può fornire il valore predefinito. Vedi Come rendere persistente una query GraphQL, per un esempio di persistenza di query utilizzando CURL.
Per poter essere utilizzati da un’applicazione, eventuali caratteri speciali utilizzati per creare variabili di query (come punto e virgola (;
), segno di uguale (=
), barra /
) deve essere convertito nella codifica UTF-8 corrispondente.
Esempio:
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"
L’URL può essere suddiviso nelle seguenti parti:
Parte URL | Descrizione |
---|---|
/graphql/execute.json |
Endpoint di query persistente |
/wknd/adventure-by-path |
Percorso query persistente |
%3B |
Codice per ; |
adventurePath |
Variabile query |
%3D |
Codice per = |
%2F |
Codice per / |
%2Fcontent%2Fdam... |
Percorso codificato del frammento di contenuto |
Come testo normale, l’URI della richiesta si presenta così:
/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp
Per utilizzare una query persistente in un’app client, è necessario utilizzare l’SDK client AEM headless per JavaScript, Java oppure NodeJS. L’SDK client headless codificherà automaticamente tutte le variabili di query in modo appropriato nella richiesta.
Le query persistenti devono sempre essere create su un servizio AEM Author e quindi pubblicate (replicate) in un servizio AEM Publish. Spesso, le query persistenti vengono create e testate in ambienti inferiori, come ambienti locali o di sviluppo. È quindi necessario promuovere le query persistenti in ambienti di livello superiore, rendendole infine disponibili in un ambiente AEM Publish di produzione affinché possano essere utilizzate da parte delle applicazioni client.
È possibile integrare le query persistenti in pacchetti AEM. I pacchetti AEM possono quindi essere scaricati e installati in ambienti diversi. I pacchetti AEM possono essere replicati anche da un ambiente AEM Author ad ambienti AEM Publish.
Per creare un pacchetto:
persistentQueries
sotto la configurazione. Ad esempio, per la configurazione wknd
il percorso completo sarà /conf/wknd/settings/graphql/persistentQueries
.Dopo aver generato il pacchetto puoi: