L’API GraphQL

GraphQL est :

  • «  …un langage de requête pour les API et un environnement d’exécution pour répondre à ces requêtes avec vos données existantes. GraphQL fournit une description complète et compréhensible des données de votre API, permet aux clients de demander exactement ce dont ils ont besoin et rien de plus, facilite l’évolution des API au fil du temps et donne accès à de puissants outils de développement.

    Voir GraphQL.org

  • «  …une spécification ouverte pour une couche d’API flexible. Placez GraphQL sur vos back-ends existants pour créer des produits plus rapidement que jamais…  ».

    Voir Explore GraphQL.

  • « … un langage et une spécification de requête de données développés en interne par Facebook en 2012 avant d’être rendus open source en 2015. C’est une alternative aux architectures basées sur REST destinée à accroître la productivité des développeurs et à réduire les quantités de données transférées. GraphQL est utilisé en production par des centaines d’entreprises de toutes tailles… »

    Voir GraphQL Foundation.

Pour plus d’informations sur l’API GraphQL, voir les sections suivantes (parmi de nombreuses autres ressources) :

La mise en œuvre GraphQL pour AEM repose sur la bibliothèque Java GraphQL standard. Voir :

Terminologie GraphQL

GraphQL utilise les éléments suivants :

Voir la Présentation de GraphQL (GraphQL.org) pour des détails complets, y compris les Bonnes pratiques.

Types de requêtes GraphQL

GraphQL permet de réaliser des requêtes pour renvoyer, au choix :

AEM fournit des fonctionnalités de conversion des requêtes (des deux types) en Requêtes persistantes, qui peuvent être mises en cache par Dispatcher et le réseau CDN.

Bonnes pratiques en matière de requêtes GraphQL (Dispatcher et réseau CDN)

Il est recommandé d’utiliser les Requêtes persistantes sur les instances de publication en raison des avantages suivants :

  • Elles sont mises en cache.
  • Elles sont gérées de manière centralisée par AEM as a Cloud Service.
NOTE
En règle générale, les instances de création ne possèdent pas de Dispatcher/réseau CDN. L’utilisation des requêtes persistantes n’offre donc aucun avantage, sauf à des fins de test.

Les requêtes GraphQL utilisant des requêtes POST ne sont pas recommandées, car elles ne sont pas mises en cache. Par conséquent, dans une instance par défaut, Dispatcher est configuré pour bloquer ces requêtes.

Bien que GraphQL prenne également en charge les requêtes GET, celles-ci peuvent atteindre des limites (par exemple, la longueur de l’URL) qui peuvent être évitées grâce aux Requêtes persistantes.

Voir Activer le cache des requêtes persistantes pour plus de détails.

NOTE
Pour autoriser les requêtes directes et/ou POST dans Dispatcher, vous pouvez demander à votre administrateur ou administratrice système de :
NOTE
Il se peut que la possibilité d’effectuer des requêtes directes devienne obsolète à un moment donné.

IDE GraphiQL

Vous pouvez tester et déboguer des requêtes GraphQL à l’aide de l’IDE GraphiQL.

Cas d’utilisation pour la création, la prévisualisation et la publication

Les cas d’utilisation peuvent dépendre du type d’environnement AEM as a Cloud Service :

  • Environnement de publication, utilisé pour :

    • Réaliser des requête de données pour l’application JS (cas d’utilisation standard)
  • Environnement de prévisualisation, utilisé pour :

    • Prévisualiser des requêtes avant le déploiement dans l’environnement de publication
      • Réaliser des requête de données pour l’application JS (cas d’utilisation standard)
  • Environnement de création, utilisé pour :

    • Réaliser des requêtes de données à des fins de gestion de contenu :

      • GraphQL dans AEM as a Cloud Service est actuellement une API en lecture seule.
      • L’API REST peut être utilisée pour les opérations CR(u)D.

Autorisations

Les autorisations sont celles requises pour accéder aux ressources.

Les requêtes GraphQL sont exécutées avec l’autorisation de l’utilisateur ou utilisatrice AEM de la requête sous-jacente. Si l’utilisateur ou l’utilisatrice ne dispose pas d’un accès en lecture à certains fragments (stockés en tant que ressources), ils ne feront pas partie du jeu de résultats.

En outre, l’utilisateur ou l’utilisatrice doit avoir accès à un point d’entrée GraphQL pour pouvoir exécuter des requêtes GraphQL.

Génération de schémas

GraphQL est une API fortement typée, ce qui signifie que les données doivent être clairement structurées et organisées par type.

La spécification GraphQL fournit une série de directives sur la création d’une API robuste pour interroger les données sur une certaine instance. Pour ce faire, un client doit récupérer le Schéma, qui contient tous les types nécessaires à une requête.

Pour les fragments de contenu, les schémas GraphQL (structure et types) reposent sur des Modèles de fragments de contenu activés et leurs types de données

CAUTION
Tous les schémas GraphQL (dérivés de modèles de fragments de contenu qui ont été activés) sont lisibles par le point d’entrée GraphQL.
En d’autres termes, vous devez vous assurer qu’aucune donnée sensible n’est disponible, car elle peut être divulguée de cette façon ; par exemple, cela concerne des informations qui peuvent être présentes sous forme de noms de champ dans la définition de modèle.

Par exemple, si un utilisateur ou une utilisatrice crée un modèle de fragment de contenu appelé Article, alors AEM génère un ArticleModel de type GraphQL. Les champs de ce type correspondent aux champs et aux types de données définis dans le modèle. AEM crée également des points d’entrée pour les requêtes qui opèrent sur ce type, comme articleByPath ou articleList.

  1. Un modèle de fragment de contenu :

    Modèle de fragment de contenu à utiliser avec GraphQL

  2. Le schéma GraphQL correspondant (sortie de la documentation automatique GraphiQL) :
    Schéma GraphQL basé sur le modèle de fragment de contenu

    Cela montre que le type généré ArticleModel contient plusieurs champs.

    • Trois d’entre eux ont été contrôlés par l’utilisateur : author, main et referencearticle.

    • Les autres champs ont été ajoutés automatiquement par AEM et représentent des méthodes utiles pour fournir des informations sur un certain fragment de contenu (dans cet exemple, les « champs d’aide » _path, _metadata et _variations).

  3. Après qu’un utilisateur a créé un fragment de contenu reposant sur le modèle d’article, il peut être interrogé via GraphQL. Vous trouverez des exemples à la section Exemples de Requêtes (basée sur un modèle de structure de fragment de contenu à utiliser avec GraphQL).

Dans GraphQL pour AEM, le schéma est flexible. Cela signifie qu’il est généré automatiquement à chaque fois qu’un modèle de fragment de contenu est créé, mis à jour ou supprimé. Les caches de schémas de données sont également actualisés lorsque vous mettez à jour un modèle de fragment de contenu.

Les caches de schémas de données sont également actualisés lorsque vous mettez à jour un modèle de fragment de contenu.

Le service Sites GraphQL écoute (en arrière-plan) toutes les modifications apportées à un modèle de fragment de contenu. Lorsque des mises à jour sont détectées, seule cette partie du schéma est régénérée. Cette optimisation permet de gagner du temps et d’apporter de la stabilité.

Par exemple, si vous :

  1. Installez un package contenant Content-Fragment-Model-1 et Content-Fragment-Model-2 :

    1. Les types GraphQL pour Model-1 et Model-2 sont générés.
  2. Puis modifiez Content-Fragment-Model-2 :

    1. Seul le type Model-2 GraphQL sera mis à jour.

    2. Alors que Model-1 restera le même.

NOTE
Il est important de le noter si vous souhaitez effectuer des mises à jour en bloc sur les modèles de fragments de contenu via l’API REST, ou autrement.

Le schéma est desservi par le même point d’entrée que les requêtes GraphQL, le client gérant le fait que le schéma est appelé avec l’extension GQLschema. Par exemple, l’exécution d’une requête GET simple sur /content/cq:graphql/global/endpoint.GQLschema entraîne la sortie du schéma avec le type de contenu : text/x-graphql-schema;charset=iso-8859-1.

Génération de schémas – Modèles dépubliés

Lorsque des fragments de contenu sont imbriqués, il se peut qu’un modèle de fragment de contenu parent soit publié, mais pas un modèle référencé.

NOTE
L’interface utilisateur d’AEM empêche cela, mais si la publication est effectuée par programmation ou avec des packages de contenu, elle peut être effectuée.

Dans ce cas, AEM génère un schéma incomplet pour le modèle de fragment de contenu parent. Cela signifie que la référence au fragment, qui dépend du modèle dépublié, est supprimée du schéma.

Champs

Le schéma comporte des champs individuels de deux catégories de base :

  • Champs que vous générez.

    Une sélection de types de données est utilisée pour créer des champs en fonction de la configuration du modèle de fragment de contenu. Les noms des champs proviennent du champ Nom de la propriété de l’onglet Type de données.

    • Prenez également en compte le paramètre Rendre en tant que, car les utilisateurs et utilisatrices peuvent configurer certains types de données. Par exemple, pour configurer un champ de texte monoligne afin de contenir plusieurs textes monolignes, choisissez multifield dans la liste déroulante.
  • GraphQL pour AEM génère également plusieurs champs d’assistance.