Query GraphQL persistenti

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.

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 Come rendere persistente una query GraphQL.

Query ed endpoint persistenti

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:

• Configurazione globale ed endpoint
  La query ha accesso a tutti i modelli per frammenti di contenuto.
• Configurazione/i di Sites ed endpoint specifici
  La creazione di una query persistente per una configurazione di Sites specifica richiede un endpoint specifico per la configurazione di Sites corrispondente (in modo da fornire accesso ai relativi modelli per frammenti di contenuto).
  Ad esempio, per creare una query persistente per la configurazione di Sites WKND, è necessario aver già creato una configurazione di Sites specifica per WKND corrispondente e un endpoint specifico per WKND.

Ad esempio, se vi è una particolare query denominata my-query, che utilizza un modello my-model della configurazione Sites my-conf:

• Puoi creare una query utilizzando l’endpoint my-conf specifico. La query viene salvata come segue:
  /conf/my-conf/settings/graphql/persistentQueries/my-query
• Puoi creare la stessa query utilizzando l’endpoint global, ma in questo caso la query viene salvata come segue:
  /conf/global/settings/graphql/persistentQueries/my-query

Rendere persistente una query GraphQL

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:

• IDE GraphiQL: vedi Salvataggio delle query persistenti (metodo preferito)
• cURL: vedi l’esempio seguente
• Altri strumenti, tra cui Postman

L’IDE GraphiQL è il metodo preferito per le query persistenti. Per rendere persistente una determinata query utilizzando lo strumento per riga di comando cURL:

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

2. 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"
   }
   

3. 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
   

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

5. 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 } } } }"}'
   

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

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

Come eseguire una query persistente

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.

1. 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
   

2. Esegui una query con parametri.

   NOTA

   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.

Utilizzo delle 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.

Memorizzazione in cache delle query persistenti

Le query persistenti sono consigliate in quanto possono essere memorizzate nella cache a livello di Dispatcher e CDN, migliorando in ultima analisi le prestazioni dell’applicazione client richiedente.

Per impostazione predefinita, AEM annullerà la cache basata sulla definizione TTL (Time To Live). Le definizioni TTL possono essere definite dai seguenti parametri. Questi parametri sono accessibili con vari mezzi, con variazioni dei nomi in base al meccanismo utilizzato:

Istanze di authoring

Per le istanze di authoring, i valori predefiniti sono:

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

Questi:

• non può essere sovrascritto:
  • con una configurazione OSGi
• può essere sovrascritto:
  • da una richiesta che definisce le impostazioni dell’intestazione HTTP utilizzando cURL; deve includere impostazioni adeguate per cache-control e/o surrogate-control; per esempi, consulta Gestione della cache a livello di query persistente
  • se specifichi i valori nella finestra di dialogo Intestazioni di IDE GraphiQL

Istanze di pubblicazione

Per le istanze di pubblicazione i valori predefiniti sono:

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

Questi possono essere sovrascritti:

• da IDE GraphQL

• a livello di query persistente; ciò comporta la pubblicazione della query per AEM utilizzando cURL nell’interfaccia della riga di comando e la pubblicazione della query persistente.

• con variabili di Cloud Manager

• con una configurazione OSGi

Gestione delle intestazioni della cache HTTP nell’IDE GraphiQL

GraphiQL IDE: consulta Salvataggio delle query persistenti

Gestione della cache a livello di query persistente

Ciò comporta la pubblicazione della query per AEM utilizzando cURL nell’interfaccia per riga di comando.

Per un esempio del metodo PUT (creato):

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

Per un esempio del metodo POST (aggiornato):

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 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. Consulta Come rendere persistente una query GraphQL, per un esempio di persistenza di query utilizzando cURL.

Gestione della cache con le variabili di Cloud Manager

Le variabili dell’ambiente Cloud Manager possono essere definite con Cloud Manager per determinare i valori richiesti:

Gestione della cache con una configurazione OSGi

Per gestire la cache a livello globale, puoi configurare le impostazioni OSGi per la Configurazione del servizio query persistenti.

La configurazione OSGi predefinita per le istanze di pubblicazione:

• legge le variabili di Cloud Manager se disponibili:

  Proprietà della configurazione OSGi	legge questo	Variabile di Cloud Manager
  cacheControlMaxAge	legge	graphqlCacheControl
  surrogateControlMaxAge	legge	graphqlSurrogateControl
  surrogateControlStaleWhileRevalidate	legge	graphqlStaleWhileRevalidate
  surrogateControlStaleIfError	legge	graphqlStaleIfError

• e, se non disponibile, la configurazione OSGi utilizza i valori predefiniti per le istanze di pubblicazione.

Configurazione del codice di risposta della query

Per impostazione predefinita, il PersistedQueryServlet invia una risposta 200 quando esegue una query, indipendentemente dal risultato effettivo.

È possibile configurare le impostazioni OSGi per la Configurazione servizio query persistenti per controllare quale codice di stato viene restituito dall’endpoint /execute.json/persisted-query, quando si verifica un errore nella query persistente.

Il campo Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) può essere definito come richiesto:

• false (valore predefinito):
  non importa se la query persistente ha esito positivo o negativo. /execute.json/persisted-query restituisce il codice di stato 200 e l’intestazione Content-Type restituita è application/json.

• true:
  secondi i casi, l’endpoint restituirà 400 o 500 quando si verifica qualsiasi tipo di errore durante l’esecuzione della query persistente. Inoltre, il Content-Type restituito è application/graphql-response+json.

  NOTA

  Per maggiori dettagli, visita il sito https://graphql.github.io/graphql-over-http/draft/#sec-Status-Codes

Codifica dell’URL della query per l’utilizzo da parte di un’app

Per poter essere utilizzati da un’applicazione, eventuali caratteri speciali utilizzati per creare variabili di query (come punto e virgola (;), segno di uguale (=), barra /) devono essere convertiti 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:

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.

Trasferimento di una query persistente all’ambiente di produzione

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.

Query persistenti nei pacchetti

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

1. Passa a Strumenti > Implementazione > Pacchetti.
2. Per creare un nuovo pacchetto, tocca Crea pacchetto. Viene visualizzata una finestra di dialogo per la definizione del pacchetto.
3. Nella finestra di dialogo Definizione pacchetto, nella sezione Generale inserisci un Nome, ad esempio “wknd-persistent-queries”.
4. Immetti un numero di versione, ad esempio a “1.0”.
5. Nella sezione Filtri, aggiungi un nuovo Filtro. Utilizza Trova percorso per selezionare la cartella persistentQueries sotto la configurazione. Ad esempio, per la configurazione wknd il percorso completo sarà /conf/wknd/settings/graphql/persistentQueries.
6. Tocca Salva per salvare la definizione del nuovo pacchetto e chiudere la finestra di dialogo.
7. Tocca il Genera nella definizione del pacchetto appena creata.

Dopo aver generato il pacchetto puoi:

• Scaricare il pacchetto e ricaricalo in un altro ambiente.
• Replicare il pacchetto toccando Altro > Replica. Il pacchetto verrà replicato nell’ambiente AEM Publish collegato.

Risorse Business.Adobe.com