Query GraphQL persistenti persisted-graphql-queries

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 persisted-queries-and-endpoints

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:

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

Rendere persistente una query GraphQL how-to-persist-query

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:

Come eseguire una query persistente execute-persisted-query

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.

Utilizzo delle variabili di query query-variables

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

La codifica UTF-8 %3B è 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.

Utilizzo delle variabili di query: best practice query-variables-best-practices

Quando si utilizzano le variabili nelle query, è necessario seguire alcune best practice:

Memorizzazione in cache delle query persistenti caching-persisted-queries

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

Per le istanze di authoring, i valori predefiniti sono:

Questi:

Istanze di pubblicazione publish-instances

Per le istanze di pubblicazione i valori predefiniti sono:

Questi possono essere sovrascritti:

Gestione delle intestazioni della cache HTTP nell’IDE GraphiQL http-cache-headers-graphiql-ide

GraphiQL IDE: consulta Salvataggio delle query persistenti

Gestione della cache a livello di query persistente cache-persisted-query-level

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

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

Gestione della cache con una configurazione OSGi cache-osgi-configration

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:

Configurazione del codice di risposta della query configuring-query-response-code

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 del servizio query persistenti per controllare se l'endpoint /execute.json/persisted-query restituisce codici di stato più dettagliati in caso di errore nella query persistente.

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

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

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 transfer-persisted-query-production

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:

Dopo aver generato il pacchetto puoi: