Utilizzare GraphQL con Gatsby e Oracle Content Management

Introduzione

GraphQL è un linguaggio di query per le API e un runtime per soddisfare tali query ai dati esistenti.

In questa esercitazione verrà illustrato come utilizzare GraphQL con Gatsby connesso a Oracle Content Management. In particolare, ci concentreremo sulla pagina 'Persone' esistente nel sito di esempio Gatsby minimal eseguendo una query sui dati necessari utilizzando GraphQL connesso al plugin Gatsby Source GraphQL. Le altre pagine ('Home' e 'Contattaci') attualmente utilizzano un'API REST connessa al plugin Gatsby Source OCE.

Prerequisiti

Prima di procedere con questa esercitazione, si consiglia di leggere le seguenti informazioni:

Per seguire questa esercitazione, sono necessari:

Cosa stiamo costruendo

Con il sito minimo creato in Gatsby, puoi facilmente recuperare le immagini e altri contenuti dal repository di Oracle Content Management.

Per dare un'occhiata a cosa stiamo costruendo, ecco lo stato finale della nostra esercitazione, un sito di base minimo di Gatsby che utilizza i contenuti di Oracle Content Management:

https://headless.mycontentdemo.com/samples/oce-gatsby-minimal-sample

Questa esercitazione si concentrerà solo sulla pagina 'Persone' di questo sito.

Questo è l'aspetto della pagina Persone alla fine di questa esercitazione:

Questa immagine mostra la pagina di contatto per un sito minimo di Gatsby.

Per continuare, sarà necessario disporre di una sottoscrizione attiva a Oracle Content Management ed eseguire il login con il ruolo Amministratore contenuto.

Task 1: Comprendere la tassonomia della pagina Persone

Il pacchetto di asset scaricabile contiene un asset denominato Minimal Main GraphQL con slug 'minimalmaingraphql'.

L'asset Minimal Main GraphQL contiene una pagina di tipo PeoplePage denominata Persone. Questo è l'aspetto:

Questa immagine mostra la tassonomia Minimal Main GraphQL.

L'asset Persone è di tipo PeoplePage e contiene sottotipi di persone. Questo è l'aspetto:

Questa immagine mostra la tassonomia della pagina Persone.

Questo è l'aspetto di un asset persone di esempio (notare tutti i metadati nel pannello Attributi):

Questa immagine mostra la tassonomia delle persone.

Task 2: connessione al plugin Gatsby Source GraphQL

Per eseguire una query su questi asset da Oracle Content Management, è necessario configurare il plugin Gatsby Source GraphQL nel file gatsby-config.js. Questo plugin deve essere aggiunto alle dipendenze nel file package.json.

Di seguito è riportato il codice per tale configurazione in gatsby-config.js.

    {
          resolve: 'gatsby-source-graphql',
          options: {
            // This type will contain remote schema Query type
            typeName: 'OCM',
            // This is the field under which it's accessible
            fieldName: 'ocm',
            // URL to query from
            url: `${process.env.SERVER_URL}/content/published/api/v1.1/graphql`,
          },
        },

L'endpoint per l'API GraphQL è l'URL del server concatenato con /content/published/api/v1.1/graphql.

Si noti che typeName e fieldName vengono utilizzati per contenere il tipo di query dello schema remoto e il campo in cui è accessibile. La denominazione qui non è troppo importante a condizione che sia coerente nella query.

Task 3: eseguire ed elaborare la query GraphQL

Di seguito è riportata una sezione del file gatsby-node.js. Instrada la pagina con slug 'people' al percorso corretto con componente e contesto utilizzando il metodo createPage in Gatsby. Notare come vengono passati i dati della pagina, slug e channelToken nel contesto.

} else if (page.slug.localeCompare('people') === 0) {
        createPage({
            path: '/people',
            component: peopleTemplate,
            context: {
                page,
                slug: 'people',
                channelToken: process.env.CHANNEL_TOKEN,
            },
        });

Dopo essere stata instradata al modello di pagina Persone, viene eseguita la query seguente per ottenere tutti i dati per la pagina Persone. Per accedere all'API GraphQL per questa pagina sono necessari un slug e channelToken.

Ulteriori informazioni su come eseguire query sui dati mediante Oracle Content Management sono reperibili nella documentazione.

query ($slug: String!, $channelToken: String!) { 
      ocm {
        getPeoplePage(
          slug: $slug
          channelToken: $channelToken
        ) {
          id
          slug
          name
          fields {
            announcement {
              id
              fields {
                type: fieldType
                heading
                body
                actions
                image {
                  ... on OCM_image {
                    id
                    name
                    fields {
                      renditions {
                        file {
                          url
                        }
                      }
                    }
                  }
                }
              }
            }
            people {
              id
              fields {
                fullname
                title
                biodata
                file {
                  metadata {
                    width
                    height
                  }
                }
                renditions {
                  name
                  format
                  file {
                    url
                    metadata {
                      height
                      width
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

Notare come la query di livello superiore contiene ocm e typeName nell'immagine è OCM_Image. Deve essere coerente con le opzioni typeName e fieldName associate a gatsby-config.js.

Il risultato restituito viene quindi elaborato per creare l'HTML per visualizzare la pagina Persone. Per visualizzare l'output della query, è possibile accedere a GraphQL Explorer, disponibile all'indirizzo http://localhost:8000/___graphql dopo aver richiamato npm run develop sul terminale. Inoltre, l'IDE GraphQL è disponibile all'indirizzo http://your_instance/content/published/api/v1.1/graphql/explorer.

Questa immagine mostra l'esploratore.

Conclusione

In questa esercitazione è stata aggiunta una pagina 'Persone' al sito di esempio Gatsby minimo utilizzando GraphQL per ottenere i dati relativi a tale pagina. I dati ottenuti da GraphQL con Gatsby sono stati connessi a Oracle Content Management utilizzando il plugin Gatsby Source GraphQL. Le altre pagine ('Home' e 'Contattaci') utilizzano ancora l'API REST connessa al plugin Gatsby Source OCE. Sia il plugin OCE di origine Gatsby che il plugin GraphQL di origine Gatsby sono metodi validi per ottenere i dati da Oracle Content Management.

Ulteriori informazioni su GraphQL in Oracle Content Management sono reperibili nella documentazione.