API AEM GraphQL à utiliser avec des fragments de contenu

Découvrez comment utiliser les fragments de contenu dans Adobe Experience Manager (AEM) as a Cloud Service avec l’API AEM GraphQL pour la diffusion de contenu en mode découplé.

L’API GraphQL d’AEM as a Cloud Service utilisée avec des fragments de contenu repose principalement sur l’API open source standard GraphQL.

L’utilisation de l’API GraphQL dans AEM permet la diffusion efficace de fragments de contenu aux clients JavaScript dans les implémentations CMS découplées :

• en évitant les demandes d’API itératives comme avec REST ;
• en veillant à ce que la diffusion soit limitée aux exigences spécifiques ;
• en permettant de diffuser en bloc exactement ce qui est nécessaire pour le rendu en réponse à une seule requête d’API.

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) :

• Sur graphql.org :

  • Présentation de GraphQL

  • La spécification GraphQL

• Sur graphql.com :

  • Guides

  • Tutoriels

  • Études de cas

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

• graphQL.org – Java

• GraphQL Java sur GitHub

Terminologie GraphQL

GraphQL utilise les éléments suivants :

• Requêtes

• Schémas et types :

  • Les schémas sont générés par AEM en fonction des modèles de fragment de contenu.
  • Grâce à vos schémas, GraphQL présente les types et les opérations autorisés pour l’implémentation de GraphQL pour AEM.

• Champs

• Point d’entrée GraphQL

  • Le chemin d’accès dans AEM qui répond aux requêtes GraphQL et permet d’accéder aux schémas GraphQL.

  • Voir Activation de votre point d’entrée GraphQL pour plus de détails.

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 :

• Une entrée unique

• Une liste d’entrées

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.

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 comportent des limites (par exemple, la longueur de l’URL) qui peuvent être évitées grâce aux requêtes persistantes.

IDE GraphiQL

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

Cas d’utilisation pour les environnements de création et de 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 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.

Création de schémas

GraphQL est une API dans laquelle 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. Un client doit pour cela récupérer le Schéma, qui contient tous les types nécessaires pour 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

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 :

   

2. Le schéma GraphQL correspondant (sortie de la documentation automatique GraphiQL) :
   

   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 seront 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.

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é.

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 un certain nombre de champs d’assistance.

Types de données

GraphQL pour AEM prend en charge une liste de types. Tous les types de données de modèles de fragments de contenu pris en charge et les types GraphQL correspondants sont représentés :

Champs d’assistance

Outre les types de données des champs générés par l’utilisateur, GraphQL pour AEM génère également un certain nombre de champs d’assistance afin de faciliter l’identification d’un fragment de contenu ou de fournir des informations supplémentaires sur un fragment de contenu.

Ces champs d’assistance sont précédés d’un _ pour distinguer ce qui a été défini par l’utilisateur ou l’utilisatrice de ce qui a été généré automatiquement.

Chemin d’accès

Le champ de chemin est utilisé comme identificateur dans AEM GraphQL. Il représente le chemin d’accès de la ressource de fragment de contenu dans le référentiel AEM. Nous l’avons choisi comme identificateur d’un fragment de contenu, car il :

• est unique dans AEM ;
• peut facilement être récupéré.

Le code suivant affiche les chemins de tous les fragments de contenu créés à partir du modèle de fragment de contenu Author, comme décrit dans le tutoriel WKND.

{
  authorList {
    items {
      _path
    }
  }
}

Pour récupérer un fragment de contenu unique d’un type spécifique, vous devez commencer par déterminer son chemin d’accès. Par exemple :

{
  authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
    item {
      _path
      firstName
      lastName
    }
  }
}

Voir Exemple de requête – Un fragment de ville unique et spécifique.

Métadonnées

Par le biais de GraphQL, AEM expose également les métadonnées d’un fragment de contenu. Les métadonnées sont les informations qui décrivent un fragment de contenu, comme le titre d’un fragment de contenu, le chemin d’accès à la miniature, la description d’un fragment de contenu, la date de création, etc.

Les métadonnées étant générées par l’éditeur de schémas et n’ayant donc pas de structure spécifique, le type TypedMetaData GraphQL a été implémenté pour exposer les métadonnées d’un fragment de contenu. TypedMetaData expose les informations regroupées selon les types scalaires suivants :

Chaque type scalaire représente soit une paire nom-valeur unique, soit un tableau de paires nom-valeur, où la valeur d’une paire est du type dans lequel elle a été regroupée.

Par exemple, si vous souhaitez récupérer le titre d’un fragment de contenu, nous savons que cette propriété est une propriété Chaîne et recherchons donc toutes les métadonnées Chaîne :

Pour rechercher des métadonnées :

{
  authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
    item {
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

Vous pouvez afficher tous les types GraphQL de métadonnées si vous affichez le schéma GraphQL généré. Tous les types de modèle ont le même TypedMetaData.

Voir Modèle de recherche de métadonnées – Répertorier les métadonnées des prix intitulés GB.

Variations

Le champ _variations a été implémenté pour simplifier la recherche de variations d’un fragment de contenu. Par exemple :

{
  authorByPath(_path: "/content/dam/wknd-shared/en/contributors/ian-provo") {
    item {
      _variations
    }
  }
}

Voir Modèle de requête – Toutes les villes avec une variante nommée.

Variables GraphQL

GraphQL permet de placer des variables dans la requête. Pour plus d’informations, voir la documentation GraphQL des Variables.

Par exemple, pour obtenir tous les fragments de contenu de type Author dans une variation spécifique (si disponible), vous pouvez spécifier l’argument variation dans GraphiQL.

Requête :

query($variation: String!) {
  authorList(variation: $variation) {
    items {
      _variation
      lastName
      firstName
    }
  }
}

Variables de requête :

{
  "variation": "another"
}

Cette requête renverra la liste complète des auteurs. Les auteurs qui n’ont pas la variation another reviendront aux données d’origine (_variation indiquera master dans ce cas).

Si vous souhaitez limiter la liste aux auteurs qui présentent la variation spécifiée (et ignorer ceux qui reviendraient aux données d’origine), vous devez appliquer un filtre :

query($variation: String!) {
  authorList(variation: $variation, filter: {
    _variation: {
      _expressions: {
        value: $variation
      }
    }
  }) {
    items {
      _variation
      lastName
      firstName
    }
  }
}

Directives GraphQL

Dans GraphQL, il est possible de modifier la requête en fonction de variables, nommées directives GraphQL.

Par exemple, vous pouvez inclure ici le champ adventurePrice dans une requête pour tous les AdventureModels, en fonction d’une variable includePrice.

Requête :

query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      title
      price @include(if: $includePrice)
    }
  }
}

Variables de requête :

{
    "includePrice": true
}

Filtrage

Vous pouvez également utiliser le filtrage dans vos requêtes GraphQL pour renvoyer des données spécifiques.

Le filtrage utilise une syntaxe basée sur des expressions et des opérateurs logiques.

La partie la plus atomique est une expression unique qui peut être appliquée au contenu d’un certain champ. Il compare le contenu du champ avec une valeur constante donnée.

Par exemple, l’expression

{
  value: "some text"
  _op: EQUALS
}

compare le contenu du champ à la valeur some text et réussit si le contenu est égal à la valeur. Dans le cas contraire, l’expression échouera.

Les opérateurs suivants peuvent être utilisés pour comparer les champs à une certaine valeur :

Certains types permettent également de spécifier des options supplémentaires qui modifient la manière dont une expression est évaluée :

Les expressions peuvent être combinées à un jeu à l’aide d’un opérateur logique (_logOp) :

• OR : le jeu d’expressions réussit si au moins une expression réussit.
• AND : le jeu d’expressions réussit si toutes les expressions réussissent (par défaut).

Chaque champ peut être filtré par son propre jeu d’expressions. Les jeux d’expressions de tous les champs mentionnés dans l’argument de filtre seront finalement combinés par leur propre opérateur logique.

Une définition de filtre (transmise comme l’argument filter dans une requête) contient les éléments suivants :

• Une sous-définition pour chaque champ (le champ est accessible via son nom, par exemple il y a un champ lastName dans le filtre pour le champ lastName dans le type de données (champ)).
• Chaque sous-définition contient le tableau _expressions, qui fournit le jeu d’expressions, ainsi que le champ _logOp, qui définit l’opérateur logique avec lequel les expressions doivent être combinées.
• Chaque expression est définie par la valeur (champ value) et l’opérateur (champ _operator) auxquels le contenu d’un champ doit être comparé.

Notez que vous pouvez omettre l’opérateur _logOp si vous souhaitez combiner des éléments avec AND, ainsi que l’opérateur _operator si vous souhaitez vérifier l’égalité, car il s’agit des valeurs par défaut.

L’exemple suivant illustre une requête complète qui filtre toutes les personnes dont le lastName est Provo ou contenant sjö, quel que soit le cas :

{
  authorList(filter: {
    lastname: {
      _logOp: OR
      _expressions: [
        {
          value: "sjö",
          _operator: CONTAINS,
          _ignoreCase: true
        },
        {
          value: "Provo"
        }
      ]
    }
  }) {
    items {
      lastName
      firstName
    }
  }
}

Il n’est pas recommandé de filtrer les champs imbriqués (bien que cela soit possible), car cela peut entraîner des problèmes de performances.

Pour accéder à d’autres exemples, voir :

• détails des extensions GraphQL pour AEM

• Modèles de requêtes utilisant ce modèle de contenu et de structure

  • Et Modèle de contenu et de structure préparé pour une utilisation dans des modèles de requêtes

• Modèles de requêtes basées sur le projet WKND

Tri

Cette fonctionnalité vous permet de trier les résultats de la requête en fonction d’un champ spécifié.

Les critères de tri sont les suivants :

• il s’agit d’une liste de valeurs séparées par des virgules représentant le chemin du champ,
  • le premier champ de la liste définit l’ordre de tri principal, le second est utilisé si deux valeurs du critère de tri principal sont égales, le troisième si les deux premiers critères sont égaux, etc.
  • valeur séparée par des points, c’est-à-dire field1.subfield.subfield, etc.
• avec un sens d’ordre optionnel,
  • ASC (croissant) ou DESC (décroissant) ; la valeur par défaut est ASC,
  • le sens d’ordre peut être spécifié par champ : vous pouvez trier un champ par ordre croissant et un autre par ordre décroissant (name, firstName DESC).

Par exemple :

query {
  authorList(sort: "lastName, firstName") {
    items {
      firstName
      lastName
    }
  }
}

Un autre exemple :

{
  authorList(sort: "lastName DESC, firstName DESC") {
    items {
        lastName
        firstName
    }
  }
}

Vous pouvez également trier un champ dans un fragment imbriqué au format nestedFragmentname.fieldname.

Par exemple :

query {
  articleList(sort: "authorFragment.lastName")  {
    items {
      title
      authorFragment {
        firstName
        lastName
        birthDay
      }
      slug
    }
  }
}

Pagination

Cette fonctionnalité vous permet d’effectuer une pagination sur les types de requête qui renvoient une liste. Deux méthodes sont proposées :

• offset et limit dans une requête List
• first et after dans une requête Paginated

Requête de liste : « offset » et « limit »

Dans une requête ...List, vous pouvez utiliser offset et limit pour renvoyer un sous-ensemble spécifique de résultats :

• offset : spécifie le premier jeu de données à renvoyer.
• limit : spécifie le nombre maximal de jeux de données à renvoyer.

Par exemple, pour obtenir la page de résultats contenant jusqu’à cinq articles, en commençant par le cinquième article de la liste complète des résultats, effectuez l’opération suivante :

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}

Requête paginée : « first » et « after »

Le type de requête ...Paginated utilise la plupart des fonctionnalités du type de requête ...List (filtrage et tri), mais au lieu d’utiliser les arguments offset/limit, il utilise les arguments first/after tels que définis dans la Spécification des connexions basées sur le curseur GraphQL. Consultez une introduction moins formelle dans la Présentation de GraphQL.

• first : les n premiers éléments à renvoyer.
  La valeur par défaut est 50.
  La valeur maximale est 100.
• after : le curseur qui détermine le début de la page demandée. Notez que l’élément représenté par le curseur n’est pas inclus dans le jeu de résultats. Le curseur d’un élément est déterminé par le champ cursor de la structure edges.

Par exemple, vous pouvez afficher la page des résultats contenant jusqu’à cinq aventures, à partir de l’élément donné du curseur dans la liste complète des résultats :

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}

GraphQL pour AEM – Résumé des extensions

Le fonctionnement de base des requêtes avec GraphQL pour AEM est conforme à la spécification GraphQL standard. Pour les requêtes GraphQL avec AEM, il existe quelques extensions :

• Si vous prévoyez une liste de résultats :

  • Ajoutez List au nom du modèle ; par exemple, cityList
  • Voir Exemple de requête – Toutes les informations sur toutes les villes

  Vous pouvez ensuite :

  • Trier les résultats

    • ASC : croissant
    • DESC : décroissant

  • Renvoyer une page de résultats à l’aide de l’une des méthodes suivantes :

    • Une requête de liste utilisant offset et limit
    • Une requête paginée utilisant first and after.

  • Voir Exemple de requête – Toutes les informations sur toutes les villes.

• Si vous avez besoin d’un seul résultat :

  • Utilisez le nom du modèle ; p. ex. city.

• Si vous prévoyez une liste de résultats :

  • Ajoutez List au nom du modèle ; par exemple, cityList
  • Voir Exemple de requête – Toutes les informations sur toutes les villes

• Si vous souhaitez utiliser un OU logique :

  • Utilisez _logOp: OR
  • Voir Exemple de requête – Toutes les personnes qui portent le nom « Jobs » ou « Smith »

• L’opérateur logique ET existe également, mais est (souvent) implicite

• Vous pouvez appliquer des requêtes aux noms de champ qui correspondent aux champs du modèle de fragment de contenu.

  • Voir Exemple de requête – Détails complets relatifs au PDG et aux employés d’une entreprise

• Outre les champs de votre modèle, il existe certains champs générés par le système (précédés d’un trait de soulignement) :

  • Pour le contenu :

    • _locale : pour afficher la langue ; basé sur Language Manager

      • Voir Exemple de requête pour plusieurs fragments de contenu d’un paramètre régional donné

    • _metadata : pour afficher les métadonnées de votre fragment

      • Voir Modèle de recherche de métadonnées – Répertorier les métadonnées des prix intitulés GB

    • _model : autoriser l’interrogation d’un modèle de fragment de contenu (chemin et titre)

      • Voir Exemple de requête pour un modèle de fragment de contenu à partir d’un modèle

    • _path : chemin d’accès au fragment de contenu dans le référentiel.

      • Voir Exemple de requête – Un fragment de ville unique et spécifique

    • _reference : pour afficher les références ; y compris les références intégrées dans l’éditeur de texte enrichi

      • Voir Exemple de requête pour plusieurs fragments de contenu avec des références préalablement récupérées

    • _variation : pour afficher des variantes spécifiques dans votre fragment de contenu

      REMARQUE

      Si la variation donnée n’existe pas pour un fragment de contenu, la variation principale est renvoyée comme valeur (de secours) par défaut.

      • Voir Exemple de requête – Toutes les villes avec une variante nommée

  • Et les opérations :

    • _operator : pour appliquer des opérateurs spécifiques ; EQUALS, EQUALS_NOT, GREATER_EQUAL, LOWER, CONTAINS, STARTS_WITH
      • Voir Exemple de requête – Toutes les personnes qui ne portent pas le nom « Jobs »
      • Voir Exemple de requête – Toutes les aventures où _path commence par un préfixe spécifique
    • _apply : pour appliquer des conditions spécifiques ; par exemple AT_LEAST_ONCE
      • Voir Exemple de requête : effectuer un filtrage sur un tableau avec un élément qui doit se produire au moins une fois
    • _ignoreCase : pour ignorer la casse lors de l’application de la requête
      • Voir Exemple de requête : toutes les villes dont le nom contient SAN, indépendamment de la casse

• Les types d’union GraphQL sont pris en charge :

  • Utilisez ... on
    • Voir Exemple de requête pour un fragment de contenu d’un modèle spécifique avec une référence de contenu

• Secours lors de l’interrogation de fragments imbriqués :

  • Si une variation donnée n’existe pas dans un fragment imbriqué, la variation Principal est renvoyée.

Requête du point d’entrée GraphQL à partir d’un site web externe

Pour accéder au point d’entrée GraphQL à partir d’un site web externe, vous devez configurer les éléments suivants :

• Filtre CORS
• Filtre Référent

Authentification

Voir Authentification pour les requêtes distantes AEM GraphQL sur les fragments de contenu.

FAQ

Questions soulevées :

1. Q : « En quoi l’API GraphQL pour AEM est-elle différente de l’API Query Builder ? »

   • R : « L’API AEM GraphQL offre un contrôle total sur la sortie JSON et est une norme du secteur pour les requêtes de contenu.
     AEM prévoit d’investir dans l’API AEM GraphQL. »

Tutoriel – Prise en main d’AEM découplé et de GraphQL

Vous cherchez un tutoriel pratique ? Consultez le tutoriel complet Prise en main d’AEM découplé et de GraphQL illustrant comment créer et exposer du contenu à l’aide des API GraphQL d’AEM et consommé par une application externe, dans un scénario CMS découplé.

Ressources Business.Adobe.com