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 Persistenza di 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, 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:

• 7200 secondi, TTL predefinito per Dispatcher e CDN; noto anche come cache condivise
  • impostazione predefinita: s-maxage=7200
• 60, TTL predefinito per il client (ad esempio, un browser)
  • impostazione predefinita: maxage=60

Se desideri modificare il valore TTL per la query GraphLQ, quest’ultima deve essere impostata come:

• persistente dopo la gestione delle intestazioni cache HTTP, dall’IDE GraphQL;
• persistente utilizzando il metodo API.

Gestione delle intestazioni cache HTTP in GraphQL

GraphiQL IDE: vedi Salvataggio delle query persistenti

Gestione della cache dall’API

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.

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

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