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.
Se recomiendan las consultas persistentes. Consulte Prácticas recomendadas para consultas de GraphQL (Dispatcher) para obtener más información y la configuración de Dispatcher relacionada.
La variable GraphiQL IDE está disponible en AEM para que desarrolle, pruebe y mantenga sus consultas de GraphQL antes de transferencia a su entorno de producción. Para los casos que necesitan personalización (por ejemplo, cuando personaliza la caché) puede utilizar la API; consulte el ejemplo de curl que se proporciona en Persistencia de una consulta de GraphQL.
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:
Consulte Habilitar la funcionalidad de fragmento de contenido en el explorador de configuración para obtener más información.
Las consultas persistentes de GraphQL deben estar habilitadas para la configuración de sitios adecuada.
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
:
my-conf
específico, y luego la consulta se guardará de la siguiente manera:/conf/my-conf/settings/graphql/persistentQueries/my-query
global
, pero la consulta se guardará de la siguiente manera:/conf/global/settings/graphql/persistentQueries/my-query
Estas son dos consultas distintas: se guardan en rutas diferentes.
Simplemente, utilizan el mismo modelo, pero a través de puntos de conexión diferentes.
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 preferido para consultas persistentes. Para mantener una consulta determinada utilizando la variable curl herramienta de línea de comandos:
Prepare la consulta colocándola en la nueva URL de punto de conexión /graphql/persist.json/<config>/<persisted-label>
.
Por ejemplo, cree una consulta persistente:
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
-d \
'{
articleList {
items{
_path
author
main {
json
}
}
}
}'
En este punto, compruebe la respuesta.
Por ejemplo, compruebe si se ha realizado correctamente:
{
"action": "create",
"configurationName": "wknd",
"name": "plain-article-query",
"shortPath": "/wknd/plain-article-query",
"path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
}
A continuación, puede solicitar la consulta persistente usando GET en la dirección URL /graphql/execute.json/<shortPath>
.
Por ejemplo, utilice la consulta persistente:
$ curl -X GET \
http://localhost:4502/graphql/execute.json/wknd/plain-article-query
Actualice una consulta persistente usando POST en una ruta de consulta ya existente.
Por ejemplo, utilice la consulta persistente:
$ curl -X POST \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
-d \
'{
articleList {
items{
_path
author
main {
json
}
referencearticle {
_path
}
}
}
}'
Cree una consulta sin formato ajustada.
Por ejemplo:
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query-wrapped" \
-d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }"}'
Cree una consulta sencilla ajustada con control de caché.
Por ejemplo:
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
-d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'
Cree una consulta persistente con parámetros:
Por ejemplo:
$ curl -X PUT \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H "Content-Type: application/json" \
"http://localhost:4502/graphql/persist.json/wknd/plain-article-query-parameters" \
-d \
'query GetAsGraphqlModelTestByPath($apath: String!, $withReference: Boolean = true) {
articleByPath(_path: $apath) {
item {
_path
author
main {
plaintext
}
referencearticle @include(if: $withReference) {
_path
}
}
}
}'
Para ejecutar una consulta persistente, una aplicación cliente realiza una solicitud de 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.
Por ejemplo wknd
es el nombre de configuración y plain-article-query
es el nombre de la consulta persistente. Para ejecutar la consulta:
$ curl -X GET \
https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
Ejecución de una consulta con parámetros.
Las variables y los valores de consulta deben ser correctos codificado al ejecutar una consulta persistente.
Por ejemplo:
$ curl -X GET \
"https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query-parameters%3Bapath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fmagazine%2Falaska-adventure%2Falaskan-adventures%3BwithReference%3Dfalse
Consulte variables de consulta para obtener más información.
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
Tenga en cuenta que %3B
es la codificación UTF-8 para ;
y %3D
es la codificación para =
. Las variables de consulta y los caracteres especiales deben ser codificado correctamente para que se ejecute la consulta persistente.
Para su uso por 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:
Parte URL | Descripción |
---|---|
/graphql/execute.json |
Punto final de consulta persistente |
/wknd/adventure-by-path |
Ruta de consulta persistente |
%3B |
Codificación de ; |
adventurePath |
Variable de consulta |
%3D |
Codificación de = |
%2F |
Codificación de / |
%2Fcontent%2Fdam... |
Ruta codificada al fragmento de contenido |
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, Javao NodeJS. El SDK de cliente sin encabezado codificará automáticamente todas las variables de consulta de la forma adecuada en la solicitud.
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.
Las consultas persistentes se pueden incorporar en Paquetes AEM. AEM paquetes se pueden descargar e instalar en diferentes entornos. AEM paquetes también se pueden replicar desde un entorno de AEM Author a entornos de AEM Publish.
Para crear un paquete:
persistentQueries
debajo de la configuración. Por ejemplo, para la variable wknd
configuración de la ruta completa /conf/wknd/settings/graphql/persistentQueries
.Una vez creado el paquete, puede: