Esplora le API di GraphQL

L’API GraphQL dell’AEM fornisce un potente linguaggio di query per esporre i dati dei frammenti di contenuto alle applicazioni a valle. I modelli per frammenti di contenuto definiscono lo schema di dati utilizzato dai frammenti di contenuto. Ogni volta che un modello per frammenti di contenuto viene creato o aggiornato, lo schema viene tradotto e aggiunto al "grafico" che costituisce l’API di GraphQL.

In questo capitolo, esploreremo alcune query GraphQL comuni per raccogliere contenuti utilizzando un IDE denominato GraphiQL. L’IDE GraphiQL consente di testare e perfezionare rapidamente le query e i dati restituiti. Consente inoltre di accedere facilmente alla documentazione, per scoprire e comprendere facilmente i metodi disponibili.

Prerequisiti

Si tratta di un tutorial in più parti in cui si presume che i passaggi descritti in Creazione di frammenti di contenuto sono state completate.

Obiettivi

  • Scopri come utilizzare lo strumento GraphiQL per creare una query utilizzando la sintassi GraphQL.
  • Scopri come eseguire query su un elenco di frammenti di contenuto e un singolo frammento di contenuto.
  • Scopri come filtrare e richiedere attributi di dati specifici.
  • Scopri come unire una query di più modelli per frammenti di contenuto
  • Scopri come rendere persistente la query GraphQL.

Abilitare endpoint GraphQL

È necessario configurare un endpoint GraphQL per abilitare le query API GraphQL per i frammenti di contenuto.

  1. Dalla schermata iniziale dell’AEM, passa a Strumenti > Generale > GraphQL.

    Passa all’endpoint GraphQL

  2. Tocca Crea nell’angolo in alto a destra, nella finestra di dialogo risultante inserisci i seguenti valori:

    • Nome*: Endpoint progetto personale.
    • Utilizza lo schema GraphQL fornito da … *: Il mio progetto

    Crea endpoint GraphQL

    Tocca Crea per salvare l’endpoint.

    Gli endpoint di GraphQL creati in base alla configurazione di un progetto abilitano solo le query sui modelli appartenenti a tale progetto. In questo caso, le uniche query per Persona e Team possono essere utilizzati.

    NOTA

    È inoltre possibile creare un endpoint globale per abilitare le query sui modelli in più configurazioni. Questo deve essere utilizzato con cautela in quanto può aprire l’ambiente a ulteriori vulnerabilità di sicurezza e aumentare la complessità complessiva nella gestione dell’AEM.

  3. Ora dovrebbe essere abilitato un endpoint GraphQL nel tuo ambiente.

    Endpoint graphql abilitati

Utilizzo dell’IDE GraphiQL

Il GraphiQL consente agli sviluppatori di creare e testare query sui contenuti nell’ambiente AEM corrente. Lo strumento GraphiQL consente inoltre agli utenti di: persistere o salvare query che devono essere utilizzate dalle applicazioni client in un'impostazione di produzione.

Quindi, esplora la potenza dell’API GraphQL dell’AEM utilizzando l’IDE GraphiQL integrato.

  1. Dalla schermata iniziale dell’AEM, passa a Strumenti > Generale > Editor query di GraphQL.

    Passare all’IDE GraphiQL

    NOTA

    In, le versioni precedenti di AEM e IDE GraphiQL potrebbero non essere integrate. Può essere installato manualmente seguendo queste istruzioni istruzioni.

  2. Nell’angolo in alto a destra, accertati che Endpoint sia impostato su Endpoint progetto personale.

    Imposta endpoint GraphQL

In questo modo tutte le query verranno estese ai modelli creati nel Il mio progetto progetto.

Eseguire una query su un elenco di frammenti di contenuto

Un requisito comune consiste nell’eseguire query per più frammenti di contenuto.

  1. Incolla la seguente query nel pannello principale (sostituendo l’elenco dei commenti):

    query allTeams {
  teamList {
    items {
      _path
      title
    }
  }
}

  2. Premere il tasto Play nel menu principale per eseguire la query. Dovresti visualizzare i risultati dei frammenti di contenuto del capitolo precedente:

    Risultati elenco persone

  3. Posiziona il cursore sotto il title testo e immetti CTRL+spazio per attivare suggerimenti sul codice. Aggiungi shortname e description alla query.

    Query di aggiornamento con hit di codice

  4. Eseguire nuovamente la query premendo il tasto Play e dovresti vedere che i risultati includono le proprietà aggiuntive di shortname e description.

    risultati con nome breve e descrizione

    Il shortname è una proprietà semplice e description è un campo di testo su più righe e l’API GraphQL consente di scegliere vari formati per i risultati, come html, markdown, json, o plaintext.

Query per frammenti nidificati

Successivamente, esperimento con query è il recupero di frammenti nidificati, ricorda che il Team il modello fa riferimento al Persona modello.

  1. Aggiorna la query per includere teamMembers proprietà. Ricorda che si tratta di un Riferimento frammento al modello della 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 potente funzione dell’API GraphQL dell’AEM. In questo semplice esempio, la nidificazione è profonda solo due livelli. Tuttavia, è possibile nidificare ulteriormente i frammenti. Ad esempio, se è stato Indirizzo modello associato a un Persona sarebbe possibile restituire dati da tutti e tre i modelli in una singola query.

Filtrare un elenco di frammenti di contenuto

Vediamo ora come è possibile filtrare i risultati in un sottoinsieme di frammenti di contenuto in base a un valore di proprietà.

  1. 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 precedente esegue una ricerca in tutti i frammenti Persona nel sistema. Il filtro aggiunto all’inizio della query esegue un confronto sulla name e la stringa della variabile $name.

  2. In Variabili di query immetti quanto segue:

    {"name": "John Doe"}

  3. Esegui la query. È previsto che solo Persone Il frammento di contenuto viene restituito con il valore John Doe.

    Utilizzare le variabili di query per filtrare

    Esistono molte altre opzioni per filtrare e creare query complesse. Consulta Imparare a utilizzare GraphQL con AEM: contenuto di esempio e query.

  4. Migliora la query precedente 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

        }
      }
    }
  }
}

    Il profilePicture è un riferimento di contenuto e deve essere un’immagine, pertanto è incorporato ImageRef viene utilizzato l'oggetto. Questo ci consente di richiedere dati aggiuntivi sull’immagine da usare come riferimento, come width e height.

Eseguire una query su un singolo frammento di contenuto

È inoltre possibile eseguire query dirette su un singolo frammento di contenuto. Il contenuto dell’AEM viene archiviato in modo gerarchico e l’identificatore univoco di un frammento si basa sul percorso del frammento.

  1. Immetti la seguente query nell’editor GraphiQL:

    query personByPath($path: String!) {
    personByPath(_path: $path) {
        item {
        fullName
        occupation
        }
    }
}

  2. Immetti quanto segue per Variabili di query:

    {"path": "/content/dam/my-project/en/alison-smith"}

  3. Esegui la query e osserva che viene restituito il singolo risultato.

Query persistenti

Quando uno sviluppatore è soddisfatto della query e dei dati dei risultati restituiti dalla query, il passaggio successivo consiste nel memorizzare o mantenere la query nell’AEM. Il Query persistenti sono il meccanismo preferito per esporre l’API GraphQL alle applicazioni client. Una volta che una query è stata resa 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 vengano accidentalmente esposti alle applicazioni client. Ulteriori dettagli su Le query persistenti si trovano qui.

Quindi, affinché persistano due query semplici, queste vengono utilizzate nel capitolo successivo.

  1. Immetti la seguente query nell’IDE GraphiQL:

    query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

    Verifica che la query funzioni.

  2. Tocco successivo Salva con nome e immetti all-teams come Nome query.

    La query deve essere visualizzata in Query persistenti nella barra a sinistra.

    Query persistente di tutti i team

  3. Tocca quindi i puntini di sospensione … accanto alla query persistente e tocca Copia URL per copiare il percorso negli Appunti.

    Copia URL query persistente

  4. Apri una nuova scheda e incolla il percorso copiato nel browser:

    https://$YOUR-AEMasCS-INSTANCEID$.adobeaemcloud.com/graphql/execute.json/my-project/all-teams

    Deve essere simile al percorso precedente. Dovresti vedere che sono stati restituiti i risultati JSON della query.

    Suddivisione 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

  5. Torna all’IDE GraphiQL e utilizza il pulsante più + per rendere persistente 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
        }
      }
    }
  }
}

  6. Salva la query con nome: person-by-name.

  7. Dovresti salvare due query persistenti:

    Query persistenti finali

Pubblicare endpoint GraphQL e query persistenti

In seguito a revisione e verifica, pubblica GraphQL Endpoint E Persisted Queries

  1. Dalla schermata iniziale dell’AEM, passa a Strumenti > Generale > GraphQL.

  2. Tocca la casella di controllo accanto a Endpoint progetto personale e tocca Pubblica

    Pubblica endpoint GraphQL

  3. Dalla schermata iniziale dell’AEM, passa a Strumenti > Generale > Editor query di GraphQL

  4. Tocca il all-teams query dal pannello Query persistenti e tocca Pubblica

    Pubblicare query persistenti

  5. Ripeti il passaggio precedente per person-by-name query

File di soluzione

Scarica i contenuti, i modelli e le query persistenti creati negli ultimi tre capitoli: basic-tutorial-solution.content.zip

Risorse aggiuntive

Ulteriori informazioni sulle query GraphQL sono disponibili all’indirizzo Imparare a utilizzare GraphQL con AEM: contenuto di esempio e query.

Congratulazioni.

Congratulazioni, hai creato ed eseguito diverse query GraphQL.

Passaggi successivi

Nel prossimo capitolo, Creare un’app React, scopri come un’applicazione esterna può eseguire query sugli endpoint AEM GraphQL e utilizzare queste due query persistenti. Vengono inoltre presentate alcune informazioni di base sulla gestione degli errori durante l’esecuzione di query GraphQL.

Installare lo strumento GraphiQL (facoltativo)

In, alcune versioni di AEM (6.X.X) lo strumento IDE GraphiQL deve essere installato manualmente, utilizza istruzioni da qui.

In questa pagina