API AEM GraphQL pour l’utilisation des fragments de contenu graphql-api-for-use-with-content-fragments

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

L’API GraphQL AEM 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 :

Conditions préalables prerequisites

Les et clientes et clients qui utilisent GraphQL doivent installer le fragment de contenu AEM avec le package d’index GraphQL 1.0.5. Voir les notes de mise à jour pour plus de détails.

L’API GraphQL graphql-api

GraphQL est :

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-terminology

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-query-types

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 sont mises en cache par Dispatcher et le réseau CDN.

Bonnes pratiques en matière de requêtes GraphQL (Dispatcher et réseau CDN) graphql-query-best-practices

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

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.

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

Interface GraphiQL graphiql-interface

Une implémentation de l’interface standard GraphiQL est disponible pour être utilisée avec AEM GraphQL.

Cette interface vous permet de saisir et tester directement les requêtes.

Par exemple :

Elle vous offre des fonctionnalités telles que la mise en surbrillance de la syntaxe, la saisie semi-automatique et la suggestion automatique, ainsi qu’un historique et une documentation en ligne:

Cas d’utilisation pour les environnements de création et de publication use-cases-author-publish-environments

Les cas d’utilisation peuvent dépendre du type d’environnement AEM :

Autorisations permission

Les autorisations sont 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 schema-generation

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. Pour compléter ces directives, un client doit 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.

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.

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 :

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 schema-generation-unpublished-models

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 fields

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

Types de données data-types

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’assistant helper-fields

Outre les types de données des champs générés par l’utilisateur ou l’utilisatrice, GraphQL pour AEM génère également plusieurs champs d’assistant 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 path

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. Ce chemin d’accès est choisi comme identifiant d’un fragment de contenu, car il :

Le code suivant affiche les chemins d’accés de tous les fragments de contenu créés à partir du modèle de fragment de contenu Person.

{
  personList {
    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/path/to/fragment/john-doe") {
    item {
      _path
      firstName
      name
    }
  }
}

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

Métadonnées metadata

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, telles que :

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. Le 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, cette propriété est une propriété Chaîne et vous devez donc rechercher toutes les métadonnées Chaîne :

Pour rechercher des métadonnées :

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      _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 Exemple de requête pour les métadonnées – Répertorier les métadonnées des prix intitulés GB.

Variations variations

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

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _variations
    }
  }
}

Voir Exemple de requête – Toutes les villes avec une variation nommée.

Variables GraphQL graphql-variables

GraphQL permet de placer des variables dans la requête. Pour plus d’informations, voir Documentation GraphQL pour les variables.

Par exemple, pour obtenir tous les fragments de contenu de type Article qui présentent une variation spécifique, vous pouvez spécifier la variable variation dans GraphiQL.

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
            _variations
        }
    }
}

### in query variables
{
    "variation": "uk"
}

Directives GraphQL graphql-directives

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.

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}

### in query variables
{
    "includePrice": true
}

Filtrage filtering

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 suivante 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 échoue :

{
  value: "some text"
  _op: EQUALS
}

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

Certains types vous 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) :

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 :

Vous pouvez omettre _logOp si vous souhaitez combiner des éléments avec AND et _operator si vous souhaitez vérifier l’égalité, car il s’agit de 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
    }
  }
}

Lors de l’exécution d’une requête GraphQL à l’aide de variables facultatives, si une valeur spécifique n’est pas fournie pour la variable facultative, la variable est alors ignorée dans l’évaluation du filtre. Cela signifie que les résultats de la requête contiendront toutes les valeurs, les deux null et non null, pour la propriété associée à la variable de filtre.

Par exemple, dans la requête ci-dessous, où aucune valeur n’est spécifiée pour la propriété lastName :

query getAuthorsFilteredByLastName($authorLastName: String) {
  authorList(filter:
    {
      lastName: {_expressions: {value: $authorLastName}
      }}) {
    items {
      lastName
    }
  }
}

Toutes les instances de création seront renvoyées :

{
  "data": {
    "authorList": {
      "items": [
        {
          "lastName": "Hammer"
        },
        {
          "lastName": "Provo"
        },
        {
          "lastName": "Wester"
        },
        {
          "lastName": null
        },
         ...
      ]
    }
  }
}

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 :

Tri sorting

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 :

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 paging

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

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

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

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 » paginated-first-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.

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

Requêtes persistantes GraphQL - Activation de la mise en cache dans Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

La mise en cache des requêtes persistantes n’est pas activée par défaut dans Dispatcher. L’activation par défaut n’est pas possible, car les clients ou clientes qui utilisent le partage de ressources entre origines multiples (CORS) doivent examiner et éventuellement mettre à jour la configuration de Dispatcher.

Activer la mise en cache des requêtes persistantes enable-caching-persisted-queries

Pour activer la mise en cache des requêtes persistantes, les mises à jour suivantes des fichiers de configuration de Dispatcher sont requises :

Configuration CORS dans Dispatcher cors-configuration-in-dispatcher

Les clients et les clientes qui utilisent des requêtes CORS doivent peut-être passer en revue et mettre à jour leur configuration CORS dans Dispatcher.

GraphQL pour AEM – Résumé des extensions graphql-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 :

Filtre CORS cors-filter

Pour accéder au point d’entrée GraphQL, configurez une politique CORS dans le référentiel Git du client. Cette configuration est effectuée en ajoutant un fichier de configuration OSGi CORS approprié pour un ou plusieurs points de d’entrée souhaités.

Cette configuration doit spécifier une origine de site web approuvée alloworigin ou alloworiginregexp pour laquelle l’accès doit être accordé.

Par exemple, pour accorder l’accès au point d’entrée GraphQL et aux requêtes persistantes pour https://my.domain, vous pouvez utiliser :

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

Si vous avez configuré un chemin d’accès Vanity pour le point d’entrée, vous pouvez également l’utiliser dans allowedpaths.

Filtre Référent referrer-filter

Outre la configuration CORS, un filtre Référent doit être configuré pour autoriser l’accès à partir d’hôtes tiers.

Pour ce faire, ajoutez un fichier de configuration de filtre Référent OSGi approprié qui :

Par exemple, pour accorder l’accès aux requêtes avec le référent my.domain, vous pouvez :

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}

Limites limitations

Pour vous protéger contre les problèmes potentiels, vos requêtes sont soumises à des limitations par défaut :

À savoir également :

Authentification authentication

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

FAQ faqs

Questions soulevées :

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

Vous cherchez un tutoriel pratique ? Consultez le tutoriel complet Prise en main d’AEM Headless 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é.