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.

NOTA

Si consiglia di effettuare query persistenti. Vedi 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 di 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.
NOTA

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:

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

Si tratta di due query diverse, salvate in percorsi diversi.

Utilizzano lo stesso modello, ma tramite endpoint diversi.

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:

L'IDE GraphiQL è il preferito metodo per query persistenti. Per persistere una determinata query utilizzando arricciare strumento della riga di comando:

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

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

    Consulta la sezione variabili di query per ulteriori dettagli.

Utilizzo delle variabili di query

Le variabili di query possono essere utilizzate con le query persistenti. Le variabili della query vengono aggiunte alla richiesta con un punto e virgola (;) utilizzando il nome e il valore della variabile. Le variabili multiple sono separate da 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 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 =. Le variabili della query e gli eventuali caratteri speciali devono essere codificato correttamente per eseguire la query persistente.

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

Per l'uso da parte di un'applicazione, qualsiasi carattere speciale utilizzato per la costruzione di variabili di query (ovvero punto e virgola (;), segno di uguale (=), barre /) deve essere convertito per utilizzare la 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 Codifica di ;
adventurePath Variabile query
%3D Codifica di =
%2F Codifica di /
%2Fcontent%2Fdam... Percorso codificato del frammento di contenuto

In testo normale, l’URI della richiesta ha il seguente aspetto:

/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 headless AEM per JavaScript, Javaoppure NodeJS. L’SDK del 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 gli ambienti locali o di sviluppo. È quindi necessario promuovere le query persistenti in ambienti di livello superiore, rendendole infine disponibili in un ambiente di produzione AEM Publish per l’utilizzo da parte delle applicazioni client.

Query persistenti del pacchetto

È possibile integrare query persistenti in Pacchetti AEM. AEM I pacchetti possono quindi essere scaricati e installati in ambienti diversi. AEM pacchetti possono essere replicati anche da un ambiente AEM Author agli ambienti AEM Publish.

Per creare un pacchetto:

  1. Passa a Strumenti > Distribuzione > Pacchetti.
  2. Crea un nuovo pacchetto toccando Crea pacchetto. Viene visualizzata una finestra di dialogo per la definizione del pacchetto.
  3. Nella finestra di dialogo Definizione pacchetto, in Generale inserire un Nome come "query wknd-persistenti".
  4. Immettere un numero di versione simile a "1.0".
  5. Sotto Filtri aggiungi una nuova Filtro. Utilizza il Finder del percorso per selezionare il persistentQueries sotto la configurazione. Ad esempio, per wknd configurazione del percorso completo /conf/wknd/settings/graphql/persistentQueries.
  6. Tocca Salva per salvare la nuova definizione del pacchetto e chiudere la finestra di dialogo.
  7. Tocca Crea nella definizione del pacchetto appena creata.

Dopo aver generato il pacchetto puoi:

  • Scarica il pacchetto e ricaricalo in un ambiente diverso.
  • Replicare il pacchetto toccando Altro > Replicare. Questo replicherà il pacchetto all’ambiente di pubblicazione AEM connesso.

In questa pagina