L’API GraphQL di AEM fornisce un potente linguaggio di query per esporre i dati dei frammenti di contenuto alle applicazioni downstream. I modelli di frammenti di contenuto definiscono lo schema di dati utilizzato dai frammenti di contenuto. Ogni volta che un modello di frammento di contenuto viene creato o aggiornato, lo schema viene tradotto e aggiunto al "grafico" che costituisce l’API GraphQL.
In questo capitolo, esaminiamo alcune query GraphQL comuni per raccogliere contenuti utilizzando un IDE denominato GraphiQL. L'IDE GraphiQL ti consente di testare e perfezionare rapidamente le query e i dati restituiti. Offre inoltre un facile accesso alla documentazione, facilitando l’apprendimento e la comprensione dei metodi disponibili.
Si tratta di un tutorial in più parti e si presume che i passaggi descritti in Authoring di frammenti di contenuto sono state completate.
È necessario configurare un endpoint GraphQL per abilitare le query API GraphQL per i frammenti di contenuto.
Dalla schermata iniziale AEM, passa a Strumenti > Generale > GraphQL.
Tocca Crea nell’angolo in alto a destra, nella finestra di dialogo risultante immetti i seguenti valori:
Tocca Crea per salvare l’endpoint.
Gli endpoint GraphQL creati in base a una configurazione di progetto abilitano solo le query rispetto ai modelli appartenenti a tale progetto. In questo caso, le uniche query contro Persona e Team è possibile utilizzare modelli.
È inoltre possibile creare un endpoint globale per abilitare le query sui modelli in più configurazioni. Questo dovrebbe essere utilizzato con cautela in quanto potrebbe aprire l’ambiente a ulteriori vulnerabilità di sicurezza e aggiungere alla complessità complessiva nella gestione dei AEM.
Ora dovresti vedere un endpoint GraphQL abilitato nell’ambiente.
La GraphiQL lo strumento consente agli sviluppatori di creare e testare query rispetto al contenuto nell’ambiente AEM corrente. Lo strumento GraphiQL consente inoltre agli utenti di persistere o salvare le query che devono essere utilizzate dalle applicazioni client in un'impostazione di produzione.
Esamina quindi la potenza dell’API GraphQL AEM utilizzando l’IDE GraphiQL integrato.
Dalla schermata iniziale AEM, passa a Strumenti > Generale > Editor query GraphQL.
In potrebbero non essere integrate le versioni precedenti di AEM dell'IDE GraphiQL. Può essere installato manualmente seguendo questi istruzioni.
Nell’angolo in alto a destra, assicurati che l’endpoint sia impostato su Endpoint progetto personale.
In questo modo tutte le query verranno estese ai modelli creati nella Progetto personale progetto.
Un requisito comune consiste nell’eseguire query per più frammenti di contenuto.
Incolla la seguente query nel pannello principale (sostituendo l’elenco dei commenti):
query allTeams {
teamList {
items {
_path
title
}
}
}
Premere Play nel menu principale per eseguire la query. Dovresti visualizzare i risultati dei frammenti di contenuto del capitolo precedente:
Posizionare il cursore sotto il title
testo e immetti CTRL+Spazio per attivare i suggerimenti sul codice. Aggiungi shortname
e description
alla query.
Esegui nuovamente la query premendo il pulsante Play e dovresti vedere che i risultati includono le proprietà aggiuntive di shortname
e description
.
La shortname
è una proprietà semplice e description
è un campo di testo su più righe e l’API GraphQL ci consente di scegliere vari formati per i risultati, come html
, markdown
, json
oppure plaintext
.
Successivamente, l'esperimento con l'esecuzione di query consiste nel recupero dei frammenti nidificati, ricorda che l' Team il modello fa riferimento a Persona modello.
Aggiorna la query per includere la teamMembers
proprietà. Ricorda che si tratta di un Riferimento frammento al modello persona. È possibile restituire le proprietà del modello Persona:
query allTeams {
teamList {
items {
_path
title
shortName
description {
plaintext
}
teamMembers {
fullName
occupation
}
}
}
}
Risposta JSON:
{
"data": {
"teamList": {
"items": [
{
"_path": "/content/dam/my-project/en/team-alpha",
"title": "Team Alpha",
"shortName": "team-alpha",
"description": {
"plaintext": "This is a description of Team Alpha!"
},
"teamMembers": [
{
"fullName": "John Doe",
"occupation": [
"Artist",
"Influencer"
]
},
{
"fullName": "Alison Smith",
"occupation": [
"Photographer"
]
}
]
}
]
}
}
}
La possibilità di eseguire query sui frammenti nidificati è una funzione potente dell’API GraphQL AEM. In questo semplice esempio, la nidificazione è profonda solo due livelli. Tuttavia è possibile nidificare ulteriormente i frammenti. Ad esempio, se è presente un Indirizzo modello associato a un Persona sarebbe possibile restituire i dati di tutti e tre i modelli in un’unica query.
Ora, vediamo come è possibile filtrare i risultati in un sottoinsieme di frammenti di contenuto in base a un valore di proprietà.
Immetti la seguente query nell’interfaccia utente GraphiQL:
query personByName($name:String!){
personList(
filter:{
fullName:{
_expressions:[{
value:$name
_operator:EQUALS
}]
}
}
){
items{
_path
fullName
occupation
}
}
}
La query di cui sopra esegue una ricerca per tutti i frammenti Persona nel sistema. Il filtro aggiunto all’inizio della query esegue un confronto sui name
e la stringa della variabile $name
.
In Variabili di query inserisci quanto segue:
{"name": "John Doe"}
Esegui la query, è previsto che solo Persone Il frammento di contenuto viene restituito con un valore di John Doe
.
Esistono molte altre opzioni per filtrare e creare query complesse, vedi Imparare a utilizzare GraphQL con AEM - Contenuto di esempio e query.
Ottimizza la query di cui sopra per recuperare l’immagine del profilo
query personByName($name:String!){
personList(
filter:{
fullName:{
_expressions:[{
value:$name
_operator:EQUALS
}]
}
}
){
items{
_path
fullName
occupation
profilePicture{
... on ImageRef{
_path
_authorUrl
_publishUrl
height
width
}
}
}
}
}
La profilePicture
è un riferimento al contenuto e si prevede che sia un'immagine, quindi incorporato ImageRef
viene utilizzato l'oggetto . Questo ci consente di richiedere dati aggiuntivi sull'immagine a cui fare riferimento, come il width
e height
.
È inoltre possibile eseguire query dirette su un singolo frammento di contenuto. Il contenuto in AEM viene memorizzato in modo gerarchico e l’identificatore univoco di un frammento è basato sul percorso del frammento.
Immetti la seguente query nell'editor GraphiQL:
query personByPath($path: String!) {
personByPath(_path: $path) {
item {
fullName
occupation
}
}
}
Immetti quanto segue per il Variabili di query:
{"path": "/content/dam/my-project/en/alison-smith"}
Esegui la query e osserva che viene restituito il singolo risultato.
Una volta che uno sviluppatore è soddisfatto dei dati della query e dei risultati restituiti dalla query, il passaggio successivo consiste nell’archiviare o mantenere la query in AEM. La Query persistenti sono il meccanismo preferito per l’esposizione dell’API GraphQL alle applicazioni client. Una volta che una query è persistente, può essere richiesta utilizzando una richiesta GET e memorizzata nella cache ai livelli Dispatcher e CDN. Le prestazioni delle query persistenti sono molto migliori. Oltre ai vantaggi in termini di prestazioni, le query persistenti garantiscono che i dati aggiuntivi non siano accidentalmente esposti alle applicazioni client. Maggiori dettagli Le query persistenti si trovano qui.
Successivamente, persistono due semplici query, che vengono utilizzate nel capitolo successivo.
Immetti la seguente query nell'IDE GraphiQL:
query allTeams {
teamList {
items {
_path
title
shortName
description {
plaintext
}
teamMembers {
fullName
occupation
}
}
}
}
Verifica che la query funzioni.
Tocca successivo Salva con nome e immetti all-teams
come Nome query.
La query deve essere visualizzata in Query persistenti nella barra a sinistra.
Toccare quindi i puntini di sospensione … accanto alla query persistente e toccare Copia URL per copiare il percorso negli Appunti.
Apri una nuova scheda e incolla il percorso copiato nel browser:
https://$YOUR-AEMasCS-INSTANCEID$.adobeaemcloud.com/graphql/execute.json/my-project/all-teams
Dovrebbe essere simile al percorso indicato sopra. Dovresti vedere che sono stati restituiti i risultati JSON della query.
Scomposizione dell’URL precedente:
Nome | Descrizione |
---|---|
/graphql/execute.json |
Endpoint di query persistente |
/my-project |
Configurazione del progetto per /conf/my-project |
/all-teams |
Nome della query persistente |
Torna all'IDE GraphiQL e utilizza il pulsante più + per mantenere la query NEW
query personByName($name: String!) {
personList(
filter: {
fullName:{
_expressions: [{
value: $name
_operator:EQUALS
}]
}
}){
items {
_path
fullName
occupation
biographyText {
json
}
profilePicture {
... on ImageRef {
_path
_authorUrl
_publishUrl
width
height
}
}
}
}
}
Salva la query come: person-by-name
.
È necessario salvare due query persistenti:
Al momento della revisione e della verifica, pubblica il GraphQL Endpoint
& Persisted Queries
Dalla schermata iniziale AEM, passa a Strumenti > Generale > GraphQL.
Tocca la casella di controllo accanto a Endpoint progetto personale e toccare Pubblica
Dalla schermata iniziale AEM, passa a Strumenti > Generale > Editor query GraphQL
Tocca all-team query dal pannello Query persistenti e tocca Pubblica
Ripeti il passaggio precedente per person-by-name
query
Scarica il contenuto, i modelli e le query persistenti create negli ultimi tre capitoli: tutorial-solution-content.zip
Ulteriori informazioni sulle query GraphQL all'indirizzo Imparare a utilizzare GraphQL con AEM - Contenuto di esempio e query.
Congratulazioni, hai creato ed eseguito diverse query GraphQL!
Nel capitolo successivo, Creare un’app React, illustra come un’applicazione esterna può eseguire query AEM endpoint GraphQL e utilizzare queste due query persistenti. Sono inoltre state introdotte alcune informazioni di base sulla gestione degli errori durante l’esecuzione delle query GraphQL.
In, alcune versioni di AEM (6.X.X) lo strumento GraphiQL IDE deve essere installato manualmente, utilizza il istruzioni da qui.