Requêtes GraphQL persistantes

Les requêtes persistantes sont des requêtes GraphQL qui sont créées et stockées sur le serveur Adobe Experience Manager (AEM) as a Cloud Service. Elles peuvent être demandées avec une requête GET par les applications clientes. La réponse d’une requête GET peut être mise en cache aux couches Dispatcher et CDN, ce qui améliore finalement les performances de l’application cliente qui la demande. Elles sont en cela différentes des requêtes GraphQL standard, qui sont exécutées à l’aide de requêtes POST dans lesquelles la réponse ne peut pas être facilement mise en cache.

Le IDE GraphiQL est disponible dans AEM pour que vous puissiez développer, tester et conserver vos requêtes GraphQL, avant transfert vers votre environnement de production. Dans les cas qui nécessitent une personnalisation (par exemple, pour la personnalisation du cache) vous pouvez utiliser l’API ; consultez l’exemple de curl fourni dans Conservation d’une requête GraphQL.

Requêtes et points d’entrée persistants

Les requêtes persistantes doivent toujours utiliser le point d’entrée associé à la configuration Sites appropriée afin qu’ils puissent utiliser l’une des fonctionnalités ou les deux :

• Configuration globale et point d’entrée
  La requête a accès à tous les modèles de fragment de contenu.
• Configuration(s) de sites spécifiques et point(s) d’entrée
  La création d’une requête persistante pour une configuration Sites spécifique nécessite un point d’entrée spécifique à la configuration Sites correspondant (pour fournir l’accès aux modèles de fragment de contenu associés).
  Par exemple, pour créer une requête persistante spécifique à la configuration WKND Sites, une configuration de sites spécifique à WKND correspondante et un point d’entrée spécifique à WKND doivent être créés à l’avance.

Par exemple, s’il existe une requête spécifique appelée my-query, qui utilise un modèle my-model de la configuration Sites my-conf :

• Vous pouvez créer une requête à l’aide du point d’entrée my-conf spécifique, puis la requête sera enregistrée comme suit :
  /conf/my-conf/settings/graphql/persistentQueries/my-query
• Vous pouvez créer la même requête à l’aide du point d’entrée global, mais elle sera dans ce cas enregistrée comme suit :
  /conf/global/settings/graphql/persistentQueries/my-query

Conservation d’une requête GraphQL

Il est recommandé d’appliquer des requêtes persistantes dans un environnement de création d’AEM dès le départ, puis de transférer la requête à votre environnement de publication AEM de production, pour être utilisées par les applications.

Il existe différentes méthodes pour créer des requêtes persistantes, notamment :

• IDE GraphiQL - voir Enregistrement des requêtes persistantes (méthode préférée)
• curl - Consultez l’exemple suivant
• Autres outils, notamment Postman

L’IDE GraphiQL est l’IDE preferred pour les requêtes persistantes. Pour conserver une requête donnée à l’aide de la fonction curl outil de ligne de commande :

1. Préparez la requête avec une commande PUT sur l’URL du nouveau point d’entrée /graphql/persist.json/<config>/<persisted-label>.

   Par exemple, créez une requête persistante :

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

2. À ce stade, vérifiez la réponse.

   Par exemple, contrôlez le succès :

   {
     "action": "create",
     "configurationName": "wknd",
     "name": "plain-article-query",
     "shortPath": "/wknd/plain-article-query",
     "path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
   }
   

3. Vous pouvez ensuite exécuter à nouveau la requête persistante avec une commande GET sur l’URL /graphql/execute.json/<shortPath>.

   Par exemple, utilisez la requête persistante :

   $ curl -X GET \
       http://localhost:4502/graphql/execute.json/wknd/plain-article-query
   

4. Mettez à jour une requête persistante avec une commande POST vers un chemin de requête existant.

   Par exemple, utilisez la requête persistante :

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

5. Créez une requête ordinaire encapsulée.

   Par exemple :

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

6. Créez une requête ordinaire encapsulée avec le contrôle de cache.

   Par exemple :

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

7. Créez une requête persistante avec des paramètres :

   Par exemple :

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

Exécution d’une requête persistante

Pour exécuter une requête persistante, une application client effectue une requête GET en utilisant la syntaxe suivante :

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

Où PERSISTENT_PATH est un chemin raccourci vers l’emplacement d’enregistrement de la requête persistante.

1. Par exemple wknd est le nom de la configuration et plain-article-query est le nom de la requête persistante. Pour exécuter la requête :

   $ curl -X GET \
       https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
   

2. Exécution d’une requête avec des paramètres.

   REMARQUE

   Les variables et valeurs de requête doivent être correctement encoded lors de l’exécution d’une requête persistante.

   Par exemple :

   $ 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
   

   Voir Utilisation variables de requête pour plus d’informations.

Utilisation de variables de requête

Les variables de requête peuvent être utilisées avec les requêtes persistantes. Les variables de requête sont ajoutées à la requête précédée d’un point-virgule (;) à l’aide du nom et de la valeur de la variable. Plusieurs variables sont séparées par des points-virgules.

Le modèle ressemble à ce qui suit :

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

Par exemple, la requête suivante contient une variable . activity pour filtrer une liste en fonction d’une valeur d’activité :

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

Cette requête peut être conservée sous un chemin wknd/adventures-by-activity. Pour appeler la requête persistante où activity=Camping la requête ressemblerait à ceci :

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

Notez que %3B est l’encodage UTF-8 pour ; et %3D est l’encodage pour =. Les variables de requête et les caractères spéciaux doivent être correctement encodé pour que la requête persistante s’exécute.

Mise en cache de vos requêtes persistantes

Les requêtes persistantes sont recommandées, car elles peuvent être mises en cache aux couches Dispatcher et CDN, ce qui améliore finalement les performances de l’application cliente qui demande.

Par défaut, AEM invalide le cache du réseau de diffusion de contenu (CDN) en fonction d’une durée de vie par défaut (TTL).

Cette valeur est définie sur :

• 7 200 secondes est la durée de vie par défaut du Dispatcher et du réseau de diffusion de contenu, également connus sous le nom de caches partagés.
  • default: s-maxage=7200
• 60 est la durée de vie par défaut du client (par exemple, un navigateur).
  • default: maxage=60

Si vous souhaitez modifier la durée de vie de votre requête GraphLQ, la requête doit être :

• persistante après la gestion de En-têtes de cache HTTP - à partir de l’IDE GraphQL
• persistante à l’aide de la fonction méthode API.

Gestion des en-têtes de cache HTTP dans GraphQL

L’IDE GraphiQL - voir Enregistrement des requêtes persistantes

Gestion du cache à partir de l’API

Cela implique de publier la requête dans AEM à l’aide de la CURL dans votre interface de ligne de commande.

Par exemple :

curl -X PUT \
    -H 'authorization: Basic YWRtaW46YWRtaW4=' \
    -H "Content-Type: application/json" \
    "https://publish-p123-e456.adobeaemcloud.com/graphql/persist.json/wknd/plain-article-query-max-age" \
    -d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'

Le cache-control peut être défini au moment de la création (PUT) ou ultérieurement (par exemple, via une demande de POST). Le contrôle du cache est facultatif lors de la création de la requête persistante car AEM peut fournir la valeur par défaut. Consultez Conservation d’une requête GraphQL, par exemple pour conserver une requête à l’aide d’une commande curl.

Encodage de l’URL de requête à utiliser par une application

Pour une utilisation par une application, tout caractère spécial utilisé lors de la création de variables de requête (c’est-à-dire des points-virgules (;), signe égal (=), barres obliques /) doit être converti pour utiliser le codage UTF-8 correspondant.

Par exemple :

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"

L’URL peut être divisée en plusieurs parties :

En texte brut, l’URI de requête ressemble à ce qui suit :

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

Pour utiliser une requête persistante dans une application cliente, le SDK client AEM sans interface utilisateur doit être utilisé pour JavaScript, Javaou NodeJS. Le SDK client sans tête codera automatiquement toutes les variables de requête correctement dans la requête.

Transfert d’une requête persistante vers votre environnement de production

Les requêtes persistantes doivent toujours être créées sur un service AEM Author, puis publiées (répliquées) sur un service AEM Publish. Souvent, les requêtes persistantes sont créées et testées dans des environnements inférieurs tels que les environnements locaux ou de développement. Il est ensuite nécessaire de promouvoir les requêtes persistantes dans des environnements de niveau supérieur, ce qui rend ces requêtes disponibles dans un environnement de publication AEM de production pour que les applications clientes puissent les utiliser.

Requêtes persistantes de package

Les requêtes persistantes peuvent être intégrées à AEM de modules. AEM les packages peuvent ensuite être téléchargés et installés dans différents environnements. Les modules AEM peuvent également être répliqués d’un environnement de création AEM vers des environnements de publication AEM.

Pour créer un module :

1. Accédez à Outils > Déploiement > Packages.
2. Créez un module en appuyant sur Créer un module. Une boîte de dialogue s’ouvre alors pour définir le module.
3. Dans la boîte de dialogue Définition de module, sous Général saisir une Nom comme "wknd-persistent-requêtes".
4. Saisissez un numéro de version du type "1.0".
5. Sous Filtres ajouter une nouvelle Filtrer. Utilisez l’outil de recherche de chemin pour sélectionner la variable persistentQueries sous la configuration. Par exemple, pour la variable wknd configuration Le chemin complet sera /conf/wknd/settings/graphql/persistentQueries.
6. Appuyer Enregistrer pour enregistrer la nouvelle définition de module et fermer la boîte de dialogue.
7. Appuyez sur le bouton Build dans la définition de package nouvellement créée.

Une fois le module créé, vous pouvez :

• Télécharger le package et effectuez un nouveau chargement sur un autre environnement.
• Répliquer le module en appuyant sur Plus > Répliquer. Cela répliquera le module dans l’environnement de publication AEM connecté.

Ressources Business.Adobe.com