Consultas persistentes de GraphQL persisted-queries-caching

Consultas persistentes são consultas GraphQL criadas e armazenadas no servidor Adobe Experience Manager (AEM). Elas podem ser solicitadas com uma solicitação GET por aplicativos clientes. A resposta de uma solicitação do GET pode ser armazenada em cache nas camadas do Dispatcher e da Rede de entrega de conteúdo (CDN), melhorando, em última análise, o desempenho do aplicativo cliente solicitante. Isso é diferente das consultas de GraphQL padrão, que são executadas usando solicitações POST, onde a resposta não pode ser facilmente armazenada em cache.

O GraphiQL IDE está disponível no AEM para que você desenvolva, teste e crie consultas GraphQL persistentes antes de transferi-las para o ambiente de produção. Para casos que precisam de personalização (por exemplo, ao personalizar o armazenamento em cache), é possível usar a API; consulte o exemplo de cURL fornecido em Como criar uma consulta persistente de GraphQL.

Endpoints e consultas persistentes persisted-queries-and-endpoints

Consultas persistentes devem sempre usar o endpoint relacionado à configuração apropriada do Sites; para que possam usar um desses, ou ambos:

Por exemplo, se houver uma consulta específica chamada my-query, que usa um modelo my-model da configuração my-conf do Sites:

Como criar uma consulta persistente de GraphQL how-to-persist-query

É recomendável criar consultas persistentes em um ambiente de criação do AEM inicialmente e, em seguida, transferir a consulta para o ambiente de publicação da sua produção do AEM para ser usada pelos aplicativos.

Há vários métodos para criar consultas persistentes, incluindo:

O GraphiQL IDE é o método preferencial para consultas persistentes. Para criar uma determinada consulta persistente usando a ferramenta de linha de comando cURL:

Como executar uma consulta persistente execute-persisted-query

Para executar uma consulta persistente, um aplicativo cliente faz uma solicitação GET usando a seguinte sintaxe:

GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>

Onde PERSISTENT_PATH é um caminho encurtado no qual a consulta persistida é salva.

Uso de variáveis de consulta query-variables

As variáveis de consulta podem ser usadas com consultas persistentes. As variáveis de consulta são anexadas à solicitação e prefixadas por ponto e vírgula (;), usando o nome e o valor da variável. As variáveis são separadas por ponto e vírgula.

O padrão é semelhante ao seguinte:

<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2

Por exemplo, a consulta a seguir contém uma variável activity para filtrar uma lista com base em um valor de atividade:

query getAdventuresByActivity($activity: String!) {
      adventureList (filter: {
        adventureActivity: {
          _expressions: [
            {
              value: $activity
            }
          ]
        }
      }){
        items {
          _path
        adventureTitle
        adventurePrice
        adventureTripLength
      }
    }
  }

Esta consulta pode ser persistida em um caminho wknd/adventures-by-activity. Para chamar a consulta persistente onde activity=Camping, a solicitação terá esta aparência:

<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping

Observe que %3B é a codificação UTF-8 para ; e %3D é a codificação para =. As variáveis de consulta e quaisquer caracteres especiais devem ser corretamente codificados para que a consulta persistente seja executada.

Armazenamento em cache de consultas persistentes caching-persisted-queries

Consultas persistentes são recomendadas, pois elas podem ser armazenadas em cache nas camadas do Dispatcher e da Rede de entrega de conteúdo (CDN), melhorando o desempenho do aplicativo do cliente solicitante.

Por padrão, o AEM invalidará o cache com base em uma definição de Time To Live (TTL). Esses TTLs podem ser definidos pelos seguintes parâmetros. Estes parâmetros podem ser acessados por vários meios, com variações nos nomes de acordo com o mecanismo usado:

Instâncias do autor author-instances

Para instâncias de autor, os valores padrão são:

Estes:

Publicar instâncias publish-instances

Para instâncias de publicação, os valores padrão são:

Eles podem ser substituídos:

Gerenciamento de cache no nível de Consulta persistente cache-persisted-query-level

Envolve postar a consulta no AEM usando o cURL na interface da linha de comando.

Para obter um exemplo do método PUT (criar):

curl -u admin:admin -X PUT \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

Para obter um exemplo do método POST (atualizar):

curl -u admin:admin -X POST \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

O cache-control pode ser definido no momento da criação (PUT) ou posteriormente (por exemplo, por meio de uma solicitação POST por instância). O controle de cache é opcional ao criar a consulta persistente, pois o AEM pode fornecer o valor padrão. Consulte Como criar uma consulta persistente de GraphQL, para obter um exemplo de criação de consulta persistente usando cURL.

Gerenciamento de cache com uma configuração OSGi cache-osgi-configration

Para gerenciar o cache globalmente, você pode definir as configurações de OSGi para a Configuração do Serviço de Consulta Persistente. Caso contrário, essa configuração OSGi usa os valores padrão para instâncias de publicação.

Codificação do URL de consulta para uso por um aplicativo encoding-query-url

Para uso por um aplicativo, quaisquer caracteres especiais usados ao criar variáveis de consulta (ou seja, ponto e vírgula (;), sinal de igual (=), barras /) devem ser convertidos para usar a codificação UTF-8 correspondente.

Por exemplo:

curl -X GET \ "https://localhost:4502/graphql/execute.json/wknd/adventure-by-path%3BadventurePath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fadventures%2Fbali-surf-camp%2Fbali-surf-camp"

O URL pode ser dividido nas seguintes partes:

Em textos sem formatação, o URI da solicitação tem a seguinte aparência:

/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp

Para usar uma consulta persistente em um aplicativo cliente, o SDK do cliente do AEM Headless deve ser usado para JavaScript, Java ou NodeJS. O SDK do cliente headless codificará automaticamente todas as variáveis de consulta apropriadamente na solicitação.

Transferir uma consulta persistente para o ambiente de produção transfer-persisted-query-production

As consultas persistentes devem sempre ser criadas em um serviço de autor do AEM e publicadas (replicadas) em um serviço de publicação do AEM. Geralmente, as consultas persistentes são criadas e testadas em ambientes inferiores, como ambientes locais ou de desenvolvimento. Então, é necessário promover consultas persistentes a ambientes de nível superior, disponibilizando-as em um ambiente de publicação do AEM em produção para que os aplicativos clientes as consumam.

Pacote de consultas persistidas

As consultas persistidas podem ser inseridas em pacotes do AEM. Os pacotes do AEM podem ser baixados e instalados em diferentes ambientes. Os pacotes do AEM também podem ser replicados de um ambiente de autor do AEM para ambientes de publicação do AEM.

Para criar um pacote:

Depois que o pacote tiver sido criado, você poderá: