Utiliser GraphQL avec Gatsby et Oracle Content Management

Introduction

GraphQL est un langage de requête pour les API et une exécution permettant d'exécuter ces requêtes avec vos données existantes.

Dans ce tutoriel, nous vous montrerons comment utiliser GraphQL avec Gatsby connecté à Oracle Content Management. En particulier, nous allons nous concentrer sur la page 'People' existante sur le site d'exemple de données de Gatsby minimal en interrogeant les données nécessaires à l'aide de GraphQL connecté avec le plug-in Gatsby Source GraphQL. Les autres pages ("Accueil" et "Nous contacter") utilisent actuellement une API REST connectée au module d'extension Gatsby Source OCE.

Prérequis

Avant de poursuivre ce tutoriel, nous vous recommandons de lire les informations suivantes en premier :

Pour suivre ce tutoriel, vous aurez besoin des éléments suivants :

Ce que nous construisons

Grâce au site minimal intégré à Gatsby, vous pouvez facilement extraire des images et d'autres contenus de votre référentiel Oracle Content Management.

Pour regarder ce que nous construisons, voici l'état de fin de notre tutoriel, un site minimal Gatsby de base qui consomme du contenu d'Oracle Content Management :

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

Ce tutoriel se concentrera uniquement sur la page "Personnes" de ce site.

Voici à quoi ressemblera la page Personnes à la fin de ce tutoriel :

Cette image présente la page Nous contacter pour un site minime de Gatsby.

Pour continuer, vous devez disposer d'un abonnement actif à Oracle Content Management et être connecté avec le rôle Administrateur de contenu.

Tâche 1 : Comprendre la taxonomie de la page Personnes

Le pack de ressources téléchargeables contient une ressource appelée Minimal Main GraphQL avec le slug 'minimalmaingraphql'.

La ressource Minimal Main GraphQL contient une page de type PeoplePage appelée Personnes. Il se présente comme suit :

Cette image présente la taxonomie principale GraphQL minimale.

La ressource People est de type PeoplePage et contient des sous-types de personne. Il se présente comme suit :

Cette image présente la taxonomie de la page Personnes.

Voici un exemple de ressource people (notez toutes les métadonnées dans le panneau Attributes) :

Cette image présente la taxonomie des personnes.

Tâche 2 : connexion au module d'extension GraphQL de la source Gatsby

Pour interroger ces ressources à partir d'Oracle Content Management, nous devons configurer le module d'extension Source de Gatsby GraphQL dans le fichier gatsby-config.js. Ce module d'extension doit être ajouté aux dépendances dans le fichier package.json.

Voici le code de cette configuration dans 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'adresse de l'API GraphQL est l'URL du serveur concaténée avec /content/published/api/v1.1/graphql.

Les éléments typeName et fieldName sont utilisés pour contenir le type de requête de schéma distant et le champ sous lequel il est accessible, respectivement. La dénomination ici n'est pas trop importante tant qu'elle est cohérente dans la requête.

Tâche 3 : exécution et traitement de la requête GraphQL

Vous trouverez ci-dessous une section du fichier gatsby-node.js. Elle achemine la page avec le slug 'people' vers le chemin approprié avec le composant et le contexte à l'aide de la méthode createPage dans Gatsby. Observez comment transmettre les données de page, slug et channelToken dans le contexte.

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

Une fois acheminée vers le modèle de page Personnes, la requête suivante est exécutée pour obtenir toutes les données de la page Personnes. Un slug et channelToken sont nécessaires pour accéder à l'API GraphQL pour cette page.

Pour plus d'informations sur l'interrogation des données à l'aide d'Oracle Content Management, reportez-vous à la documentation.

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
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

Notez que la requête de niveau supérieur contient ocm et que typeName sur l'image est OCM_Image. Cela doit être cohérent avec les options typeName et fieldName associées aux options fournies dans gatsby-config.js.

Le résultat renvoyé est ensuite traité pour créer le code HTML afin d'afficher la page Personnes. Pour voir la sortie de la requête, accédez à l'explorateur GraphQL, qui se trouve sur http://localhost:8000/___graphql après avoir appelé npm run develop sur le terminal. L'IDE GraphQL est également disponible à l'adresse http://your_instance/content/published/api/v1.1/graphql/explorer.

Cette image représente l'explorateur.

Conclusion

Dans ce tutoriel, nous avons ajouté une page "Personnes" au site d'exemple avec moins de Gatsby en utilisant GraphQL pour obtenir les données de cette page. Les données obtenues à partir de GraphQL avec Gatsby ont été connectées à Oracle Content Management à l'aide du module d'extension Source de Gatsby GraphQL. Les autres pages ('Accueil' et 'Nous contacter') utilisent toujours l'API REST connectée au plug-in Gatsby Source OCE. Le module d'extension OCE source Gatsby et le module d'extension GraphQL source Gatsby sont des méthodes valides pour obtenir des données à partir d'Oracle Content Management.

Pour plus d'informations sur GraphQL dans Oracle Content Management, reportez-vous à la documentation.