Consultas persistentes de GraphQL persisted-graphql-queries

Las consultas persistentes son consultas de GraphQL que se crean y almacenan en el servidor de Adobe Experience Manager (AEM) as a Cloud Service. Las consultas persistentes pueden solicitarlas las aplicaciones cliente con una petición GET. La respuesta de una petición GET se puede almacenar en caché en las capas de Dispatcher y CDN, lo que a la larga mejora el rendimiento de la aplicación cliente solicitante. Esto difiere de las consultas estándar de GraphQL, que se ejecutan mediante peticiones POST en las que la respuesta no se puede almacenar en caché fácilmente.

El IDE de GraphiQL está disponible en AEM para que desarrolle, pruebe y mantenga sus consultas de GraphQL antes de la transferencia a su entorno de producción. Para los casos que necesitan personalización (por ejemplo, cuando se personaliza la caché) puede utilizar la API; consulte el ejemplo de cURL que se proporciona en Persistencia de una consulta de GraphQL.

Consultas y puntos de conexión persistentes persisted-queries-and-endpoints

Las consultas persistentes siempre deben utilizar el punto de conexión relacionado con la configuración de Sites adecuada, para que puedan usar una o ambas:

Por ejemplo, si hay una consulta en particular llamada my-query, que utiliza un modelo my-model desde la configuración de Sites my-conf:

Cómo conservar una consulta de GraphQL how-to-persist-query

Se recomienda mantener las consultas en un entorno de creación de AEM primero, y después transferir la consulta al entorno de publicación de producción de AEM para su uso por parte de las aplicaciones.

Existen varios métodos para hacer que persistan las consultas, entre los que se incluyen los siguientes:

El IDE de GraphiQL es el método preferido para consultas persistentes. Para mantener una consulta determinada utilizando la herramienta línea de comandos cURL:

Ejecución de una consulta persistente execute-persisted-query

Para ejecutar una consulta persistente, una aplicación cliente realiza una petición GET utilizando la siguiente sintaxis:

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

Donde PERSISTENT_PATH es una ruta abreviada donde se guarda la consulta persistente.

Uso de variables de consulta query-variables

Las variables de consulta se pueden usar con Consultas persistentes. Las variables de consulta se anexan a la solicitud con el prefijo punto y coma (;) empleando el nombre y valor de la variable. Las variables múltiples se separan con punto y coma.

El patrón tiene el siguiente aspecto:

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

Por ejemplo, la siguiente consulta contiene una variable activity para filtrar una lista en función de un valor de actividad:

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

Esta consulta se puede mantener en una ruta wknd/adventures-by-activity. Para llamar a la consulta persistente donde activity=Camping la solicitud tendría este aspecto:

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

La codificación UTF-8 %3B es para ; y %3D es la codificación para =. Las variables de consulta y los caracteres especiales deben ser codificados correctamente para que se ejecute la consulta persistente.

Uso de variables de consulta: prácticas recomendadas query-variables-best-practices

Al utilizar variables en las consultas, hay algunas prácticas recomendadas que se deben seguir:

Almacenamiento en caché de las consultas persistentes caching-persisted-queries

Se recomiendan las Consultas persistentes, ya que se pueden almacenar en caché en las capas de Dispatcher y la Red de distribución de contenido (CDN), mejorando finalmente el rendimiento de la aplicación cliente solicitante.

De forma predeterminada, AEM invalidará la caché en función de una definición de tiempo de vida (TTL). Estos TTL se pueden definir mediante los siguientes parámetros. Se puede acceder a estos parámetros de varias formas, con variaciones en los nombres según el mecanismo utilizado:

Instancias de autor author-instances

En las instancias de autor, los valores predeterminados son:

Estos:

Publicación de instancias publish-instances

Para las instancias de publicación, los valores predeterminados son:

Se pueden sobrescribir:

Administración de encabezados de caché HTTP en el IDE de GraphiQL http-cache-headers-graphiql-ide

El IDE de GraphiQL: consulte Guardado de consultas persistentes

Administración de la caché en el Nivel de consulta persistente cache-persisted-query-level

Esto implica publicar la consulta en AEM usando cURL en la interfaz de línea de comandos.

Para ver un ejemplo del método PUT (crear):

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 ver un ejemplo del método POST (actualización):

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

El cache-control se puede configurar en el momento de la creación (PUT) o más tarde (por ejemplo, mediante una petición POST). El control de caché es opcional al crear la consulta persistente, ya que AEM puede proporcionar el valor predeterminado. Consulte Cómo hacer persistir una consulta de GraphQL, para ver un ejemplo de persistencia de una consulta utilizando cURL.

Administración de la caché con variables de Cloud Manager cache-cloud-manager-variables

Variables de entorno de Cloud Manager se puede definir con Cloud Manager para definir los valores necesarios:

Administración de la caché con una configuración OSGi cache-osgi-configration

Para administrar la caché globalmente, puede configurar la configuración de OSGi para la Configuración del servicio de consulta persistente.

La configuración de OSGi predeterminada para instancias de publicación:

Configuración del código de respuesta a la consulta configuring-query-response-code

De forma predeterminada, la PersistedQueryServlet envía una respuesta 200 cuando ejecuta una consulta, independientemente del resultado real.

Puede configurar la configuración de OSGi para la configuración del servicio de consulta persistente para controlar si el extremo /execute.json/persisted-query devuelve códigos de estado más detallados cuando hay un error en la consulta persistente.

El campo Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) se puede definir según sea necesario:

Codificación de la URL de consulta para su uso en una aplicación encoding-query-url

Para su uso en una aplicación, cualquier carácter especial utilizado al construir variables de consulta (es decir, punto y coma (;), signo igual (=), barras oblicuas /) debe convertirse para utilizar la codificación UTF-8 correspondiente.

Por ejemplo:

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

La dirección URL se puede desglosar en las siguientes partes:

En texto sin formato, el URI de solicitud tiene el siguiente aspecto:

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

Para utilizar una consulta persistente en una aplicación cliente, se debe utilizar el SDK de cliente AEM sin encabezado para JavaScript, Java o NodeJS. El SDK de cliente sin encabezado codificará automáticamente todas las variables de consulta de la forma adecuada en la solicitud.

Transferencia de una consulta persistente al entorno de producción transfer-persisted-query-production

Las consultas persistentes siempre deben crearse en un servicio de AEM Author y luego publicarse (replicarse) en un servicio de AEM Publish. A menudo, las consultas persistentes se crean y prueban en entornos más bajos, como los entornos locales o de desarrollo. A continuación, es necesario promocionar las consultas persistentes a entornos de nivel superior, para que finalmente estén disponibles en un entorno de publicación de AEM de producción para que las aplicaciones de cliente las consuman.

Empaquetar consultas persistentes

Las consultas persistentes se pueden integrar en Paquetes de AEM. Los paquetes AEM se pueden descargar e instalar en diferentes entornos. Los paquetes AEM también se pueden replicar desde un entorno de AEM Author a entornos de AEM Publish.

Para crear un paquete, haga lo siguiente:

Una vez creado el paquete, puede hacer lo siguiente: