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:
O GraphQL é usado em dois cenários (separados) no Adobe Experience Manager (AEM):
Os clientes que usam o GraphQL devem instalar o AEM Content Fragment with GraphQL Index Package 1.0.5. Consulte a Notas de versão para obter mais detalhes.
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. Ele dá aos clientes o poder de solicitar exatamente o que precisam e nada mais, 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 que você possa criar produtos mais rápido do que nunca…".
Consulte Explorar GraphQL.
"…uma linguagem de consulta de dados e especificação desenvolvidas internamente pela 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 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:
O GraphQL usa o seguinte:
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.
Com o GraphQL, é possível executar consultas para retornar:
Uma entrada única
O AEM fornece recursos para converter consultas (ambos os tipos) em Consultas persistentes que são armazenados em cache pelo Dispatcher e pelo CDN.
As consultas persistentes são o método recomendado a ser usado em instâncias de publicação, como:
Normalmente, não há dispatcher/CDN no autor, portanto, não há ganho de desempenho ao usar consultas persistentes lá; além de testá-las.
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.
A capacidade de realizar consultas diretas pode se tornar obsoleta em algum momento no futuro.
Uma implementação da norma GraphiQL A interface do está disponível para uso com o AEM GraphQL.
O GraphiQL é incluído em todos os ambientes de AEM (mas só é acessível/visível quando você configura os endpoints).
Em versões anteriores, você precisava de um pacote para instalar o GraphiQL IDE. Se você tiver esse pacote instalado, ele poderá ser removido.
Essa interface permite inserir e testar diretamente consultas.
Por exemplo:
http://localhost:4502/content/graphiql.html
Isso fornece recursos como realce de sintaxe, preenchimento automático e sugestão automática, juntamente com um histórico e uma documentação online:
Consulte Uso do GraphiQL IDE.
Os casos de uso podem depender do tipo de ambiente AEM:
Ambiente de publicação; usado para:
Ambiente de autor; usado para:
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 Ativos), 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.
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 query.
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.
Todos os esquemas de GraphQL (derivados dos modelos de fragmento de conteúdo que foram Habilitados) são legíveis por meio do endpoint do GraphQL.
Essa capacidade significa que você deve garantir que não haja dados confidenciais disponíveis, pois eles podem ser vazados dessa maneira. Por exemplo, inclui informações que podem estar presentes como nomes de campo na definição do modelo.
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
.
Um modelo de fragmento de conteúdo:
O esquema de GraphQL correspondente (saída da documentação automática do GraphiQL):
Esta imagem 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, (a variável campos auxiliares) _path
, _metadata
, _variations
.
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. 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ê:
Instalar um pacote contendo Content-Fragment-Model-1
e Content-Fragment-Model-2
:
Model-1
e Model-2
são geradas.Em seguida, o Content-Fragment-Model-2
é modificado:
Somente o Model-2
O tipo de GraphQL é atualizado.
Considerando Model-1
continua a mesma.
É importante observar esses detalhes caso queira fazer atualizações em massa nos modelos de fragmento de conteúdo por meio da API REST ou de outra maneira.
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 GET
solicitação em /content/cq:graphql/global/endpoint.GQLschema
resulta na saída do schema com o tipo de conteúdo: text/x-graphql-schema;charset=iso-8859-1
.
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.
A interface de usuário do AEM impede que isso aconteça, mas se a publicação for feita de forma programática ou com pacotes de conteúdo, isso poderá ocorrer.
Quando isso acontece, o AEM gera um incompleto Esquema 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.
Dentro do esquema, há campos individuais de duas categorias básicas:
Campos gerados.
Uma seleção de Tipos de dados é 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.
multifield
na lista suspensa.O GraphQL para AEM também gera vários campos auxiliares.
Esses campos são usados para identificar um fragmento de conteúdo ou obter mais informações sobre ele.
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:
Modelo de fragmento de conteúdo - Tipo de dados | Tipo de GraphQL | Descrição |
---|---|---|
Texto em linha única | String , [String] |
Usado para sequências de caracteres simples, como nomes de autor e nomes de localização. |
Texto multilinha | String |
Usado para saída de texto, como o corpo de um artigo |
Número | Float , [Float] |
Usado para exibir números de ponto flutuantes e números regulares |
Booleano | Boolean |
Usado para exibir caixas de seleção → declarações simples de verdadeiro/falso |
Data e hora | Calendar |
Usado para exibir data e hora em um formato ISO 8086. Dependendo do tipo selecionado, há três opções disponíveis para uso no GraphQL do AEM: onlyDate , onlyTime e dateTime |
Enumeração | String |
Usado para exibir uma opção de uma lista de opções definidas na criação do modelo |
Tags | [String] |
Usado para exibir uma lista de sequências de caracteres que representam tags usadas no AEM |
Referência de conteúdo | String |
Usado para exibir o caminho para outro ativo no AEM |
Referência do fragmento | Um tipo de modelo Campo único: Model - Tipo de modelo, referenciado diretamente Vários campos, com um tipo referenciado: [Model] - Matriz de tipo Model , referenciado diretamente do array Vários campos, com vários tipos referenciados: [AllFragmentModels] - Matriz de todos os tipos de modelo, referenciada da matriz com tipo de união |
Usado para fazer referência a um ou mais Fragmentos de conteúdo de determinados Tipos de modelo, definidos quando o modelo foi criado |
Além dos tipos de dados para campos gerados pelo usuário, o GraphQL para AEM também gera vários auxiliar campos para ajudar a identificar um fragmento de conteúdo ou para 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.
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.
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. A variável TypedMetaData
expõe as informações agrupadas pelos seguintes tipos escalares:
Texto |
---|
stringMetadata:[StringMetadata]! |
stringArrayMetadata:[StringArrayMetadata]! |
intMetadata:[IntMetadata]! |
intArrayMetadata:[IntArrayMetadata]! |
floatMetadata:[FloatMetadata]! |
floatArrayMetadata:[FloatArrayMetadata]! |
booleanMetadata:[BooleanMetadata]! |
booleanArrayMetadata:[booleanArrayMetadata]! |
calendarMetadata:[CalendarMetadata]! |
calendarArrayMetadata:[CalendarArrayMetadata]! |
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
.
Diferença entre metadados normais e de matriz
Lembre-se que StringMetadata
e StringArrayMetadata
se referem ao que é armazenado no repositório, não a como você os recupera.
Por exemplo, ao chamar a variável stringMetadata
recebe uma matriz de todos os metadados armazenados no repositório como um String
. E se você chamar stringArrayMetadata
, você receberá uma matriz de todos os metadados armazenados no repositório como String[]
.
Consulte Exemplo de consulta para metadados - listar os metadados para prêmios denominados GB.
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
}
}
}
A variável _variations
o campo não contém um master
variação, uma vez que tecnicamente os dados originais (referenciados Principal na interface) não é considerada uma variação explícita.
Consulte Exemplo de consulta - todas as cidades com uma variável nomeada.
Se a variação especificada não existir para um Fragmento de conteúdo, os dados originais (também conhecidos como variação principal) são retornados como padrão (substituta).
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"
}
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
}
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 terão êxito se o conteúdo for 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:
Operador | Tipos | A expressão será bem-sucedida se… |
---|---|---|
EQUALS |
String , ID , Boolean |
… o valor é igual ao conteúdo do campo |
EQUALS_NOT |
String , ID |
…o valor não for igual ao conteúdo do campo |
CONTAINS |
String |
… o conteúdo do campo contém o valor ({ value: "mas", _op: CONTAINS } corresponde a Christmas , Xmas , master , …) |
CONTAINS_NOT |
String |
…o conteúdo do campo não contiver o valor |
STARTS_WITH |
ID |
… a ID começa com um determinado valor ({ value: "/content/dam/", _op: STARTS_WITH corresponde a /content/dam/path/to/fragment , mas não /namespace/content/dam/something |
EQUAL |
Int , Float |
… o valor é igual ao conteúdo do campo |
UNEQUAL |
Int , Float |
…o valor não for igual ao conteúdo do campo |
GREATER |
Int , Float |
…o conteúdo do campo for maior que o valor |
GREATER_EQUAL |
Int , Float |
…o conteúdo do campo for maior ou igual ao valor |
LOWER |
Int , Float |
…o conteúdo do campo for menor que o valor |
LOWER_EQUAL |
Int , Float |
…o conteúdo do campo for menor ou igual ao valor |
AT |
Calendar , Date , Time |
… o conteúdo do campo é o mesmo que o valor (incluindo a configuração de fuso horário) |
NOT_AT |
Calendar , Date , Time |
…o conteúdo do campo não for igual ao valor |
BEFORE |
Calendar , Date , Time |
…o ponto no tempo indicado pelo valor for anterior ao ponto no tempo indicado pelo conteúdo do campo |
AT_OR_BEFORE |
Calendar , Date , Time |
…o ponto no tempo indicado pelo valor for anterior ou igual ao ponto no tempo indicado pelo conteúdo do campo |
AFTER |
Calendar , Date , Time |
…o ponto no tempo indicado pelo valor for posterior ao ponto no tempo indicado pelo conteúdo do campo |
AT_OR_AFTER |
Calendar , Date , Time |
…o ponto no tempo indicado pelo valor for posterior ou igual ao ponto no tempo indicado pelo conteúdo do campo |
Alguns tipos também permitem especificar opções adicionais que modificam como uma expressão é avaliada:
Opção | Tipos | Descrição |
---|---|---|
_ignoreCase |
String |
Ignora a capitalização de uma cadeia de caracteres, por exemplo, um valor de time corresponde a TIME , time , tImE , … |
_sensitiveness |
Float |
Permite uma certa margem para que valores float sejam considerados iguais (para contornar limitações técnicas devido à representação interna de valores float ; deve ser evitada, pois essa opção pode ter um impacto negativo no desempenho |
As expressões podem ser combinadas a um conjunto com a ajuda de um operador lógico (_logOp
):
OR
- o conjunto de expressões terá êxito se pelo menos uma expressão tiver êxitoAND
- o conjunto de expressões terá êxito se todas as expressões tiverem êxito (padrão)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:
lastName
no filtro para o lastName
no Tipo de dados (campo)_expressions
, fornecendo o conjunto de expressões e a variável _logOp
campo que define o operador lógico com o qual as expressões devem ser combinadasvalue
) e o operador (campo _operator
) com o qual o conteúdo de um campo deve ser comparadoVocê pode omitir _logOp
se quiser combinar itens com AND
e _operator
se quiser verificar a igualdade, pois esses valores são padrões.
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
}
}
}
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:
detalhes da GraphQL para extensões do AEM
Exemplos de consulta usando esta amostra de conteúdo e estrutura
Para obter o melhor desempenho, considere Atualização dos fragmentos de conteúdo para paginação e classificação na filtragem do GraphQL.
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
.
Este formato pode ter um impacto negativo no desempenho.
Por exemplo:
query {
articleList(sort: "authorFragment.lastName") {
items {
title
authorFragment {
firstName
lastName
birthDay
}
slug
}
}
}
Para obter o melhor desempenho, considere Atualização dos fragmentos de conteúdo para paginação e classificação na filtragem do GraphQL.
Esse recurso permite executar a paginação em tipos de consulta que retornam uma lista. Dois métodos são fornecidos:
offset
e limit
em uma consulta List
first
e after
em uma consulta Paginated
Em uma consulta de ...List
você pode usar offset
e limit
para retornar um subconjunto específico de resultados:
offset
: especifica o primeiro conjunto de dados a ser retornadolimit
: especifica o número máximo de conjuntos de dados a serem retornadosPor 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
}
}
}
}
A paginação exige uma ordem de classificação estável para funcionar corretamente em várias consultas que solicitam páginas diferentes do mesmo conjunto de resultados. Por padrão, ele usa o caminho do repositório de cada item do conjunto de resultados para garantir que a ordem seja sempre a mesma. Se uma ordem de classificação diferente for usada e se essa classificação não puder ser feita no nível de consulta JCR, haverá um impacto negativo no desempenho. O motivo é que todo o conjunto de resultados deve ser carregado na memória antes que as páginas sejam determinadas.
Quanto maior o deslocamento, mais tempo leva para ignorar os itens do conjunto completo de resultados da consulta JCR. Uma solução alternativa para grandes conjuntos de resultados é usar a consulta paginada com os métodos first
e 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.
first
: os primeiros n
itens a serem retornados.50
.100
.after
: o cursor que determina o início da página solicitada. O item representado pelo cursor não está incluído no conjunto de resultados. O cursor de um item é determinado pela variável cursor
do campo edges
estrutura.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
}
}
}
Por padrão, a paginação usa a UUID do nó do repositório que representa o fragmento para ordenação, garantindo que a ordem dos resultados seja sempre a mesma. Quando sort
é usado, o UUID será usado implicitamente para garantir uma ordem de classificação exclusiva, mesmo para dois itens com chaves de classificação idênticas.
Devido a restrições técnicas internas, o desempenho será reduzido se a classificação e a filtragem forem aplicadas em campos aninhados. Portanto, use os campos de filtro/classificação armazenados no nível raiz. Essa técnica também é a maneira recomendada se você quiser consultar grandes conjuntos de resultados paginados.
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:
Se você precisar de um único resultado:
Se você espera uma lista de resultados:
List
ao nome do modelo; por exemplo, cityList
É possível:
ASC
: crescenteDESC
: decrescenteRetorna uma página de resultados usando uma dessas duas opções:
Consulte Exemplo de consulta - Todas as informações sobre todas as cidades
O filtro includeVariations
está incluído na variável List
tipo de consulta. Para recuperar as Variações do fragmento de conteúdo nos resultados da consulta, a variável includeVariations
o filtro deve ser definido como true
.
O filtro includeVariations
não pode ser usado junto com o campo gerado pelo sistema _variation
.
Se quiser usar um operador OR lógico:
_logOp: OR
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
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
_metadata
: para revelar metadados do fragmento
_model
: permite a consulta para um modelo de fragmento de conteúdo (caminho e título)
_path
: o caminho para o fragmento de conteúdo no repositório
_reference
: para revelar referências; incluindo referências em linha no Editor de Rich Text
_variation
: para revelar variações específicas no fragmento de conteúdo
Se a variação especificada não existir para um Fragmento de conteúdo, a variação principal será retornada como padrão (substituta).
O campo gerado pelo sistema _variation
não pode ser usado junto com o filtro includeVariations
.
_tags
: para revelar as IDs dos Fragmentos de conteúdo ou Variações que contêm tags; esta lista é uma matriz de cq:tags
identificadores.
As tags também podem ser consultadas listando os metadados de um fragmento de conteúdo.
_operator
: aplica operadores específicos; EQUALS
, EQUALS_NOT
, GREATER_EQUAL
, LOWER
, CONTAINS
e STARTS_WITH
_apply
: para aplicar condições específicas; por exemplo, AT_LEAST_ONCE
_ignoreCase
: para ignorar se os caracteres são maiúsculos ou minúsculos ao consultar
Os tipos de união GraphQL são compatíveis:
Fazer o fallback ao consultar fragmentos aninhados:
Para obter uma visão geral detalhada da política de compartilhamento de recursos do CORS no AEM, consulte Entenda o CORS (Cross-Origin Resource Sharing, Compartilhamento de recursos entre origens).
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
acesso deve ser concedido.
Por exemplo, para conceder acesso ao endpoint do GraphQL e ao endpoint de consultas persistentes para https://my.domain
, é possível 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
.
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:
allow.hosts
ou allow.hosts.regexp
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":[
""
]
}
Continua a ser responsabilidade do cliente:
Toda os esquemas de GraphQL (derivados de modelos de fragmento de conteúdo que foram Habilitados) são legíveis por meio do endpoint do GraphQL.
Essa funcionalidade significa que você deve garantir que não haja dados confidenciais disponíveis, pois eles podem ser vazados dessa maneira. Por exemplo, inclui informações que podem estar presentes como nomes de campo na definição do modelo.
Consulte Autenticação para consultas de GraphQL remotas do AEM sobre fragmentos de conteúdo.
Perguntas que surgiram:
P: “Qual a diferença entre a API GraphQL do AEM e a API do Construtor de consultas?”
Procurando um tutorial prático? Confira Introdução ao AEM Headless e ao GraphQL Tutorial completo que ilustra como criar e expor conteúdo usando APIs AEM GraphQL e consumi-lo por um aplicativo externo, em um cenário de CMS headless.