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 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, dà ai clienti la possibilità di chiedere esattamente ciò di cui hanno bisogno e niente di più, rende più semplice l'evoluzione delle API nel tempo e abilita potenti strumenti di sviluppo.".

  Vedere GraphQL.org

• "…una specifica aperta per un livello API flessibile. Inserisci GraphQL sui tuoi backend esistenti per creare prodotti più rapidamente che mai…".

  Vedere Esplora GraphQL.

• "…una lingua e una specifica per le query di dati sviluppata internamente da Facebook nel 2012 prima di essere pubblicamente aperta dal 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 è 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

Terminologia GraphQL

GraphQL utilizza quanto segue:

• Query

• Schemi e tipi:

  • Gli schemi sono generati da AEM basati sui modelli di frammenti di contenuto.
  • Utilizzando gli schemi, GraphQL presenta i tipi e le operazioni consentiti per GraphQL per AEM implementazione.

• Campi

• Endpoint GraphQL

  • Percorso in AEM che risponde alle query GraphQL e fornisce l'accesso agli schemi GraphQL.

  • Per ulteriori informazioni, vedere Abilitazione dell'endpoint GraphQL.

Per informazioni dettagliate, comprese le Best Practices, consultate (GraphQL.org) Introduction to GraphQL (Introduzione a GraphQL.org).

Tipi di query GraphQL

Con GraphQL è possibile eseguire query per restituire:

• A voce singola

• Un elenco di voci

GraphQL per AEM endpoint

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

Il percorso del repository di GraphQL per AEM endpoint è:

/content/cq:graphql/global/endpoint

Nell’URL della richiesta l’app può usare il seguente percorso:

/content/_cq_graphql/global/endpoint.json

Per abilitare l'endpoint per GraphQL per AEM è necessario:

• Abilita l'endpoint GraphQL
• Eseguire configurazioni aggiuntive

Abilitazione dell'endpoint GraphQL

Per abilitare le query GraphQL in AEM, create un endpoint in /content/cq:graphql/global/endpoint:

• I nodi cq:graphql e global devono essere di tipo sling:Folder.
• Il nodo endpoint deve essere di tipo nt:unstructured e contenere sling:resourceType di graphql/sites/components/endpoint.

Configurazioni aggiuntive per Endpoint GraphQL

Sono necessarie configurazioni aggiuntive:

• Dispatcher:
  • Per consentire gli URL richiesti
  • Obbligatorio
• URL personalizzato:
  • Per allocare un URL semplificato per l'endpoint
  • Facoltativo
• Configurazione OSGi:
  • Configurazione servlet GraphQL:
    • Gestisce le richieste all'endpoint
    • Il nome della configurazione è org.apache.sling.graphql.core.GraphQLServlet. Deve essere fornito come configurazione di fabbrica OSGi
    • sling.servlet.extensions deve essere impostato su [json]
    • sling.servlet.methods deve essere impostato su [GET,POST]
    • sling.servlet.resourceTypes deve essere impostato su [graphql/sites/components/endpoint]
    • Obbligatorio
  • Configurazione servlet schema:
    • Crea lo schema GraphQL
    • Il nome della configurazione è com.adobe.aem.graphql.sites.adapters.SlingSchemaServlet. Deve essere fornito come configurazione di fabbrica OSGi
    • sling.servlet.extensions deve essere impostato su [GQLschema]
    • sling.servlet.methods deve essere impostato su [GET]
    • sling.servlet.resourceTypes deve essere impostato su [graphql/sites/components/endpoint]
    • Obbligatorio
  • Configurazione CSRF:
    • Protezione dell'endpoint
    • Il nome della configurazione è com.adobe.granite.csrf.impl.CSRFFilter
    • Aggiungi /content/cq:graphql/global/endpoint all'elenco esistente di percorsi esclusi (filter.excluded.paths)
    • Obbligatorio

Pacchetti di supporto

Per semplificare la configurazione di un endpoint GraphQL, Adobe fornisce il pacchetto GraphQL Sample Project.

Questo archivio contiene sia la configurazione aggiuntiva che l'endpoint GraphQL. Se installato in un'istanza AEM normale, verrà esposto un endpoint GraphQL completamente funzionante in /content/cq:graphql/global/endpoint.

Questo pacchetto è inteso come un progetto per i vostri progetti GraphQL. Per informazioni sull'utilizzo del pacchetto, vedere il pacchetto README.

Se preferite creare manualmente la configurazione richiesta, Adobe fornisce anche un GraphQL Endpoint Content Package dedicato. Questo pacchetto di contenuto contiene solo l'endpoint GraphQL, senza alcuna configurazione.

Interfaccia GraphiQL

È disponibile per l'uso con AEM GraphQL un'implementazione dell'interfaccia standard GraphiQL. Questo può essere installato con AEM.

Questa interfaccia 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:

Installazione dell'interfaccia AEM GraphiQL

L'interfaccia utente GraphiQL può essere installata su AEM con un pacchetto dedicato: il pacchetto GraphiQL Content Package v0.0.4.

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.

Autorizzazioni

Le autorizzazioni sono quelle necessarie per accedere alle risorse.

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 Enabled Content Fragment Models 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 referencearticle.

   • 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/cq:graphql/global/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.

{
  personList {
    items {
      _path
    }
  }
}

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

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

Vedere Esempio di query - Un singolo frammento di città specifico.

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:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _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:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _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!) {
    articleList(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
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}
 
### in query variables
{
    "includePrice": true
}

Filtro

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

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

Ad esempio, la seguente query (di base) filtra tutte le persone con un nome Jobs o Smith:

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

Per ulteriori esempi, vedete:

• dettagli di GraphQL per AEM estensioni

• Query di esempio con questo contenuto e struttura di esempio

  • E Contenuto e struttura del campione preparati per l'uso nelle query di esempio

• Query di esempio basate sul progetto WKND

Query dell'endpoint GraphQL da un sito Web esterno

Per accedere all’endpoint GraphQL da un sito Web esterno è necessario configurare:

• Filtro CORS
• Filtro referente

Filtro CORS

Per accedere all'endpoint GraphQL, è necessario configurare un criterio CORS nell'archivio Git del cliente. A questo scopo, aggiungete un file di configurazione OSGi CORS appropriato per gli endpoint desiderati.

Questa configurazione deve specificare un'origine di sito Web attendibile alloworigin o alloworiginregexp per la quale è necessario concedere l'accesso.

Ad esempio, per concedere l'accesso all'endpoint GraphQL per https://my.domain è possibile 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"
  ]
}

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

Filtro referente

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

A questo scopo, aggiungete un file di configurazione del filtro OSGi Referrer appropriato che:

• specifica un nome host del sito Web affidabile; allow.hosts o allow.hosts.regexp,
• concede l'accesso per questo nome host.

Ad esempio, per concedere l'accesso per le richieste con il Referente my.domain è possibile:

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

Autenticazione

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

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.