API GraphQL AEM per l’utilizzo con Frammenti di contenuto graphql-api-for-use-with-content-fragments

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

L’API GraphQL dell’AEM utilizzata con i Frammenti di contenuto si basa in larga misura 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:

Prerequisiti prerequisites

I clienti che utilizzano GraphQL devono installare il pacchetto 1.0.5 dell’indice Frammento di contenuto AEM con GraphQL. Per ulteriori dettagli, consulta le note sulla versione.

API GraphQL graphql-api

GraphQL è:

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

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

Terminologia GraphQL graphql-terminology

GraphQL utilizza quanto segue:

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

Tipi di query GraphQL graphql-query-types

Con GraphQL è possibile eseguire query per ottenere:

AEM fornisce funzionalità per convertire le query (di entrambi i tipi) in query persistenti memorizzate nella cache da Dispatcher e CDN.

Best practice per le query GraphQL (Dispatcher e CDN) graphql-query-best-practices

Le query persistenti sono il metodo consigliato da utilizzare nelle istanze di pubblicazione come:

Le query GraphQL con l’utilizzo di POST non sono consigliate in quanto non sono memorizzate nella cache. Quindi, in un’istanza predefinita, Dispatcher è configurato per bloccarle.

Anche se GraphQL supporta le richieste di GET, queste possono raggiungere dei limiti (ad esempio, la lunghezza dell’URL) che possono essere evitati utilizzando query persistenti.

Per ulteriori dettagli, vedere Abilitare la memorizzazione nella cache delle query persistenti.

Interfaccia GraphiQL graphiql-interface

È disponibile un'implementazione dell'interfaccia standard GraphiQL da utilizzare con AEM GraphQL.

Questa interfaccia consente di inserire e testare direttamente le query.

Ad esempio:

Fornisce funzioni quali evidenziazione della sintassi, completamento automatico, suggerimento automatico, nonché una cronologia e una documentazione online:

Casi di utilizzo per ambienti di authoring e pubblicazione use-cases-author-publish-environments

I casi d’uso possono dipendere dal tipo di ambiente AEM:

Autorizzazioni permission

Le autorizzazioni sono necessarie per accedere ad Assets.

Le query GraphQL vengono eseguite con l’autorizzazione dell’utente AEM della richiesta sottostante. Se l’utente non dispone dell’accesso in lettura ad alcuni frammenti (memorizzati come Assets), questi non entrano a far parte del set di risultati.

Inoltre, l’utente deve avere accesso a un endpoint GraphQL per poter eseguire query GraphQL.

Generazione schema schema-generation

GraphQL è un’API 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. Per completare queste linee guida, 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.

Ad esempio, se un utente ha creato un modello di frammento di contenuto denominato Article, AEM genera un tipo GraphQL ArticleModel. I campi all’interno di questo tipo corrispondono ai campi e ai tipi di dati definiti nel modello. Inoltre, crea alcuni punti di ingresso per le query che operano su questo tipo, come articleByPath o articleList.

In GraphQL per AEM, lo schema è flessibile. Questa flessibilità significa che viene generata automaticamente ogni volta che viene creato, aggiornato o eliminato un modello per frammenti 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:

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 su /content/cq:graphql/global/endpoint.GQLschema genera l'output dello schema con il tipo di contenuto text/x-graphql-schema;charset=iso-8859-1.

Generazione schema: modelli non pubblicati schema-generation-unpublished-models

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.

In questo caso, AEM genera uno schema incompleto per il modello di Frammento di contenuto padre. Significa che il Riferimento frammento, che dipende dal modello non pubblicato, viene rimosso dallo schema.

Campi fields

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

Tipi di dati data-types

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:

Campi di supporto helper-fields

Oltre ai tipi di dati per i campi generati dall'utente, GraphQL for AEM genera anche diversi campi helper per identificare un frammento di contenuto o per fornire informazioni aggiuntive su un frammento di contenuto.

Tali campi di supporto sono contrassegnati con un _ precedente per distinguere tra ciò che è stato definito dall’utente e ciò che è stato generato automaticamente.

Percorso path

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

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

{
  personList {
    items {
      _path
    }
  }
}

Per recuperare un singolo frammento di contenuto di un tipo specifico, devi prima determinarne il percorso. Esempio:

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

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

Metadati metadata

Tramite GraphQL, AEM espone inoltre i metadati di un frammento di contenuto. I metadati sono informazioni che descrivono un frammento di contenuto, ad esempio quanto segue:

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:

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 desideri recuperare il titolo di un frammento di contenuto, questa proprietà è una proprietà Stringa e puoi quindi 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.

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

Varianti variations

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.

Variabili GraphQL graphql-variables

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.

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

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

Direttive GraphQL graphql-directives

In GraphQL è possibile modificare la query basata su variabili, denominate Direttive GraphQL.

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

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

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

Filtro filtering

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.

La parte più atomica è una singola espressione che può essere applicata al contenuto di un determinato campo. Confronta il contenuto del campo con un valore costante specificato.

Ad esempio, l'espressione seguente confronta il contenuto del campo con il valore some text e ha esito positivo se il contenuto è uguale al valore. In caso contrario, l’espressione non riesce.:

{
  value: "some text"
  _op: EQUALS
}

Per confrontare i campi con un determinato valore è possibile utilizzare i seguenti operatori:

Alcuni tipi consentono inoltre di specificare opzioni aggiuntive che modificano la modalità di valutazione di un'espressione:

Le espressioni possono essere combinate in un set tramite un operatore logico (_logOp):

Ogni campo può essere filtrato in base al proprio set di espressioni. I set di espressioni di tutti i campi menzionati nell’argomento filtro vengono infine combinati dal proprio operatore logico.

Una definizione di filtro (passata come argomento filter a una query) contiene:

È possibile omettere _logOp se si desidera combinare gli elementi con AND e _operator se si desidera verificare l'uguaglianza, poiché questi valori sono predefiniti.

L’esempio seguente illustra una query completa che filtra tutte le persone con una lastName di Provo o contenenti sjö, indipendentemente dal caso:

{
  authorList(filter: {
    lastname: {
      _logOp: OR
      _expressions: [
        {
          value: "sjö",
          _operator: CONTAINS,
          _ignoreCase: true
        },
        {
          value: "Provo"
        }
      ]
    }
  }) {
    items {
      lastName
      firstName
    }
  }
}

Quando si esegue una query GraphQL utilizzando variabili facoltative, se per la variabile facoltativa è stato fornito un valore specifico not, la variabile verrà ignorata nella valutazione del filtro. Ciò significa che i risultati della query conterranno tutti i valori, sia null che non null, per la proprietà correlata alla variabile di filtro.

Ad esempio, nella query seguente, dove non è specificato alcun valore per la proprietà lastName:

query getAuthorsFilteredByLastName($authorLastName: String) {
  authorList(filter:
    {
      lastName: {_expressions: {value: $authorLastName}
      }}) {
    items {
      lastName
    }
  }
}

Verranno restituiti tutti gli autori:

{
  "data": {
    "authorList": {
      "items": [
        {
          "lastName": "Hammer"
        },
        {
          "lastName": "Provo"
        },
        {
          "lastName": "Wester"
        },
        {
          "lastName": null
        },
         ...
      ]
    }
  }
}

È anche possibile filtrare i campi nidificati, ma non è consigliabile, in quanto potrebbe causare problemi di prestazioni.

Per altri esempi, consulta:

Ordinamento sorting

Questa funzione consente di ordinare i risultati della query in base a un campo specificato.

I criteri di ordinamento:

Esempio:

query {
  authorList(sort: "lastName, firstName") {
    items {
      firstName
      lastName
    }
  }
}

Inoltre:

{
  authorList(sort: "lastName DESC, firstName DESC") {
    items {
        lastName
        firstName
    }
  }
}

È inoltre possibile ordinare in base a un campo all’interno di un frammento nidificato utilizzando il formato nestedFragmentname.fieldname.

Esempio:

query {
  articleList(sort: "authorFragment.lastName")  {
    items {
      title
      authorFragment {
        firstName
        lastName
        birthDay
      }
      slug
    }
  }
}

Paging paging

Questa funzione consente di eseguire il paging sui tipi di query che restituiscono un elenco. Vengono forniti due metodi:

Query elenco: offset e limite list-offset-limit

In una ...Listquery puoi utilizzare offset e limit per ottenere un sottoinsieme specifico di risultati:

Ad esempio, per un output con la pagina dei risultati contenente fino a cinque articoli, a partire dal quinto articolo dell’elenco dei risultati completo:

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}

Query impaginata: prima e dopo paginated-first-after

Il tipo di query ...Paginated riutilizza la maggior parte delle funzionalità del tipo di query ...List (filtro, ordinamento), ma invece di utilizzare gli argomenti offset/limit utilizza first/after come definiti in Specifica delle connessioni del cursore GraphQL. È possibile trovare un’introduzione meno formale in Introduzione a GraphQL.

Ad esempio, restituisce la pagina dei risultati contenenti fino a cinque avventure, a partire dalla voce del cursore specificata nell’elenco dei risultati completo:

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}

Query persistenti GraphQL: abilitazione della memorizzazione in cache in Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

La memorizzazione nella cache delle query persistenti non è abilitata per impostazione predefinita in Dispatcher. L’abilitazione predefinita non è possibile perché i clienti che utilizzano CORS (Cross-Origin Resource Sharing) con più origini devono rivedere, e possibilmente aggiornare, la configurazione di Dispatcher.

Abilita la memorizzazione nella cache delle query persistenti enable-caching-persisted-queries

Per abilitare la memorizzazione nella cache delle query persistenti, sono necessari i seguenti aggiornamenti ai file di configurazione di Dispatcher:

Configurazione CORS in Dispatcher cors-configuration-in-dispatcher

I clienti che utilizzano richieste CORS potrebbero dover rivedere e aggiornare la configurazione CORS in Dispatcher.

GraphQL per AEM: riepilogo delle estensioni graphql-extensions

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:

Filtro CORS cors-filter

Per accedere all’endpoint GraphQL, configura un criterio CORS nell’archivio Git del cliente. Questa configurazione viene eseguita aggiungendo un file di configurazione OSGi CORS appropriato per uno o più endpoint desiderati.

Questa configurazione deve specificare un'origine del sito Web attendibile alloworigin o alloworiginregexp per la quale deve essere consentito l'accesso.

Ad esempio, per concedere l'accesso all'endpoint GraphQL e all'endpoint delle 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 referrer-filter

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

Questo filtro viene eseguito aggiungendo un file di configurazione del filtro di riferimento OSGi appropriato che:

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":[
      ""
    ]
}

Limitazioni limitations

Per proteggere da potenziali problemi, esistono limitazioni predefinite imposte alle query:

È inoltre necessario essere a conoscenza di:

Autenticazione authentication

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

Domande frequenti faqs

Domande poste:

Tutorial: guida introduttiva ad AEM headless e GraphQL tutorial

Cerchi un pratico tutorial? Dai un’occhiata al tutorial Guida introduttiva di AEM headless 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.