API GraphQL do AEM para uso com Fragmentos de conteúdo

Saiba como usar os Fragmentos de conteúdo no Adobe Experience Manager (AEM) as a Cloud Service com a API GraphQL do AEM, para entrega de conteúdo headless.

A API GraphQL do AEM as a Cloud Service utilizada com Fragmentos de conteúdo é baseada na API GraphQL padrão de código aberto.

Usar a API GraphQL no AEM permite a entrega eficiente dos Fragmentos de conteúdo aos clientes JavaScript em implementações CMS headless:

• Evitando solicitações de API iterativas como com REST,
• Garantindo que a entrega se limite aos requisitos específicos,
• Permitindo a entrega em massa exatamente daquilo que é necessário para a renderização, como resposta a uma única consulta de API.

A API GraphQL

O GraphQL é:

• "…um idioma de consulta para APIs e um tempo de execução para realizar essas consultas com seus dados existentes. O GraphQL fornece uma descrição completa e compreensível dos dados em sua API, concede aos clientes nada além do poder de solicitar exatamente o que precisam, facilita a evolução das APIs ao longo do tempo e habilita ferramentas avançadas de desenvolvedor.".

  Consulte GraphQL.org

• "…uma especificação aberta para uma camada de API flexível. Coloque o GraphQL sobre seus back-end existentes para criar produtos mais rápido do que nunca…".

  Consulte Explorar GraphQL.

• "…uma linguagem de consulta de dados e especificação desenvolvidas internamente pelo Facebook em 2012, antes de serem disponibilizadas publicamente em 2015. Ele oferece uma alternativa às arquiteturas baseadas em REST, com o objetivo de aumentar a produtividade do desenvolvedor e minimizar as quantidades de dados transferidos. O GraphQL é usado na produção por centenas de organizações de todos os tamanhos…"

  Consulte Fundação GraphQL.

Para obter mais informações sobre a API GraphQL, consulte as seguintes seções (entre muitos outros recursos):

• Em graphql.org:

  • Introdução ao GraphQL

  • A especificação GraphQL

• Em graphql.com:

  • Guias

  • Tutoriais

  • Estudos de caso

A implementação do GraphQL para AEM é baseada na Biblioteca GraphQL Java padrão. Consulte:

• graphQL.org - Java

• Java GraphQL no GitHub

Terminologia de GraphQL

O GraphQL usa o seguinte:

• Consultas

• Esquemas e Tipos:

  • Os esquemas são gerados pelo AEM com base nos modelos de fragmento de conteúdo.
  • Usando seus esquemas, o GraphQL apresenta os tipos e as operações permitidas no GraphQL para implementação no AEM.

• Campos

• Endpoint de GraphQL

  • O caminho no AEM que responde a consultas de GraphQL e fornece acesso aos esquemas de GraphQL.

  • Consulte Habilitação do endpoint de GraphQL para obter mais detalhes.

Consulte a Introdução ao GraphQL (GraphQL.org) para obter detalhes abrangentes, incluindo as Práticas recomendadas.

Tipos de consulta de GraphQL

Com o GraphQL, é possível executar consultas para retornar:

• Uma entrada única

• Uma lista de entradas

Também é possível executar:

• Consultas persistentes, que são armazenadas em cache

Práticas recomendadas de consulta GraphQL (Dispatcher)

O Consultas Persistentes são o método recomendado como:

• são armazenadas em cache
• são gerenciados centralmente AEM as a Cloud Service

As consultas diretas e/ou POST não são recomendadas, pois não são armazenadas em cache, portanto, em uma instância padrão, o Dispatcher é configurado para bloquear essas consultas.

IDE GraphiQL

É possível testar e depurar consultas de GraphQL usando o IDE GraphiQL.

Casos de uso para ambientes de Autor e Publicação

Os casos de uso podem depender do tipo de ambiente do AEM as a Cloud Service:

• Ambiente de publicação; usado para:

  • Consultar dados para o aplicativo JS (caso de uso padrão)

• Ambiente de autor; usado para:

  • Consultar dados para “fins de gerenciamento de conteúdo”:
    • Atualmente, o GraphQL no AEM as a Cloud Service é uma API somente de leitura.
    • A API REST pode ser usada para operações de CR(u)D.

Permissões

As permissões são as necessárias para acessar o Assets.

Geração de esquemas

O GraphQL é uma API altamente tipificada, o que significa que os dados devem ser estruturados e organizados claramente por tipo.

A especificação GraphQL fornece uma série de diretrizes sobre como criar uma API robusta para interrogar dados em uma determinada instância. Para fazer isso, um cliente precisa buscar o Esquema, que contém todos os tipos necessários para uma consulta.

Para fragmentos de conteúdo, os esquemas de GraphQL (estrutura e tipos) são baseados em modelos de fragmento de conteúdo habilitados e seus tipos de dados.

Por exemplo, se um usuário criou um modelo de fragmento de conteúdo chamado Article, então o AEM irá gerar o objeto article, que é do tipo ArticleModel. Os campos desse tipo correspondem aos campos e tipos de dados definidos no modelo.

1. Um modelo de fragmento de conteúdo:

   

2. O esquema de GraphQL correspondente (saída da documentação automática do GraphiQL):
   

   Isso mostra que o tipo gerado ArticleModel contém vários campos.

   • Três deles foram controlados pelo usuário: author, main e referencearticle.

   • Os outros campos foram adicionados automaticamente pelo AEM e representam métodos úteis para fornecer informações sobre um determinado fragmento de conteúdo; neste exemplo, _path, _metadata e _variations. Esses campos auxiliares estão marcados com um _ precedente, para distinguir entre o que foi definido pelo usuário e o que foi gerado automaticamente.

3. Depois que um usuário cria um fragmento de conteúdo com base no modelo de Artigo, ele pode ser interrogado por meio do GraphQL. Para obter exemplos, consulte Exemplos de consulta (baseado em uma amostra da estrutura do fragmento de conteúdo para uso com GraphQL).

No GraphQL para AEM, o esquema é flexível. Isso significa que ele é gerado automaticamente toda vez que um modelo de fragmento de conteúdo é criado, atualizado ou excluído. Os caches do esquema de dados também são atualizados quando você atualiza um modelo de fragmento de conteúdo.

O serviço GraphQL do Sites acompanha (em segundo plano) quaisquer modificações feitas em um modelo de fragmento de conteúdo. Quando as atualizações são detectadas, somente essa parte do esquema é gerada novamente. Essa otimização economiza tempo e oferece estabilidade.

Por exemplo, se você:

1. Instalar um pacote contendo Content-Fragment-Model-1 e Content-Fragment-Model-2:

   1. Os tipos de GraphQL para Model-1 e Model-2 serão gerados.

2. Em seguida, o Content-Fragment-Model-2 é modificado:

   1. Somente o tipo de GraphQL para Model-2 será atualizado.

   2. Já o Model-1 permanecerá o mesmo.

O esquema é distribuído por meio do mesmo endpoint das consultas de GraphQL, com o cliente lidando com o fato de que o esquema é chamado com a extensão GQLschema. Por exemplo, executar uma simples solicitação GET em /content/cq:graphql/global/endpoint.GQLschema resultará na saída do esquema com o tipo do conteúdo: text/x-graphql-schema;charset=iso-8859-1.

Geração de esquema - Modelos não publicados

Quando os fragmentos de conteúdo são aninhados, pode acontecer que um modelo de fragmento de conteúdo principal seja publicado, mas um modelo referenciado não.

Quando isso acontece, o AEM gera um esquema incompleto do modelo de fragmento de conteúdo principal. Isso significa que a referência do fragmento, que depende do modelo não publicado, é removida do esquema.

Campos

Dentro do esquema há campos individuais de duas categorias básicas:

• Campos gerados.

  Uma seleção de Tipos de campos é usada para criar campos com base em como você configura o modelo de fragmento de conteúdo. Os nomes de campo são retirados do campo Nome da propriedade do Tipo de dados.

  • A propriedade Renderizar como também precisa ser considerada, pois os usuários podem configurar determinados tipos de dados; por exemplo, como um texto de linha única ou como um multicampo.

• O GraphQL do AEM também gera vários campos auxiliares.

  Eles são usados para identificar um fragmento de conteúdo ou obter mais informações sobre ele.

Tipos de campos

O GraphQL do AEM oferece suporte a uma lista de tipos. Todos os tipos de dados do modelo de fragmento de conteúdo compatíveis e os tipos de GraphQL correspondentes são representados:

Campos auxiliares

Além dos tipos de dados para campos gerados pelo usuário, o GraphQL para AEM também gera vários campos auxiliares para ajudar a identificar um Fragmento de conteúdo ou fornecer informações adicionais sobre um Fragmento de conteúdo.

Caminho

O campo de caminho é usado como um identificador no GraphQL. Ele representa o caminho do ativo Fragmento de conteúdo dentro do repositório do AEM. Escolhemos isso como o identificador de um fragmento de conteúdo, pois ele:

• é exclusivo dentro do AEM,
• pode ser buscado facilmente.

O código a seguir exibirá os caminhos de todos os Fragmentos de conteúdo que foram criados com base no Modelo de fragmento de conteúdo Person.

{
  personList {
    items {
      _path
    }
  }
}

Para recuperar um único Fragmento de conteúdo de um tipo específico, também é necessário determinar seu caminho primeiro. por exemplo:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      firstName
      name
    }
  }
}

Consulte Exemplo de consulta - um único fragmento específico de cidade.

Metadados

Por meio do GraphQL, o AEM também expõe os metadados de um Fragmento de conteúdo. Metadados são as informações que descrevem um fragmento de conteúdo, como o título de um fragmento de conteúdo, o caminho da miniatura, a descrição de um Fragmento de conteúdo, a data de criação, dentre outros.

Como os metadados são gerados por meio do Editor de esquemas e, como tal, não têm uma estrutura específica, o GraphQL tipo TypedMetaData foi implementado para expor os metadados de um Fragmento de conteúdo. TypedMetaData expõe as informações agrupadas pelos seguintes tipos escalares:

Cada tipo escalar representa um único par de nome-valor ou uma matriz de pares de nome-valor, em que o valor desse par é do tipo em que foi agrupado.

Por exemplo, se você quiser recuperar o título de um Fragmento de conteúdo, sabemos que essa é uma propriedade de String; portanto, consultaríamos todos os metadados de String:

Para consultar metadados:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

É possível exibir todos os tipos de metadados GraphQL, se você exibir o esquema GraphQL gerado. Todos os tipos de modelo têm o mesmo TypedMetaData.

Consulte Exemplo de consulta para metadados - listar os metadados para prêmios denominados GB.

Variações

O campo _variations foi implementado para simplificar a consulta das variações que um Fragmento de conteúdo possui. Por exemplo:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _variations
    }
  }
}

Consulte Exemplo de consulta - todas as cidades com uma variável nomeada.

Variáveis GraphQL

O GraphQL permite que as variáveis sejam colocadas na consulta. Para obter mais informações, é possível visualizar a documentação do GraphQL sobre variáveis.

Por exemplo, para obter todos os Fragmentos de conteúdo do tipo Article que tenham uma variação específica, é possível especificar a variável variation no GraphiQL.

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
        }
    }
}

### in query variables
{
    "variation": "Introduction"
}

Diretivas GraphQL

No GraphQL, há uma possibilidade de alterar a consulta com base em variáveis, chamadas de Diretivas GraphQL.

Por exemplo, é possível incluir o campo adventurePrice em uma consulta para todos os AdventureModels, com base em uma variável includePrice.

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}

### in query variables
{
    "includePrice": true
}

Filtragem

Também é possível usar a filtragem em consultas de GraphQL para retornar dados específicos.

A filtragem usa uma sintaxe baseada em operadores lógicos e expressões.

Por exemplo, a consulta a seguir (básica) filtra todas as pessoas cujo nome é Jobs ou Smith:

query {
  personList(filter: {
    name: {
      _logOp: OR
      _expressions: [
        {
          value: "Jobs"
        },
        {
          value: "Smith"
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

Para obter mais exemplos, consulte:

• detalhes da GraphQL para extensões do AEM

• Exemplos de consulta usando esta amostra de conteúdo e estrutura

  • E a amostra de conteúdo e estrutura preparada para uso em consultas de exemplo

• Exemplos de consulta com base no projeto WKND

GraphQL para AEM - resumo das extensões

A operação básica de consultas com o GraphQL para AEM adere à especificação GraphQL padrão. Para consultas de GraphQL com o AEM, há algumas extensões:

• Se você precisar de um único resultado:

  • utilize o nome do modelo; por exemplo, cidade

• Se você espera uma lista de resultados:

  • adicione List ao nome do modelo; por exemplo, cityList
  • Consulte Exemplo de consulta - Todas as informações sobre todas as cidades

• Se quiser usar um operador OR lógico:

  • use _logOp: OR
  • Consulte Exemplo de consulta - Todas as pessoas cujo nome é “Jobs” ou “Smith”

• O operador AND lógico também existe, mas está (muitas vezes) implícito

• Você pode consultar nos nomes de campos que correspondem aos campos no modelo de fragmento de conteúdo

  • Consulte Exemplo de consulta - Detalhes completos do CEO e dos funcionários de uma empresa

• Além dos campos do modelo, há alguns campos gerados pelo sistema (precedidos por um sublinhado):

  • Para conteúdo:

    • _locale : para revelar a língua; com base no Gerenciador de idiomas
      • Consulte Exemplo de consulta para vários fragmentos de conteúdo de uma determinada localidade
    • _metadata : para revelar metadados do fragmento
      • Consulte Exemplo de consulta para metadados - Listar os metadados para prêmios denominados como GB
    • _model : permite a consulta para um modelo de fragmento de conteúdo (caminho e título)
      • Consulte Exemplo de consulta para um modelo de fragmento de conteúdo de um modelo
    • _path : o caminho para o fragmento de conteúdo no repositório
      • Consulte Exemplo de consulta - Um único fragmento de cidade específico
    • _reference : para revelar referências; incluindo referências em linha no Editor de Rich Text
      • Consulte Exemplo de consulta para vários fragmentos de conteúdo com referências previamente buscadas
    • _variation : para revelar variações específicas no fragmento de conteúdo
      • Consulte Exemplo de consulta - Todas as cidades com uma variação nomeada

  • Operações AND:

    • _operator : aplica operadores específicos; EQUALS, EQUALS_NOT, GREATER_EQUAL, LOWER, CONTAINS e STARTS_WITH
      • Consulte Exemplo de consulta - Todas as pessoas cujo nome não é “Jobs”
      • Consulte Exemplo de consulta - Todas as aventuras em que o _path começa com um prefixo específico
    • _apply : para aplicar condições específicas; por exemplo, AT_LEAST_ONCE
      • Consulte Exemplo de consulta - Filtrar em uma matriz com um item que deve ocorrer pelo menos uma vez
    • _ignoreCase : para ignorar se os caracteres são maiúsculos ou minúsculos ao consultar
      • Consulte Exemplo de consulta - Todas as cidades com SAN no nome, independentemente de caracteres maiúsculos ou minúsculos

• Os tipos de união GraphQL são compatíveis:

  • use ... on
    • Consulte Exemplo de consulta para um fragmento de conteúdo de um modelo específico com uma referência de conteúdo

• Fazer o fallback ao consultar fragmentos aninhados:

  • Se uma determinada variação não existir em um fragmento aninhado, a variação principal é retornada.

Consultar o endpoint do GraphQL a partir de um site externo

Para acessar o endpoint do GraphQL a partir de um site externo, é necessário configurar o:

• Filtro CORS
• Filtro de referenciador

Autenticação

Consulte Autenticação para consultas de GraphQL remotas do AEM sobre fragmentos de conteúdo.

Perguntas frequentes

Perguntas que surgiram:

1. P: “Qual a diferença entre a API GraphQL do AEM e a API do Construtor de consultas?”

   • R: “A API GraphQL do AEM oferece controle total sobre a saída em JSON e é um padrão do setor para consulta de conteúdo.
     A partir de agora, o AEM planeja investir na API GraphQL do AEM.”

Tutorial - Introdução ao AEM Headless e GraphQL

Procurando um tutorial prático? Veja o tutorial completo de Introdução ao AEM Headless e GraphQL que ilustra como criar e expor conteúdo usando as APIs GraphQL do AEM e consumi-lo por meio de um aplicativo externo, em um cenário de CMS headless.