API GraphQL AEM per l’utilizzo con Frammenti di contenuto

Scopri come utilizzare Frammenti di contenuto in Adobe Experience Manager (AEM) con l’API GraphQL AEM per la distribuzione di contenuti headless.

L’API GraphQL AEM utilizzata con i Frammenti di contenuto è pesantemente basata sull’API GraphQL standard open source.

L’utilizzo dell’API GraphQL in AEM consente la consegna efficiente di Frammenti di contenuto ai client JavaScript in implementazioni CMS headless:

  • evita richieste API iterative come con REST,
  • garantisce che la consegna sia limitata ai requisiti specifici,
  • consente la consegna in massa di ciò che è esattamente necessario per il rendering come risposta a una singola query API.
NOTA

GraphQL è attualmente utilizzato in due scenari (separati) in Adobe Experience Manager (AEM):

API GraphQL

GraphQL è:

  • …un linguaggio di query per le API e un runtime per l’esecuzione di tali query con i dati esistenti. GraphQL fornisce una descrizione completa e comprensibile dei dati nell’API, offre ai clienti la possibilità di chiedere esattamente ciò di cui hanno bisogno e niente di più, semplifica l’evoluzione delle API nel tempo e abilita potenti strumenti per gli sviluppatori.”.

    Vedi GraphQL.org

  • …una specifica aperta per un livello API flessibile. Posiziona GraphQL sui backend esistenti per costruire prodotti più rapidamente che mai…”.

    Vedi Esplorare GraphQL.

  • “…un linguaggio e una specifica di query di dati sviluppati internamente da Facebook nel 2012 prima di essere resi open source nel 2015. Offre un’alternativa alle architetture basate su REST allo scopo di aumentare la produttività degli sviluppatori e ridurre al minimo le quantità di dati trasferiti. GraphQL viene utilizzato in produzione da centinaia di organizzazioni di tutte le dimensioni…”

    Vedi GraphQL Foundation.

Per ulteriori informazioni sull’API GraphQL, consulta le sezioni seguenti (tra molte altre risorse):

L’implementazione di GraphQL per AEM si basa sulla libreria Java GraphQL standard. Consulta:

Terminologia GraphQL

GraphQL utilizza quanto segue:

  • Query

  • Schemi e tipi:

    • Gli schemi vengono generati da AEM in base ai modelli di Frammenti di contenuto.
    • Utilizzando i tuoi schemi, GraphQL presenta i tipi e le operazioni consentiti per l’implementazione GraphQL per AEM.
  • Campi

  • Endpoint GraphQL

Consulta(GraphQL.org) Introduzione a GraphQL per informazioni complete, che comprendono le Best practice.

Tipi di query GraphQL

Con GraphQL è possibile eseguire query per ottenere:

Puoi anche eseguire le seguenti operazioni:

NOTA

Puoi testare ed eseguire il debug delle query GraphQL utilizzando IDE GraphiQL.

GraphQL per AEM endpoint

L’endpoint è il percorso utilizzato per accedere a GraphQL per AEM. Utilizzando questo percorso (o la tua app) puoi:

  • accedere allo schema GraphQL;
  • inviare le query GraphQL;
  • ricevere le risposte (alle query GraphQL).

Esistono due tipi di endpoint in AEM:

  • Globale
    • Disponibile per tutti i siti.
    • Questo endpoint può utilizzare tutti i modelli per frammenti di contenuto di tutte le configurazioni di Sites (definite nella sezione Browser configurazioni).
    • Se esistono modelli per frammenti di contenuto che devono essere condivisi tra le configurazioni di Sites, questi devono essere creati nelle configurazioni globali di Sites.
  • Configurazioni di Sites:
    • Corrisponde a una configurazione Sites, come definita nella sezione Browser configurazioni.
    • Sono specifiche per un determinato sito o progetto.
    • Un endpoint specifico per la configurazione di Sites utilizzerà i modelli di frammento di contenuto di quella specifica configurazione di Sites insieme a quelli della configurazione globale di Sites.
ATTENZIONE

L’Editor frammento di contenuto può consentire a un frammento di contenuto di una configurazione Sites di fare riferimento a un frammento di contenuto di un’altra configurazione Sites (tramite criteri).

In questo caso non tutti i contenuti saranno recuperabili utilizzando un endpoint specifico per la configurazione Sites.

L’autore del contenuto deve controllare questo scenario; ad esempio, potrebbe essere utile inserire modelli per frammenti di contenuto condivisi nella configurazione globale di Sites.

Il percorso dell’archivio di GraphQL per l’endpoint globale di AEM è:

/content/cq:graphql/global/endpoint

Per cui l’app può utilizzare il seguente percorso nell’URL della richiesta:

/content/_cq_graphql/global/endpoint.json

Per abilitare un endpoint per GraphQL per AEM è necessario:

Abilitazione dell’endpoint GraphQL

Per abilitare un endpoint GraphQL è innanzitutto necessario disporre di una configurazione appropriata. Vedi la sezione Frammenti di contenuto - Browser configurazioni.

ATTENZIONE

Se l’utilizzo di modelli per frammenti di contenuto non è stato abilitato, l’opzione Crea non sarà disponibile.

Per abilitare l’endpoint corrispondente:

  1. Passa a Strumenti, Risorse, quindi seleziona GraphQL.

  2. Seleziona Crea.

  3. Si aprirà la finestra di dialogo Crea nuovo endpoint GraphQL. Qui potrai definire:

    • Nome: nome dell’endpoint; puoi immettere qualsiasi testo.
    • Utilizza lo schema GraphQL fornito da: dal menu a discesa, seleziona il sito o il progetto richiesto.
    NOTA

    Nella finestra di dialogo viene visualizzato la seguente avvertenza:

    • Se non vengono gestiti correttamente, gli endpoint GraphQL possono causare problemi di prestazioni e sicurezza dei dati. Dopo aver creato un endpoint, assicurati di impostare le autorizzazioni appropriate.
  4. Per confermare, fai clic su Crea.

  5. La finestra di dialogo Passaggi successivi fornisce un collegamento diretto alla console Sicurezza per verificare che l’endpoint appena creato disponga delle autorizzazioni appropriate.

    ATTENZIONE

    L’endpoint è accessibile a tutti. Questo può creare problemi di sicurezza, soprattutto per le istanze di pubblicazione, in quanto le query GraphQL possono imporre un carico pesante sul server.

    Puoi impostare sull’endpoint eventuali ACL appropriate al tuo caso d’uso.

Pubblicazione dell’endpoint GraphQL

Seleziona il nuovo endpoint e scegli Pubblica per renderlo completamente disponibile in tutti gli ambienti.

ATTENZIONE

L’endpoint è accessibile a tutti.

Nelle istanze di pubblicazione questo può rappresentare un problema di sicurezza, in quanto le query GraphQL possono imporre un carico pesante sul server.

Devi configurare sull’endpoint le ACL appropriate al tuo caso d’uso.

Interfaccia GraphiQL

Attuazione dello standard GraphiQL È disponibile per l’utilizzo con AEM GraphQL. Può essere installato con AEM.

NOTA

GraphiQL è associato all’endpoint globale (e non funziona con altri endpoint per configurazioni specifiche di Sites).

Questa interfaccia ti consente di inserire e testare direttamente le query.

Ad esempio:

  • http://localhost:4502/content/graphiql.html

Offre funzioni quali evidenziazione della sintassi, completamento automatico, suggerimenti automatici, nonché una cronologia e una documentazione online:

Interfaccia di GraphiQL

Installazione dell'interfaccia AEM GraphiQL

L'interfaccia utente GraphiQL può essere installata su AEM con un pacchetto dedicato: la Pacchetto di contenuti GraphiQL v0.0.6 (2021.3) pacchetto.

NOTA

Il pacchetto disponibile è completamente compatibile con AEM 6.5.10.0 e AEM as a Cloud Service.

Casi di utilizzo per ambienti di authoring e pubblicazione

I casi di utilizzo possono dipendere dal tipo di ambiente AEM:

  • ambiente di pubblicazione; utilizzato per:

    • effettuare query sui dati per l’applicazione JS (caso di utilizzo standard)
  • ambiente di authoring; utilizzato per:

    • effettuare query sui dati a “scopo di gestione dei contenuti”:
      • GraphQL in AEM è attualmente un'API di sola lettura.
      • L’API REST può essere utilizzata per le operazioni CR(u)D.

Autorizzazioni

Le autorizzazioni sono quelle necessarie per accedere ad Assets.

Generazione schema

GraphQL è un’API fortemente tipizzata, il che significa che i dati devono essere chiaramente strutturati e organizzati per tipo.

La specifica GraphQL fornisce una serie di linee guida su come creare una solida API per l’interrogazione dei dati su una determinata istanza. A questo scopo, un client deve recuperare lo Schema, che contiene tutti i tipi necessari per una query.

Per quanto riguarda i Frammenti di contenuto, gli schemi GraphQL (struttura e tipi) sono basati su modelli di Frammenti di contenuto abilitati e i relativi tipi di dati.

ATTENZIONE

Tutti gli schemi GraphQL (derivati dai modelli di Frammenti di contenuto che sono stati abilitati) sono leggibili attraverso l’endpoint GraphQL.

Ciò significa che devi assicurarti che non siano disponibili dati sensibili, che in questo modo potrebbero trapelare; ad esempio, informazioni che potrebbero essere presenti come nomi di campo nella definizione del modello.

Ad esempio, se un utente ha creato un modello di Frammento di contenuto denominato Article, AEM genera l’oggetto article di un tipo ArticleModel. I campi all’interno di questo tipo corrispondono ai campi e ai tipi di dati definiti nel modello.

  1. Modello di Frammento di contenuto:

    Modello di Frammento di contenuto da utilizzare con GraphQL

  2. Lo schema GraphQL corrispondente (output dalla documentazione automatica GraphiQL):
    Schema GraphQL basato su modello di Frammento di contenuto

    Questo mostra che il tipo ArticleModel generato contiene diversi campi.

    • Tre di essi sono stati controllati dall’utente: author, main e referencearticle.

    • Gli altri campi sono stati aggiunti automaticamente da AEM e rappresentano metodi utili per fornire informazioni su un determinato Frammento di contenuto; in questo esempio, _path, _metadata, _variations. Tali campi di supporto sono contrassegnati con un _ per distinguere tra ciò che è stato definito dall’utente e ciò che è stato generato automaticamente.

  3. Un Frammento di contenuto basato sul modello di articolo creato da un utente può essere interrogato tramite GraphQL. Per esempi, consulta la sezione Query di esempio (basata su una struttura di Frammento di contenuto di esempio da utilizzare con GraphQL).

In GraphQL per AEM, lo schema è flessibile. Ciò significa che viene generato automaticamente ogni volta che viene creato, aggiornato o eliminato un modello di Frammento di contenuto. Le cache dello schema dati vengono aggiornate anche quando si rivede un modello di Frammento di contenuto.

Il servizio GraphQL di Sites ascolta (in background) le modifiche apportate a un modello di Frammento di contenuto. Quando vengono rilevati aggiornamenti, viene rigenerata solo la parte dello schema. Questa ottimizzazione consente di risparmiare tempo e garantisce stabilità.

Ad esempio, se:

  1. installi un pacchetto contenente Content-Fragment-Model-1 e Content-Fragment-Model-2:

    1. vengono generati dei tipi GraphQL per Model-1 e Model-2.
  2. Poi modifica Content-Fragment-Model-2:

    1. verrà aggiornato solo il tipo GraphQL Model-2.

    2. Mentre Model-1 rimarrà lo stesso.

NOTA

Questo è importante da notare nel caso in cui desideri eseguire aggiornamenti in blocco sui modelli di Frammento di contenuto tramite l’API REST o in altro modo.

Lo schema viene gestito attraverso lo stesso endpoint delle query GraphQL, dove il client gestisce il fatto che lo schema viene chiamato con l’estensione GQLschema. Ad esempio, l’esecuzione di una semplice richiesta GET di /content/cq:graphql/global/endpoint.GQLschema si tradurrà nell’output dello schema con il tipo di contenuto: text/x-graphql-schema;charset=iso-8859-1.

Generazione schema: modelli non pubblicati

Quando i frammenti di contenuto sono nidificati, può accadere che venga pubblicato un modello di Frammento di contenuto principale, ma non il modello di riferimento.

NOTA

L’interfaccia utente AEM impedisce che ciò accada, ma se la pubblicazione viene effettuata a livello di programmazione o con pacchetti di contenuto può verificarsi.

In questo caso, AEM genera uno schema incompleto per il modello di Frammento di contenuto principale. Ciò significa che il Riferimento al frammento, che dipende dal modello non pubblicato, viene rimosso dallo schema.

Campi

Nello schema sono presenti singoli campi, di due categorie di base:

  • Campi generati dall’utente.

    Per creare campi in base alla modalità di configurazione del modello di frammento di contenuto, viene utilizzata una selezione di Tipi di campo. I nomi dei campi vengono ricavati dal campo Nome proprietà del Tipo di dato.

    • C'è da prendere in considerazione anche la proprietà Rendering come, perché gli utenti possono configurare determinati tipi di dati; ad esempio, come testo a riga singola o come campo multiplo.
  • GraphQL per AEM genera anche una serie di campi di supporto.

    Questi vengono utilizzati per identificare un Frammento di contenuto o per ottenere ulteriori informazioni su di esso.

Tipi di campi

GraphQL per AEM supporta un elenco di tipi. Vengono rappresentati tutti i tipi di dati dei modelli di Frammento di contenuto supportati e i corrispondenti tipi GraphQL:

Modello di Frammento di contenuto: tipo di dati Tipo GraphQL Descrizione
Testo su riga singola Stringa, [Stringa] Utilizzato per stringhe semplici come nomi di autore, nomi di posizione, ecc.
Testo su più righe Stringa Utilizzato per l’output di testo, ad esempio il corpo di un articolo
Numero Mobile, [Mobile] Utilizzato per visualizzare il numero a virgola mobile e i numeri regolari
Booleano Booleano Utilizzato per visualizzare le caselle di controllo → semplici istruzioni true/false
Data e ora Calendario Utilizzato per visualizzare la data e l’ora in formato ISO 8086. A seconda del tipo selezionato, sono disponibili tre versioni da utilizzare in AEM GraphQL: onlyDate, onlyTime, dateTime
Enumerazione Stringa Utilizzato per visualizzare un’opzione da un elenco di opzioni definito durante la creazione del modello
Tag [Stringa] Utilizzato per visualizzare un elenco di stringhe che rappresentano tag utilizzati in AEM
Riferimento contenuto Stringa Utilizzato per visualizzare il percorso per un’altra risorsa in AEM
Riferimento frammento Un tipo di modello Utilizzato per fare riferimento ad altri frammenti di contenuto di un determinato tipo di modello, definito al momento della creazione del modello

Campi di supporto

Oltre ai tipi di dati per i campi generati dall’utente, GraphQL for AEM genera anche una serie di campi di supporto per consentire l’identificazione di un frammento di contenuto o per fornire informazioni aggiuntive su un frammento di contenuto.

Percorso

In GraphQL, il campo Percorso viene utilizzato come identificatore. Rappresenta il percorso della risorsa Frammenti di contenuto all’interno dell’archivio AEM. Questo è l’identificatore di un frammento di contenuto in quanto:

  • è univoco all’interno di AEM,
  • può essere facilmente recuperato.

Il seguente codice visualizza i percorsi di tutti i frammenti di contenuto creati in base al modello per frammenti di contenuto Person.

{
  personList {
    items {
      _path
    }
  }
}

Inoltre, per recuperare un singolo frammento di contenuto di un tipo specifico, è necessario determinarne prima il percorso. Esempio:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      firstName
      name
    }
  }
}

Vedi Query di esempio: un singolo frammento di città specifico.

Metadati

Tramite GraphQL, AEM espone inoltre i metadati di un frammento di contenuto. I metadati sono informazioni che descrivono un frammento di contenuto, ad esempio il titolo di un frammento di contenuto, il percorso della miniatura, la descrizione di un frammento di contenuto, la data di creazione, e così via.

Poiché i metadati vengono generati tramite l’Editor schemi e, pertanto, non dispongono di una struttura specifica, il tipo di TypedMetaData GraphQL è stato implementato per esporre i metadati di un frammento di contenuto. TypedMetaData espone le informazioni raggruppate per i seguenti tipi scalari:

Campo
stringMetadata:[StringMetadata]!
stringArrayMetadata:[StringArrayMetadata]!
intMetadata:[IntMetadata]!
intArrayMetadata:[IntArrayMetadata]!
floatMetadata:[FloatMetadata]!
floatArrayMetadata:[FloatArrayMetadata]!
booleanMetadata:[BooleanMetadata]!
booleanArrayMetadata:[booleanArrayMetadata]!
calendarMetadata:[CalendarMetadata]!
calendarArrayMetadata:[CalendarArrayMetadata]!

Ogni tipo scalare rappresenta una coppia nome-valore singola o un array di coppie nome-valore, in cui il valore di tale coppia è del tipo all'interno del quale è stato raggruppato.

Ad esempio, se vuoi recuperare il titolo di un frammento di contenuto, si tratta di una proprietà stringa, pertanto è necessario eseguire una query per tutti i metadati stringa:

Per eseguire una query per i metadati:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

Puoi visualizzare tutti i tipi di metadati GraphQL se visualizzi lo schema GraphQL generato. Tutti i tipi di modello hanno lo stesso TypedMetaData.

NOTA

Differenza tra metadati normali e quelli di array
Nota: StringMetadata e StringArrayMetadata si riferiscono a ciò che è memorizzato nell’archivio, non alla modalità di recupero.

Ad esempio, effettuando una chiamata del campo stringMetadata, può essere restituito un array di tutti i metadati memorizzati nell’archivio come una String; se si effettua una chiamata dell’stringArrayMetadata può essere restituito un array di tutti i metadati memorizzati nell’archivio come String[].

Vedi Query di esempio per metadati: elenca i metadati per riconoscimenti con titolo GB.

Varianti

Il campo _variations è stato implementato per semplificare l’esecuzione delle query sulle varianti di un frammento di contenuto. Esempio:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _variations
    }
  }
}

Vedi Query di esempio: tutte le città con una variante denominata.

NOTA

Se la variante specificata non esiste per un frammento di contenuto, la variante principale verrà restituita come impostazione predefinita (fallback).

Variabili GraphQL

GraphQL consente di inserire variabili nella query. Per ulteriori informazioni, consulta la documentazione di GraphQL per variabili.

Ad esempio, per ottenere tutti i frammenti di contenuto di tipo Article che hanno una variante specifica, puoi specificare la variabile variation in GraphiQL.

Variabili GraphQL

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
        }
    }
}

### in query variables
{
    "variation": "uk"
}

Direttive GraphQL

In GraphQL è possibile modificare le query basate su variabili, denominate Direttive GraphQL.

Ad esempio, puoi includere il campo adventurePrice in una query per tutti i AdventureModels basati su una variabile includePrice.

Direttive GraphQL

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}

### in query variables
{
    "includePrice": true
}

Filtro

Puoi inoltre utilizzare il filtro nelle query GraphQL per restituire dati specifici.

Il filtro utilizza una sintassi basata su operatori ed espressioni di tipo logico.

Ad esempio, la query (di base) seguente filtra tutti gli utenti denominati Jobs o Smith:

query {
  personList(filter: {
    name: {
      _logOp: OR
      _expressions: [
        {
          value: "Jobs"
        },
        {
          value: "Smith"
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

Per altri esempi, consulta:

GraphQL per AEM: riepilogo delle estensioni

Le operazioni di base delle query con GraphQL per AEM sono conformi alle specifiche standard di GraphQL. Per le query GraphQL con AEM sono disponibili alcune estensioni:

Query persistenti (memorizzazione in cache)

Dopo aver preparato una query con una richiesta POST, può essere eseguita con una richiesta GET memorizzabile nella cache tramite cache HTTP o CDN.

Questo è necessario in quanto le query POST di solito non vengono memorizzate nella cache e se si utilizza GET con la query come parametro esiste un rischio significativo che il parametro diventi troppo grande per i servizi HTTP e gli intermediari.

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.

Di seguito sono riportati i passaggi necessari per mantenere una determinata query:

  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. È quindi possibile riprodurre nuovamente la query persistente utilizzando GETing 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
            }
          }
        }
      }'
    
  8. Esegui una query con parametri.

    Esempio:

    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
    $ curl -X GET \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
  9. Per eseguire la query al momento della pubblicazione, la struttura ad albero persistente correlata deve essere replicata

    • Utilizzo del metodo POST per la replica:

      $curl -X POST   http://localhost:4502/bin/replicate.json \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -F path=/conf/wknd/settings/graphql/persistentQueries/plain-article-query \
        -F cmd=activate
      
    • Utilizzo di un pacchetto:

      1. Crea una nuova definizione di pacchetto.
      2. Includi la configurazione (ad esempio, /conf/wknd/settings/graphql/persistentQueries).
      3. Crea il pacchetto.
      4. Replica il pacchetto.
    • Utilizzo dello strumento di replica/distribuzione.

      1. Passa allo strumento Distribuzione.
      2. Seleziona l’attivazione ad albero per la configurazione (ad esempio, /conf/wknd/settings/graphql/persistentQueries).
    • Utilizzo di un flusso di lavoro (tramite la configurazione del modulo di avvio dei flussi di lavoro):

      1. Definisci una regola di avvio del flusso di lavoro per l’esecuzione di un modello di flusso di lavoro che replichi la configurazione su eventi diversi (ad esempio, crea, modifica, ecc.).
  10. Quando la configurazione della query è attiva per la pubblicazione, si applicano gli stessi principi, utilizzando solo l’endpoint di pubblicazione.

    NOTA

    Per l’accesso anonimo il sistema presuppone che l’ACL consenta a “tutti” l’accesso alla configurazione della query.

    In caso contrario, non potrà essere eseguito.

    NOTA

    Eventuali punti e virgola (;) negli URL devono essere codificati.

    Ad esempio, nella richiesta di esecuzione di una query persistente:

    curl -X GET \ "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters%3bapath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    

Query dell’endpoint di GraphQL da un sito Web esterno

Per accedere all’endpoint di GraphQL da un sito web esterno è necessario configurare i seguenti elementi:

Filtro CORS

NOTA

Per una panoramica dettagliata della politica di condivisione delle risorse CORS in AEM vedi Comprendere la condivisione CORS (Cross-Origin Resource Sharing).

Per accedere all’endpoint GraphQL, è necessario configurare un criterio CORS nell’archivio Git del cliente. Questo viene fatto aggiungendo un file di configurazione OSGi CORS appropriato per gli endpoint desiderati.

Questa configurazione deve specificare un'origine sito Web attendibile alloworigin o alloworiginregexp per i quali deve essere concesso l'accesso.

Ad esempio, per consentire l’accesso all’endpoint GraphQL e all’endpoint con query persistenti per https://my.domain puoi utilizzare:

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

Se hai configurato un percorso personalizzato per l’endpoint, puoi utilizzarlo in allowedpaths.

Filtro referrer

Oltre alla configurazione CORS, è necessario configurare un filtro Referrer per consentire l’accesso da host di terze parti.

A questo scopo, aggiungi un file di configurazione OSGi Referrer Filter appropriato che:

  • specifica un nome host fidato del sito web; allow.hosts oppure allow.hosts.regexp,
  • concede l’accesso per questo nome host.

Ad esempio, per concedere l’accesso alle richieste con il Referrer my.domain puoi:

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}
ATTENZIONE

Spetta al cliente:

  • concedere l’accesso solo ai domini attendibili;
  • assicurarsi che non siano esposte informazioni sensibili;
  • non utilizzare una sintassi con carattere jolly [*]; questa infatti comporterebbe la disattivazione dell’accesso autenticato all’endpoint GraphQL, rendendolo accessibile a chiunque.
ATTENZIONE

Tutti gli schemi GraphQL (derivati dai modelli per frammenti di contenuto che sono stati abilitati) sono leggibili attraverso l’endpoint GraphQL.

Ciò significa che devi assicurarti che non siano disponibili dati sensibili, che in questo modo potrebbero trapelare; ad esempio, informazioni che potrebbero essere presenti come nomi di campo nella definizione del modello.

Autenticazione

Vedi Autenticazione per query GraphQL AEM remote su frammenti di contenuto.

Domande frequenti

Domande poste:

  1. D: “quali sono le differenze tra l’API di GraphQL per AEM e l’API di Query Builder?

    • R:
      l’API di GraphQL per AEM offre il controllo totale dell’output JSON ed è uno standard di settore per l’esecuzione di query sui contenuti.
      In futuro, AEM prevede di investire nell’API di GraphQL per AEM.

Tutorial: guida introduttiva ad AEM headless e GraphQL

Cerchi un pratico tutorial? Dai un'occhiata al tutorial Guida introduttiva di headless AEM e GraphQL che illustra come creare ed esporre contenuti, utilizzati da un’app esterna, mediante le API GraphQL di AEM in uno scenario CMS headless.

In questa pagina