Usar GraphQL com Gatsby e Oracle Content Management

Introdução

GraphQL é uma linguagem de consulta para APIs e um runtime para atendimento dessas consultas com seus dados existentes.

Neste tutorial, vamos mostrar como usar GraphQL com o Gatsby conectado ao Oracle Content Management. Em particular, focaremos na página 'Pessoas' existente no site de amostra Gatsby minimal consultando os dados necessários usando GraphQL conectado ao plug-in Gatsby Source GraphQL. No momento, as outras páginas ('Início' e 'Fale Conosco') estão usando uma API REST conectada com o plug-in Gatsby Source OCE.

Pré-requisitos

Antes de prosseguir com este tutorial, recomendamos que você leia as seguintes informações primeiro:

Para seguir este tutorial, você precisará:

O que estamos construindo

Com o site mínimo criado no Gatsby, você pode recuperar facilmente imagens e outros conteúdos do seu repositório do Oracle Content Management.

Para dar uma olhada no que estamos criando, aqui está o estado final de nosso tutorial, um site básico do Gatsby que consome conteúdo do Oracle Content Management:

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

Este tutorial focará somente na página 'Pessoas' deste site.

Esta é a aparência da página Pessoas no final deste tutorial:

Esta imagem mostra a página de contato conosco para um site mínimo Gatsby.

Para continuar, será necessário ter uma inscrição ativa no Oracle Content Management e fazer log-in com a função Administrador de Conteúdo.

Tarefa 1: Compreender a Taxonomia da Página Pessoas

O pacote de ativos para download contém um ativo chamado Mínimo Principal GraphQL com a barra 'minimalmaingraphql'.

O ativo Mínimo Principal GraphQL contém uma página do tipo PeoplePage chamada Pessoas. Parecerá com o seguinte:

Esta imagem mostra a taxonomia Mínima Principal GraphQL.

O ativo Pessoas é do tipo PeoplePage e contém subtipos de pessoas. Parecerá com o seguinte:

Esta imagem mostra a taxonomia da página Pessoas.

É assim que um exemplo de ativo de pessoas se parece (observe todos os metadados no painel Atributos):

Esta imagem mostra a taxonomia das pessoas.

Tarefa 2: Conectar-se ao plug-in GraphQL do Gatsby Source

Para consultar esses ativos no Oracle Content Management, precisamos configurar o plug-in Gatsby Source GraphQL no arquivo gatsby-config.js. Esse plug-in deve ser adicionado às dependências no arquivo package.json.

Veja a seguir o código dessa configuração em 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`,
          },
        },

O ponto final da API GraphQL é o URL do servidor concatenado com /content/published/api/v1.1/graphql.

Observe que typeName e fieldName são usados para conter o tipo de consulta de esquema remoto e o campo no qual ele está acessível, respectivamente. A nomenclatura aqui não é muito importante, desde que seja consistente na consulta.

Tarefa 3: Executar e Processar a consulta GraphQL

Veja a seguir uma seção do arquivo gatsby-node.js. Ele roteia a página com 'pessoas' de slug para o caminho adequado com o componente e o contexto usando o método createPage em Gatsby. Observe como passamos nos dados da página, no slug e no channelToken no contexto.

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

Depois de rotear para o modelo da página Pessoas, a consulta a seguir é executada para obter todos os dados da página Pessoas. Um slug e channelToken são necessários para acessar a API GraphQL para esta página.

Mais informações sobre como consultar dados usando o Oracle Content Management podem ser encontradas na documentação.

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

Observe como a consulta de nível superior tem ocm e o typeName na imagem é OCM_Image. Ele deve ser consistente com o typeName e o fieldName associados às opções fornecidas em gatsby-config.js.

O resultado retornado é processado para criar o HTML para exibir a página Pessoas. Para ver a saída da consulta, você pode ir para o explorador GraphQL, que pode ser encontrado em http://localhost:8000/___graphql após chamar npm run develop no terminal. Além disso, o IDE GraphQL está disponível em http://your_instance/content/published/api/v1.1/graphql/explorer.

Esta imagem mostra o explorador.

Conclusão

Neste tutorial, adicionamos uma página 'Pessoas' ao site mínimo de amostra Gatsby usando GraphQL para obter os dados dessa página. Os dados obtidos de GraphQL com o Gatsby foram conectados ao Oracle Content Management usando o plug-in Gatsby Source GraphQL. As outras páginas ('Início' e 'Fale Conosco') ainda usam a API REST conectada com o plug-in Gatsby Source OCE. O plug-in do Gatsby Source OCE e o plug-in do Gatsby Source GraphQL são formas válidas de obter dados do Oracle Content Management.

Informações adicionais sobre GraphQL no Oracle Content Management podem ser encontradas na documentação.