AEM GraphQL API per l'utilizzo con frammenti di contenuto

L'API Adobe Experience Manager come Cloud Service (AEM) GraphQL utilizzata con i frammenti di contenuto è fortemente basata sull'API GraphQL standard open source.

L'utilizzo dell'API GraphQL in AEM consente la distribuzione efficiente di frammenti di contenuto ai client JavaScript nelle implementazioni CMS headless:

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

API GraphQL

"GraphQL è un linguaggio e una specifica di query di dati sviluppati internamente da Facebook nel 2012 prima di essere pubblicamente aperti in origine 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 nella produzione da centinaia di organizzazioni di tutte le dimensioni…" Vedere GraphQL Foundation.

Per ulteriori informazioni sull'API GraphQL, consultate le seguenti sezioni (tra cui molte altre risorse):

• A graphql.org:

  • Introduzione a GraphQL

  • Specifica GraphQL

• A graphql.com:

  • Guide

  • Esercitazioni

  • Case study

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

• graphQL.org - Java

• GraphQL Java a GitHub

Interfaccia GraphiQL

AEM Graph API include un'implementazione dell'interfaccia standard GraphiQL. Questo consente di inserire e testare direttamente le query.

Esempio:

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

Questo fornisce funzioni come evidenziazione della sintassi, completamento automatico, suggerimento automatico, insieme a una cronologia e alla documentazione online:

Casi di utilizzo per ambienti di creazione e pubblicazione

I casi di utilizzo possono dipendere dal tipo di AEM come ambiente di Cloud Service:

• Ambiente di pubblicazione; utilizzato per:

  • Dati query per l'applicazione JS (caso d'uso standard)

• Ambiente di authoring; utilizzato per:

  • Dati query per "scopi di gestione del contenuto":
    • GraphQL in AEM come Cloud Service è attualmente un'API di sola lettura.
    • L'API REST può essere utilizzata per le operazioni CR(u)D.

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 un'API affidabile per l'interrogazione dei dati su una determinata istanza. A tal fine, un client deve recuperare il Schema, che contiene tutti i tipi necessari per una query.

Per i frammenti di contenuto, gli schemi GraphQL (struttura e tipi) si basano su Modelli di frammenti di contenuto e i relativi tipi di dati.

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

1. Un Modello Di Frammento Di Contenuto:

   

2. Lo schema GraphQL corrispondente (output dalla documentazione automatica GraphiQL):
   

   Questo indica che il tipo generato ArticleModel contiene diversi campi.

   • Tre di essi sono stati controllati dall'utente: author, main e linked_article.

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

3. Dopo che un utente crea un frammento di contenuto basato sul modello Articolo, può essere interrogato tramite GraphQL. Ad esempio, vedere Query di esempio (basate su una struttura di frammenti di contenuto di esempio da utilizzare con GraphQL](/docs/experience-manager-cloud-service/assets/admin/content-fragments-graphql-samples.html?lang=it#content-fragment-structure-graphql)).[

In GraphQL per AEM, lo schema è flessibile. Questo 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 aggiorna un modello di frammento di contenuto.

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

Ad esempio, se:

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

   1. Verranno generati i tipi GraphQL per Model-1 e Model-2.

2. Quindi modificare Content-Fragment-Model-2:

   1. Viene aggiornato solo il tipo Model-2 GraphQL.

   2. Mentre Model-1 rimarrà uguale.

Lo schema viene distribuito attraverso lo stesso endpoint delle query GraphQL, con il client che gestisce il fatto che lo schema viene chiamato con l'estensione GQLschema. Ad esempio, eseguendo una semplice richiesta GET su /content/graphql/endpoint.GQLschema si ottiene l'output dello schema con il tipo di contenuto: text/x-graphql-schema;charset=iso-8859-1.

espandibili

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

• Campi generati.

  Una selezione di Tipi di campo viene utilizzata per creare campi in base alla modalità di configurazione del modello di frammento di contenuto. I nomi dei campi sono ricavati dal campo Nome proprietà del Tipo di dati.

  • È inoltre disponibile la proprietà Rendering come, in quanto gli utenti possono configurare alcuni tipi di dati; ad esempio, come testo a riga singola o multicampo.

• GraphQL per AEM genera anche un numero di campi helper.

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

Tipi di campi

GraphQL per AEM supporta un elenco di tipi. Sono rappresentati tutti i tipi di dati supportati per i modelli di frammento di contenuto e i tipi di GraphQL corrispondenti:

Modello frammento di contenuto - Tipo di dati	GraphQL Type	Descrizione
Testo su riga singola	String, [String]	Utilizzata 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 data e ora in formato ISO 8086
Enumerazione	Stringa	Utilizzato per visualizzare un'opzione da un elenco di opzioni definite durante la creazione del modello
Tag	[Stringa]	Utilizzato per visualizzare un elenco di stringhe che rappresentano i tag utilizzati in AEM
Riferimento contenuto	Stringa	Utilizzato per visualizzare il percorso verso un'altra risorsa in AEM
Riferimento frammento	Tipo di modello	Utilizzato per fare riferimento a un altro frammento di contenuto di un certo tipo di modello, definito al momento della creazione del modello

Campi helper

Oltre ai tipi di dati per i campi generati dall'utente, GraphQL per AEM genera anche un numero di campi helper per facilitare l'identificazione di un frammento di contenuto o per fornire ulteriori informazioni su un frammento di contenuto.

Percorso

Il campo percorso viene utilizzato come identificatore in GraphQL. Rappresenta il percorso della risorsa Frammento di contenuto all'interno dell'archivio AEM. È stato scelto come identificatore di un frammento di contenuto, in quanto:

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

Nel codice seguente vengono visualizzati i percorsi di tutti i frammenti di contenuto creati in base al modello di frammento di contenuto Person.

{
  persons {
    items {
      _path
    }
  }
}

Per recuperare un singolo frammento di contenuto di un tipo specifico, è necessario anche determinarne prima il percorso. ad esempio:

{
    person(_path="/content/dam/path/to/fragment/john-doe") {
        _path
        name
        first-name
    }
}

Vedere Esempio di query - Un frammento di città singola.

Metadati

Tramite GraphQL, AEM anche esporre i metadati di un frammento di contenuto. Per metadati si intendono le informazioni che descrivono un frammento di contenuto, ad esempio il titolo di un frammento di contenuto, il percorso delle miniature, la descrizione di un frammento di contenuto, la data di creazione, tra l’altro.

Poiché i metadati vengono generati tramite l'Editor schema e in quanto tali non dispongono di una struttura specifica, il tipo TypedMetaData GraphQL è stato implementato per esporre i metadati di un frammento di contenuto. TypedMetaData espone le informazioni raggruppate dai seguenti tipi di scala:

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

Ogni tipo di scala rappresenta una coppia nome-valore singola o un array di coppie nome-valore, dove il valore di quella coppia è del tipo in cui è stata raggruppata.

Ad esempio, se desiderate recuperare il titolo di un frammento di contenuto, sappiamo che questa proprietà è una proprietà String, quindi eseguiamo una query per tutti i metadati stringa:

Per eseguire una query per i metadati:

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

È possibile visualizzare tutti i tipi di metadati GraphQL se si visualizza lo schema Generated GraphQL. Tutti i tipi di modello hanno lo stesso TypedMetaData.

Consultate Esempio di query per metadati - Elenco dei metadati per i premi denominati GB.

Varianti

Il campo _variations è stato implementato per semplificare la query delle varianti di un frammento di contenuto. Esempio:

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

Vedere Esempio di query - Tutte le città con una variante denominata.

Variabili GraphQL

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

Ad esempio, per ottenere tutti i frammenti di contenuto di tipo Article con una specifica variante, è possibile specificare la variabile variation in GraphiQL:

### query
query GetArticlesByVariation($variation: String!) {
    articles(variation: $variation) {
        items {
            _path
            author
        }
    }
}
 
### in query variables
{
    "variation": "uk"
}

Direttive GraphQL

In GraphQL è possibile modificare la query in base alle variabili, denominate Direttive GraphQL.

Ad esempio, è possibile includere il campo adventurePrice in una query per tutti i AdventureModels, in base a una variabile includePrice.

query getAdventureByType($includePrice: Boolean!) {
  adventures {
    items {
      adventureType
      adventurePrice @include(if: $includePrice)
    }
  }
}
 
### in query variables
{
    "includePrice": true
}

Query persistenti (memorizzazione nella cache)

Dopo aver preparato una query con una richiesta di POST, può essere eseguita con una richiesta di GET che può essere memorizzata nella cache dalle cache HTTP o da una CDN.

Questo è richiesto perché le query POST in genere non sono 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.

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

1. Preparate la query inserendola nel nuovo URL dell'endpoint /graphql/persist.json/<config>/<persisted-label>.

   Ad esempio, create 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, controllate la risposta.

   Ad esempio, verificate che l'esito sia positivo:

   {
     "action": "create",
     "configurationName": "wknd",
     "name": "plain-article-query",
     "shortPath": "/wknd/plain-article-query",
     "path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
   }
   

3. Potete quindi riprodurre nuovamente la query persistente utilizzando GETing l'URL /graphql/execute.json/<shortPath>.

   Ad esempio, utilizzate la query persistente:

   $ curl -X GET \
       http://localhost:4502/graphql/execute.json/wknd/plain-article-query
   

4. Aggiornare una query persistente tramite POSTing a un percorso di query già esistente.

   Ad esempio, utilizzate 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. Create una query normale con wrapping.

   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. Create una query normale con wrapping 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. Esecuzione di 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 di un 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. Create una nuova definizione di pacchetto.
     2. Includete la configurazione (ad esempio, /conf/wknd/settings/graphql/persistentQueries).
     3. Create il pacchetto.
     4. Replicate il pacchetto.

   • Utilizzo dello strumento di replica/distribuzione.

     1. Passate allo strumento di distribuzione.
     2. Selezionate l'attivazione della struttura per la configurazione (ad esempio, /conf/wknd/settings/graphql/persistentQueries).

   • Utilizzo di un flusso di lavoro (tramite la configurazione di avvio del flusso di lavoro):

     1. Definite una regola di avvio del flusso di lavoro per eseguire un modello di workflow che replichi la configurazione su eventi diversi (ad esempio, create, modificate, tra gli altri).

10. Una volta che la configurazione della query è stata pubblicata, 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" di accedere alla configurazione della query.

    In caso contrario, non potrà essere eseguito.

    NOTA

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

    Ad esempio, come nella richiesta per eseguire 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 GraphQL da un sito Web esterno

Per consentire a un sito Web di terze parti di utilizzare l'output JSON, è necessario configurare un criterio CORS nell'archivio Git del cliente. A questo scopo, aggiungete un file di configurazione OSGi CORS appropriato per l’endpoint desiderato. Questa configurazione deve specificare un nome di sito Web attendibile (regex) per il quale concedere l'accesso.

• Accesso all’endpoint GraphQL:

  • alloworigin: [il vostro dominio] o alloworiginregexp: [il dominio regex]
  • metodi supportati: [POST]
  • Percorsi consentiti: ["/apps/graphql-enablement/content/endpoint.gql(/persisted?lang=it)?"]

• Accesso all'endpoint di query persistenti GraphQL:

  • alloworigin: [il vostro dominio] o alloworiginregexp: [il dominio regex]
  • metodi supportati: [GET]
  • Percorsi consentiti: ["/graphql/execute.json/.*"]

Filtro

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

Il filtro utilizza una sintassi basata su operatori logici ed espressioni.

Per esempi, vedete:

• dettagli di GraphQL per AEM estensioni

• Contenuto di esempio e struttura preparate per l’uso nelle query di esempio

• Query di esempio con questo contenuto e struttura di esempio

• Query di esempio basate sul progetto WKND

Autorizzazioni

Le autorizzazioni sono quelle necessarie per accedere alle risorse.

Punti finali

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

• accedere allo schema GraphQL,
• invia le tue query GraphQL,
• ricevere le risposte (alle query GraphQL).

Per poter accedere ai servlet GraphQL in AEM è necessario configurare un endpoint. Sono incluse anche due configurazioni OSGi.

1. Il servlet dello schema Sling che risponde alle richieste di recupero dello schema GraphQL:

   

   • I selettori (sling.servlet.selectors) devono essere lasciati vuoti.

   • Tipi di risorse(sling.servlet.resourceTypes) Definire il tipo di risorsa che il servlet GraphQL deve ascoltare.
     Esempio:
     graphql-enablement/components/endpoint.

   • Metodi (`sling.servlet.methods^)

     Il metodo HTTP che il servlet deve ascoltare; in genere GET.

   • Estensioni (sling.servlet.extensions)

     Specificare l'estensione a cui il servlet schema deve rispondere. In questo caso è GQLschema, per essere compatibile con le specifiche GraphQL.

2. Il servlet che risponde alle richieste graphql:

   

   • I selettori (sling.servlet.selectors) devono essere lasciati vuoti.

   • Tipo risorsa(sling.servlet.resourceTypes) Il tipo di risorsa a cui deve rispondere il servlet GraphQL.
     Esempio, graphql-enablement/components/endpoint.

   • Metodi (sling.servlet.methods) I metodi HTTP a cui il servlet GraphQL deve rispondere, in genere GET e POST.

   • Estensioni (sling.servlet.extensions) L'estensione per ascoltare le richieste GraphQL, in genere gql.

3. È ora necessario creare un endpoint, un nodo di sling:resourceType definito in queste configurazioni.
   Ad esempio, per creare un endpoint per il recupero dello schema GraphQL, creare un nuovo nodo in /apps/<my-site>/graphql:

   • Nome: endpoint
   • Tipo principale: nt:unstructured
   • sling:resourceType: graphql-enablement/components/endpoint

Domande frequenti

Domande sorte:

1. D: "In che modo l'API GraphQL per AEM è diversa dall'API di Query Builder?"

   • A: "L'API AEM GraphQL offre il controllo totale sull'output JSON ed è uno standard di settore per l'esecuzione di query sui contenuti.
     In futuro, AEM intende investire nell'API AEM GraphQL."

Esercitazione - Guida introduttiva a AEM headless e GraphQL

Stai cercando un'esercitazione pratica? Scoprite la Guida introduttiva AEM headless e l'esercitazione end-to-end di GraphQL che illustra come creare ed esporre contenuti utilizzando le API GraphQL di AEM e utilizzati da un'app esterna, in uno scenario CMS headless.