L'API AEM GraphQL per la distribuzione dei frammenti di contenuto è disponibile su richiesta.
Per abilitare l'API per il AEM come programma di Cloud Service, contattate il supporto di Adobe.
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:
"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:
A graphql.com:
GraphQL per AEM implementazione si basa sulla libreria Java GraphQL standard. Consulta:
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:
I casi di utilizzo possono dipendere dal tipo di AEM come ambiente di Cloud Service:
Ambiente di pubblicazione; utilizzato per:
Ambiente di authoring; utilizzato per:
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.
Un Modello Di Frammento Di Contenuto:
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.
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:
Installare un pacchetto contenente Content-Fragment-Model-1
e Content-Fragment-Model-2
:
Model-1
e Model-2
.Quindi modificare Content-Fragment-Model-2
:
Viene aggiornato solo il tipo Model-2
GraphQL.
Mentre Model-1
rimarrà uguale.
Questo è importante da notare nel caso in cui si desidera eseguire aggiornamenti in blocco sui modelli di frammenti di contenuto tramite l'API REST, o in altro modo.
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
.
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.
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.
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 |
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.
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:
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.
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
.
Differenza tra metadati normali e metadati array
Tenere presente che StringMetadata
e StringArrayMetadata
si riferiscono entrambi a ciò che è memorizzato nella directory archivio, non a come viene recuperato.
Ad esempio, chiamando il campo stringMetadata
si riceverà un array di tutti i metadati memorizzati nell'archivio come String
, e se si chiama stringArrayMetadata
si riceverà un array di tutti i metadati memorizzati nell'archivio come String[]
.
Consultate Esempio di query per metadati - Elenco dei metadati per i premi denominati GB.
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.
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"
}
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
}
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:
Prima di questo, è necessario abilitare le Query di persistenza GraphQL per la configurazione appropriata. Per ulteriori informazioni, vedere Abilitare la funzionalità dei frammenti di contenuto nel browser di configurazione.
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
}
}
}
}'
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"
}
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
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
}
}
}
}'
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 } } } }"}'
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 }}'
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
}
}
}
}'
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"
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:
/conf/wknd/settings/graphql/persistentQueries
).Utilizzo dello strumento di replica/distribuzione.
/conf/wknd/settings/graphql/persistentQueries
).Utilizzo di un flusso di lavoro (tramite la configurazione di avvio del flusso di lavoro):
Una volta che la configurazione della query è stata pubblicata, si applicano gli stessi principi, utilizzando solo l'endpoint di pubblicazione.
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.
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"
Per una panoramica dettagliata del criterio di condivisione delle risorse CORS, vedere Comprendere la condivisione delle risorse tra le origini (CORS).
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:
Accesso all'endpoint di query persistenti GraphQL:
Resta responsabilità del cliente:
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
Le autorizzazioni sono quelle necessarie per accedere alle risorse.
L’endpoint è il percorso utilizzato per accedere a GraphQL per AEM. Utilizzando questo percorso (o la vostra app) potete:
Per poter accedere ai servlet GraphQL in AEM è necessario configurare un endpoint. Sono incluse anche due configurazioni OSGi.
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.
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
.
È 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
:
endpoint
nt:unstructured
graphql-enablement/components/endpoint
Domande sorte:
D: "In che modo l'API GraphQL per AEM è diversa dall'API di Query Builder?"
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.