API GraphQL do AEM para uso com Fragmentos de conteúdo graphql-api-for-use-with-content-fragments

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

A API do GraphQL do AEM usada com Fragmentos de conteúdo é altamente baseada na API padrão de código aberto do GraphQL.

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

Pré-requisitos prerequisites

Os clientes que usam o GraphQL devem instalar o AEM Content Fragment with GraphQL Index Package 1.0.5. Consulte as Notas de versão para obter mais detalhes.

A API GraphQL graphql-api

O GraphQL é:

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

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

Terminologia de GraphQL graphql-terminology

O GraphQL usa o seguinte:

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

Tipos de consulta de GraphQL graphql-query-types

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

O AEM fornece recursos para converter consultas (ambos os tipos) em Consultas Persistentes que são armazenadas em cache pelo Dispatcher e pela CDN.

Práticas recomendadas de consulta GraphQL (Dispatcher e CDN) graphql-query-best-practices

Consultas persistentes são o método recomendado para serem usadas em instâncias de publicação como:

As consultas GraphQL que utilizam solicitações 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.

Embora o GraphQL também seja compatível com solicitações GET, essas solicitações podem atingir limites (por exemplo, o comprimento do URL) que podem ser evitados usando consultas persistentes.

Consulte Habilitar o cache de consultas persistentes para obter mais detalhes.

Interface GraphiQL graphiql-interface

Uma implementação da interface padrão GraphiQL está disponível para uso com o AEM GraphQL.

Essa interface permite inserir e testar diretamente consultas.

Por exemplo:

Ele fornece recursos como realce de sintaxe, preenchimento automático e sugestão automática, juntamente com um histórico e uma documentação online:

Casos de uso para ambientes de Autor e Publicação use-cases-author-publish-environments

Os casos de uso podem depender do tipo de ambiente AEM:

Permissões permission

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

As consultas do GraphQL são executadas com a permissão do usuário AEM da solicitação subjacente. Se o usuário não tiver acesso de leitura a alguns fragmentos (armazenados como Assets), eles não se tornarão parte do conjunto de resultados.

Além disso, o usuário deve ter acesso a um endpoint do GraphQL para executar consultas do GraphQL.

Geração de esquemas schema-generation

O GraphQL é uma API 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 concluir essas diretrizes, um cliente deve 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 criar um modelo de fragmento de conteúdo chamado Article, o AEM gerará um ArticleModel do tipo GraphQL. Os campos desse tipo correspondem aos campos e tipos de dados definidos no modelo. Além disso, ele cria alguns pontos de entrada para as consultas que operam nesse tipo, como articleByPath ou articleList.

No GraphQL para AEM, o esquema é flexível. Essa flexibilidade significa que ela é gerada automaticamente sempre 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ê:

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 resulta na saída do esquema com o tipo de conteúdo: text/x-graphql-schema;charset=iso-8859-1.

Geração de esquema - Modelos não publicados schema-generation-unpublished-models

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 para o 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 fields

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

Tipos de dados data-types

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 helper-fields

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

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.

Caminho path

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

O código a seguir exibe 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, você também deve determinar seu caminho primeiro. Por exemplo:

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

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

Metadados metadata

Por meio do GraphQL, o AEM também expõe os metadados de um Fragmento de conteúdo. Os metadados são as informações que descrevem um fragmento de conteúdo, como o seguinte:

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, essa propriedade será uma propriedade de sequência; portanto, consulte todos os metadados de sequência:

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 variations

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 graphql-variables

O GraphQL permite que as variáveis sejam colocadas na consulta. Para obter mais informações, consulte Documentação do GraphQL para 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
            _variations
        }
    }
}

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

Diretivas GraphQL graphql-directives

No GraphQL, há uma possibilidade de alterar o query com base em variáveis, chamadas de Diretivas do 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 filtering

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.

A menor parte é uma expressão única que pode ser aplicada ao conteúdo de um determinado campo. Ela compara o conteúdo do campo com um determinado valor constante.

Por exemplo, a expressão a seguir compararia o conteúdo do campo com o valor some text e teria êxito se o conteúdo fosse igual ao valor. Caso contrário, a expressão falhará.:

{
  value: "some text"
  _op: EQUALS
}

Os operadores a seguir podem ser usados para comparar campos com um determinado valor:

Alguns tipos também permitem especificar opções adicionais que modificam como uma expressão é avaliada:

As expressões podem ser combinadas a um conjunto com a ajuda de um operador lógico (_logOp):

Cada campo pode ser filtrado por seu próprio conjunto de expressões. Os conjuntos de expressões de todos os campos mencionados no argumento de filtro são eventualmente combinados por seu próprio operador lógico.

Uma definição de filtro (transmitida como o argumento filter para uma consulta) contém:

Você pode omitir _logOp se quiser combinar itens com AND e _operator se quiser verificar a igualdade, pois esses valores são o padrão.

O exemplo a seguir demonstra uma consulta completa que filtra todas as pessoas que têm um lastName igual a Provo ou que contêm sjö, independentemente do caso:

{
  authorList(filter: {
    lastname: {
      _logOp: OR
      _expressions: [
        {
          value: "sjö",
          _operator: CONTAINS,
          _ignoreCase: true
        },
        {
          value: "Provo"
        }
      ]
    }
  }) {
    items {
      lastName
      firstName
    }
  }
}

Ao executar uma consulta GraphQL usando variáveis opcionais, se um valor específico for não fornecido para a variável opcional, a variável será ignorada na avaliação do filtro. Ou seja, os resultados da consulta conterão todos os valores, null e não null, para a propriedade relacionada à variável de filtro.

Por exemplo, na consulta abaixo, onde nenhum valor é especificado para a propriedade lastName:

query getAuthorsFilteredByLastName($authorLastName: String) {
  authorList(filter:
    {
      lastName: {_expressions: {value: $authorLastName}
      }}) {
    items {
      lastName
    }
  }
}

Todos os autores serão retornados:

{
  "data": {
    "authorList": {
      "items": [
        {
          "lastName": "Hammer"
        },
        {
          "lastName": "Provo"
        },
        {
          "lastName": "Wester"
        },
        {
          "lastName": null
        },
         ...
      ]
    }
  }
}

Embora também seja possível filtrar em campos aninhados, isso não é recomendado, pois pode causar problemas de desempenho.

Para obter mais exemplos, consulte:

Classificação sorting

Esse recurso permite classificar os resultados da consulta de acordo com um campo especificado.

Os critérios de classificação são:

Por exemplo:

query {
  authorList(sort: "lastName, firstName") {
    items {
      firstName
      lastName
    }
  }
}

E também:

{
  authorList(sort: "lastName DESC, firstName DESC") {
    items {
        lastName
        firstName
    }
  }
}

Também é possível classificar um campo dentro de um fragmento aninhado, usando o formato de nestedFragmentname.fieldname.

Por exemplo:

query {
  articleList(sort: "authorFragment.lastName")  {
    items {
      title
      authorFragment {
        firstName
        lastName
        birthDay
      }
      slug
    }
  }
}

Paginação paging

Esse recurso permite executar a paginação em tipos de consulta que retornam uma lista. Dois métodos são fornecidos:

Consulta de lista - offset e limit list-offset-limit

Em uma consulta de ...List você pode usar offset e limit para retornar um subconjunto específico de resultados:

Por exemplo, para exibir uma página de resultados que contém até cinco artigos, começando do quinto artigo da lista de resultados completa:

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}

Consulta paginada - first e after paginated-first-after

O tipo de consulta ...Paginated reutiliza a maioria dos recursos do tipo de consulta ...List (filtragem, classificação), mas, em vez de usar os argumentos offset/limit, ele usa os argumentos first/after, definidos pela Especificação de conexões do cursor GraphQL. Você pode encontrar uma introdução mais simplificada na Introdução ao GraphQL.

Por exemplo, exibe uma página de resultados contendo até cinco aventuras, começando pelo item de cursor especificado na lista de resultados completa:

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}

Consultas persistentes do GraphQL - ativação do armazenamento em cache no Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

O armazenamento em cache de consultas persistentes não é ativado por padrão no Dispatcher. A ativação padrão não é possível, pois os clientes que usam o CORS (Cross-Origin Resource Sharing, Compartilhamento de recursos entre origens) precisam revisar e possivelmente atualizar a configuração do Dispatcher.

Habilitar armazenamento em cache de consultas persistentes enable-caching-persisted-queries

Para habilitar o armazenamento em cache de consultas persistentes, as seguintes atualizações dos arquivos de configuração do Dispatcher são necessárias:

Configuração do CORS no Dispatcher cors-configuration-in-dispatcher

Clientes que usam solicitações do CORS podem precisar revisar e atualizar sua configuração do CORS no Dispatcher.

GraphQL para AEM - resumo das extensões graphql-extensions

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

Filtro CORS cors-filter

Para acessar o endpoint do GraphQL, configure uma política do CORS no repositório Git do cliente. Essa configuração é feita adicionando um arquivo de configuração OSGi CORS apropriado para um ou mais endpoints desejados.

Esta configuração deve especificar uma origem de site confiável alloworigin ou alloworiginregexp para a qual o acesso deve ser concedido.

Por exemplo, para conceder acesso ao endpoint do GraphQL e ao endpoint de consultas persistentes para https://my.domain, você pode usar:

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

Se você tiver configurado um caminho personalizado para o endpoint, também poderá usá-lo no allowedpaths.

Filtro de referenciador referrer-filter

Além da configuração do CORS, um filtro Referenciador deve ser configurado para permitir acesso de hosts de terceiros.

Esse filtro é feito adicionando um arquivo de configuração de Filtro referenciador OSGi apropriado que:

Por exemplo, para conceder acesso a solicitações com o referenciador my.domain, é possível:

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}

Limitações limitations

Para se proteger contra possíveis problemas, há limitações padrão impostas às consultas:

Você também precisa estar ciente de:

Autenticação authentication

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

Perguntas frequentes faqs

Perguntas que surgiram:

Tutorial - Introdução ao AEM Headless e GraphQL tutorial

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.