Eseguire query su AEM utilizzando GraphQL da un’app esterna

In questo capitolo, esploriamo come le API GraphQL di AEM possono essere utilizzate per guidare l’esperienza in un’applicazione esterna.

Questa esercitazione utilizza una semplice app React per eseguire query e visualizzare il contenuto avventura esposto dalle API GraphQL di AEM. L'utilizzo di React è in gran parte poco importante e l'applicazione esterna consueta potrebbe essere scritta in qualsiasi struttura per qualsiasi piattaforma.

Prerequisiti

Si tratta di un tutorial in più parti e si presume che i passaggi descritti nelle parti precedenti siano stati completati.

Le schermate IDE in questo capitolo provengono da Visual Studio Code

Facoltativamente, installa un'estensione del browser come Rete GraphQL per essere in grado di visualizzare ulteriori dettagli su una query GraphQL.

Obiettivi

In questo capitolo impareremo come:

  • Avviare e comprendere le funzionalità dell’app React di esempio
  • Esplorare come vengono effettuate le chiamate dall’app esterna ai punti finali GraphQL di AEM
  • Definire una query GraphQL per filtrare un elenco di frammenti di contenuto di avventure per attività
  • Aggiorna l’app React per fornire controlli per filtrare tramite GraphQL, l’elenco delle avventure per attività

Avvia l'app React

Poiché questo capitolo si concentra sullo sviluppo di un client per l’utilizzo di frammenti di contenuto su GraphQL, il codice sorgente dell’app React di esempio WKND GraphQL deve essere scaricato e configurato sul computer locale e l’ SDK AEM è in esecuzione come servizio di authoring con il sito WKND di esempio installato.

L'avvio dell'app React è descritto più dettagliatamente nel capitolo Configurazione rapida , tuttavia è possibile seguire le istruzioni abbreviate:

  1. Se non lo hai già fatto, clona l’app WKND GraphQL React di esempio da Github.com

    $ git clone --branch tutorial/react git@github.com:adobe/aem-guides-wknd-graphql.git
    
  2. Apri l’app React GraphQL WKND nell’IDE

    React App in VSCode

  3. Dalla riga di comando, passa alla cartella react-app

  4. Avvia l'app React GraphQL WKND, eseguendo il seguente comando dalla directory principale del progetto (la cartella react-app )

    $ cd aem-guides-wknd-graphql/react-app
    $ npm start
    
  5. Rivedi l’app all’indirizzo http://localhost:3000/. L’app React di esempio ha due parti principali:

    • L’esperienza Home funge da indice delle avventure WKND, eseguendo una query sui frammenti di contenuto Avventura in AEM utilizzando GraphQL. In questo capitolo, modificheremo questa visualizzazione per supportare il filtraggio delle avventure per attività.

      App React GraphQL WKND - Home experience

    • L'esperienza dei dettagli dell'avventura utilizza GraphQL per eseguire query sul frammento di contenuto specifico Avventura e visualizza più punti di dati.

      App React GraphQL WKND - Esperienza di dettaglio

  6. Utilizza gli strumenti di sviluppo del browser e un'estensione del browser come Rete GraphQL per controllare le query GraphQL inviate ad AEM e le relative risposte JSON. Questo approccio può essere utilizzato per monitorare le richieste e le risposte GraphQL in modo che siano formulate correttamente e le risposte siano come previsto.

    Query grezza per adventureList

    Query GraphQL inviata ad AEM dall’app React

    Risposta JSON GraphQL

    Risposta JSON da AEM all’app React

    Le query e la risposta devono corrispondere a quanto visualizzato nell'IDE GraphiQL.

    NOTA

    Durante lo sviluppo, l’app React è configurata per inviare ad AEM richieste HTTP tramite il server di sviluppo del webpack. L’app React sta effettuando richieste a http://localhost:3000 che le proxy al servizio AEM Author in esecuzione su http://localhost:4502. Per ulteriori informazioni, consulta il file src/setupProxy.js e env.development .

    In scenari non di sviluppo, l’app React verrebbe configurata direttamente per effettuare richieste ad AEM.

Esplora il codice GraphQL dell'app

  1. Nell’IDE, apri il file src/api/useGraphQL.js.

    Si tratta di un Gancio di effetti di reazione che ascolta le modifiche apportate a query dell’app e, in seguito a modifica, invia una richiesta HTTP POST al punto finale AEM GraphQL e restituisce la risposta JSON all’app.

    Ogni volta che l’app React deve creare una query GraphQL, richiama questo hook personalizzato useGraphQL(query), passando GraphQL per l’invio ad AEM.

    Questo gancio utilizza il semplice modulo fetch per effettuare la richiesta HTTP POST GraphQL, ma altri moduli come Apollo GraphQL client possono essere utilizzati in modo simile.

  2. Apri src/components/Adventures.js nell'IDE, responsabile dell'elenco delle avventure della visualizzazione principale, e controlla l'invocazione del gancio useGraphQL.

    Questo codice imposta il valore predefinito query come allAdventuresQuery come definito in basso in questo file.

    const [query, setQuery] = useState(allAdventuresQuery);
    

    … e ogni volta che la variabile query cambia, viene richiamato il gancio useGraphQL, che a sua volta esegue la query GraphQL su AEM, restituendo il JSON alla variabile data, che viene quindi utilizzata per eseguire il rendering dell’elenco delle avventure.

    const { data, errorMessage } = useGraphQL(query);
    

    La allAdventuresQuery è una query GraphQL costante definita nel file, che esegue query su tutti i frammenti di contenuto avventura, senza alcun filtro, e restituisce solo i punti dati necessari per eseguire il rendering della visualizzazione a casa.

    const allAdventuresQuery = `
    {
        adventureList {
          items {
            _path
            adventureTitle
            adventurePrice
            adventureTripLength
            adventurePrimaryImage {
            ... on ImageRef {
                _path
                mimeType
                width
                height
              }
            }
          }
      }
    }
    `;
    
  3. Apri src/components/AdventureDetail.js, il componente React responsabile della visualizzazione dell’esperienza dei dettagli dell’avventura. Questa visualizzazione richiede un frammento di contenuto specifico, utilizzando il suo percorso JCR come ID univoco, ed esegue il rendering dei dettagli forniti.

    Analogamente a Adventures.js, il useGraphQL React Hook personalizzato viene riutilizzato per eseguire la query GraphQL su AEM.

    Il percorso del frammento di contenuto viene raccolto dalla parte superiore del componente props da utilizzare per specificare il frammento di contenuto per il quale eseguire la query.

    const contentFragmentPath = props.location.pathname.substring(props.match.url.length);
    

    … e la query con parametri GraphQL viene costruita utilizzando la funzione adventureDetailQuery(..) e passata a useGraphQL(query) che esegue la query GraphQL su AEM e restituisce i risultati alla variabile data .

    const { data, errorMessage } = useGraphQL(adventureDetailQuery(contentFragmentPath));
    

    La funzione adventureDetailQuery(..) racchiude semplicemente una query GraphQL di filtro, che utilizza la sintassi <modelName>ByPath di AEM per eseguire query su un singolo frammento di contenuto identificato dal suo percorso JCR, e restituisce tutti i punti dati specificati necessari per eseguire il rendering dei dettagli dell’avventura.

    function adventureDetailQuery(_path) {
    return `{
        adventureByPath (_path: "${_path}") {
          item {
            _path
            adventureTitle
            adventureActivity
            adventureType
            adventurePrice
            adventureTripLength
            adventureGroupSize
            adventureDifficulty
            adventurePrice
            adventurePrimaryImage {
                ... on ImageRef {
                _path
                mimeType
                width
                height
                }
            }
            adventureDescription {
                html
            }
            adventureItinerary {
                html
            }
          }
        }
    }
    `;
    }
    

Creare una query GraphQL con parametri

Quindi, modifichiamo l’app React per eseguire query GraphQL con parametri che filtrano la visualizzazione a casa in base all’attività delle avventure.

  1. Nell’IDE, apri il file : src/components/Adventures.js. Questo file rappresenta il componente Avventure dell'esperienza domestica, che richiede e visualizza le schede Avventures.

  2. Ispeziona la funzione filterQuery(activity), che non è utilizzata, ma è stata preparata per formulare una query GraphQL che filtra le avventure di activity.

    Si noti che il parametro activity viene inserito nella query GraphQL come parte di un filter nel campo adventureActivity, richiedendo che il valore di quel campo corrisponda al valore del parametro.

    function filterQuery(activity) {
        return `
            {
            adventures (filter: {
                adventureActivity: {
                _expressions: [
                    {
                    value: "${activity}"
                    }
                  ]
                }
            }){
                items {
                _path
                adventureTitle
                adventurePrice
                adventureTripLength
                adventurePrimaryImage {
                ... on ImageRef {
                    _path
                    mimeType
                    width
                    height
                }
                }
              }
          }
        }
        `;
    }
    
  3. Aggiorna l’istruzione return del componente React Adventures per aggiungere pulsanti che richiamano il nuovo parametro filterQuery(activity) per fornire le avventure da elencare.

    function Adventures() {
        ...
        return (
            <div className="adventures">
    
            {/* Add these three new buttons that set the GraphQL query accordingly */}
    
            {/* The first button uses the default `allAdventuresQuery` */}
            <button onClick={() => setQuery(allAdventuresQuery)}>All</button>
    
            {/* The 2nd and 3rd button use the `filterQuery(..)` to filter by activity */}
            <button onClick={() => setQuery(filterQuery('Camping'))}>Camping</button>
            <button onClick={() => setQuery(filterQuery('Surfing'))}>Surfing</button>
    
            <ul className="adventure-items">
            ...
        )
    }
    
  4. Salva le modifiche e ricarica l’app React nel browser web. I tre nuovi pulsanti vengono visualizzati nella parte superiore e facendo clic su di essi, AEM for Adventure Content Fragments viene automaticamente interrogato con l’attività corrispondente.

    Filtrare le avventure per attività

  5. Prova ad aggiungere altri pulsanti di filtro per le attività: Rock Climbing, Cycling e Skiing

Gestire gli errori GraphQL

GraphQL è fortemente tipizzato e può quindi restituire utili messaggi di errore se la query non è valida. Quindi, simuliamo una query errata per visualizzare il messaggio di errore restituito.

  1. Riapri il file src/api/useGraphQL.js. Per visualizzare la gestione dell’errore, controlla il seguente frammento:

    //useGraphQL.js
    .then(({data, errors}) => {
            //If there are errors in the response set the error message
            if(errors) {
                setErrors(mapErrors(errors));
            }
            //Otherwise if data in the response set the data as the results
            if(data) {
                setData(data);
            }
        })
        .catch((error) => {
            setErrors(error);
        });
    

    La risposta viene controllata per verificare se include un oggetto errors. L'oggetto errors viene inviato da AEM in caso di problemi con la query GraphQL, ad esempio un campo non definito basato sullo schema. Se non è presente alcun oggetto errors, viene impostato e restituito data.

    Il window.fetch include un'istruzione .catch a catch tutti gli errori comuni, come una richiesta HTTP non valida o se non è possibile effettuare la connessione al server.

  2. Aprire il file src/components/Adventures.js.

  3. Modifica allAdventuresQuery per includere una proprietà non valida adventurePetPolicy:

    /**
     * Query for all Adventures
     * adventurePetPolicy has been added beneath items
    */
    const allAdventuresQuery = `
    {
        adventureList {
          items {
            adventurePetPolicy
            _path
            adventureTitle
            adventurePrice
            adventureTripLength
            adventurePrimaryImage {
            ... on ImageRef {
                _path
                mimeType
                width
                height
            }
            }
          }
        }
    }
    `;
    

    Sappiamo che adventurePetPolicy non fa parte del modello Avventura, quindi questo dovrebbe attivare un errore.

  4. Salva le modifiche e torna al browser. Dovresti visualizzare un messaggio di errore simile al seguente:

    Errore di proprietà non valido

    L'API GraphQL rileva che adventurePetPolicy non è definito in AdventureModel e restituisce un messaggio di errore appropriato.

  5. Ispeziona la risposta da AEM utilizzando gli strumenti di sviluppo del browser per visualizzare l'oggetto JSON errors:

    Errore oggetto JSON

    L'oggetto errors è dettagliato e include informazioni sulla posizione della query non valida e sulla classificazione dell'errore.

  6. Torna a Adventures.js e ripristina la modifica della query per ripristinare lo stato corretto dell’app.

Congratulazioni!

Congratulazioni! Hai esplorato con successo il codice dell’app WKND GraphQL React di esempio e l’hai aggiornato con l’utilizzo di query GraphQL con parametri che filtrano per elencare le avventure per attività! Hai anche la possibilità di esplorare alcune funzioni di base per la gestione degli errori.

Passaggi successivi

Nel capitolo successivo, Modellazione dati avanzata con Riferimenti frammento verrà illustrato come utilizzare la funzione Riferimento frammento per creare una relazione tra due diversi frammenti di contenuto. Inoltre verrà illustrato come modificare una query GraphQL per includere un campo da un modello di riferimento.

In questa pagina

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now