API GraphQL d’AEM à utiliser avec des fragments de contenu

Découvrez comment utiliser des fragments de contenu dans Adobe Experience Manager (AEM) en tant que Cloud Service avec l’API AEM GraphQL pour la diffusion de contenu sans interface.

AEM en tant qu’API GraphQL de Cloud Service utilisée avec les fragments de contenu repose principalement sur l’API GraphQL Open Source standard.

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

  • 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.
REMARQUE

GraphQL est actuellement utilisé dans deux scénarios (distincts) dans Adobe Experience Manager (AEM) as a Cloud Service :

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 :

Vous pouvez également effectuer les opérations suivantes :

REMARQUE

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

Point d’entrée GraphQL pour AEM

Le point d’entrée est le chemin utilisé pour accéder à GraphQL pour AEM. Avec ce chemin, vous (ou votre application) pouvez :

  • accéder au schéma GraphQL ;
  • envoyer vos requêtes GraphQL ;
  • recevoir les réponses (à vos requêtes GraphQL).

Il existe deux types de points de terminaison dans AEM :

  • Global
    • Disponible pour tous les sites.
    • Ce point de terminaison peut utiliser tous les modèles de fragment de contenu de toutes les configurations Sites (définis dans le navigateur de configuration).
    • S’il existe des modèles de fragment de contenu qui doivent être partagés entre les configurations Sites, ils doivent être créés sous les configurations Sites globales.
  • Configurations de sites :
    • Correspond à une configuration Sites, comme défini dans le navigateur de configuration.
    • Spécifique à un site/projet spécifique.
    • Un point de terminaison spécifique à la configuration Sites utilisera les modèles de fragment de contenu de cette configuration Sites spécifique, ainsi que ceux de la configuration Sites globale.
ATTENTION

L’éditeur de fragment de contenu peut permettre à un fragment de contenu d’une configuration Sites de référencer un fragment de contenu d’une autre configuration Sites (via des stratégies).

Dans ce cas, tout le contenu ne peut pas être récupéré à l’aide d’un point de terminaison spécifique à la configuration Sites.

L’auteur du contenu doit contrôler ce scénario ; par exemple, il peut s’avérer utile de placer des modèles de fragment de contenu partagés sous la configuration de sites globaux.

Le chemin d’accès au référentiel de GraphQL pour AEM point d’entrée global est le suivant :

/content/cq:graphql/global/endpoint

Pour lequel votre application peut utiliser le chemin d’accès suivant dans l’URL de requête :

/content/_cq_graphql/global/endpoint.json

Pour activer un point de terminaison pour GraphQL pour AEM, vous devez :

Activation de votre point d’entrée GraphQL

Pour activer un point d’entrée GraphQL, vous devez d’abord disposer d’une configuration appropriée. Voir Fragments de contenu - Explorateur de configuration.

ATTENTION

Pour activer le point de terminaison correspondant :

  1. Accédez à Outils, Ressources, puis sélectionnez GraphQL.

  2. Sélectionnez Créer.

  3. La boîte de dialogue Créer un point d’entrée GraphQL s’ouvre. Vous pouvez y indiquer les informations suivantes :

    • Nom : nom du point de terminaison ; vous pouvez saisir du texte.
    • Utilisez le schéma GraphQL fourni par : utilisez la liste déroulante pour sélectionner le site/projet requis.
    REMARQUE

    L’avertissement suivant s’affiche dans la boîte de dialogue :

    • Les points d'entrée GraphQL peuvent présenter des problèmes de sécurité et de performances des données s'ils ne sont pas gérés de manière adaptée. Veillez à définir les autorisations appropriées après la création d'un point d'entrée.
  4. Confirmez avec Créer.

  5. La boîte de dialogue Étapes suivantes fournit un lien direct vers la console de sécurité afin que vous puissiez vous assurer que le nouveau point de terminaison dispose des autorisations appropriées.

    ATTENTION

    Le point d’entrée est accessible à tous. Cela peut entraîner un problème de sécurité, en particulier pour les instances de publication, car les requêtes GraphQL peuvent imposer une charge importante au serveur.

    Vous pouvez configurer des listes de contrôle d’accès pour le point d’entrée en fonction de votre cas d’utilisation.

Publication de votre point d’entrée GraphQL

Sélectionnez le nouveau point de terminaison et Publier pour le rendre entièrement disponible dans tous les environnements.

ATTENTION

Le point d’entrée est accessible à tous.

Sur les instances de publication, cela peut poser un problème de sécurité, car les requêtes GraphQL peuvent imposer une charge importante sur le serveur.

Vous devez configurer des listes de contrôle d’accès adaptées à votre cas d’utilisation sur le point de terminaison .

Interface GraphiQL

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

REMARQUE

GraphiQL est lié au point de terminaison global (et ne fonctionne pas avec d’autres points de terminaison pour des configurations Sites spécifiques).

Elle permet de saisir et tester directement les requêtes.

Par exemple :

  • http://localhost:4502/content/graphiql.html

Vous disposez de 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 :

Interface GraphiQL

Installation de l’interface AEM GraphiQL

L’interface utilisateur de GraphiQL peut être installée sur AEM avec un package dédié : le module GraphiQL Content Package v0.0.6 (2021.3).

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.

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

ATTENTION

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 a créé un modèle de fragment de contenu nommé Article, AEM génère l’objet article de type ArticleModel. Les champs de ce type correspondent aux champs et aux types de données définis dans le modèle.

  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, _path, _metadata et _variations. Ces champs d’assistance sont précédés d’un _ pour distinguer ce qui a été défini par l’utilisateur de ce qui a été généré automatiquement.

  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.

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.

REMARQUE

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

REMARQUE

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

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 non 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 champs 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é du Type de données.

    • Il faut également tenir compte de la propriété Rendre comme, car les utilisateurs peuvent configurer certains types de données, par exemple comme une seule ligne de texte ou avec plusieurs champs.
  • GraphQL pour AEM génère également un certain nombre de champs d’assistance.

    Ils servent à identifier un fragment de contenu ou à obtenir plus d’informations sur un fragment.

Types de champs

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 :

Modèle de fragment de contenu – Type de données Type GraphQL Description
Texte sur une seule ligne Chaîne, [Chaîne] Utilisé pour les chaînes simples telles que les noms d’auteurs, les noms d’emplacements, etc…
Texte multi-lignes Chaîne Utilisé pour la sortie de texte, tel que le corps d’un article
Nombre Flottant, [Flottant] Utilisé pour afficher le nombre à virgule flottante et les nombres réguliers
Booléen Booléen Utilisé pour afficher les cases à cocher → simples instructions vrai/faux
Date et heure Calendrier Utilisé pour afficher la date et l’heure au format ISO 8086 : Selon le type sélectionné, trois versions sont disponibles dans AEM GraphQL : onlyDate, onlyTime, dateTime
Énumération Chaîne Utilisé pour afficher une option à partir d’une liste d’options définies lors de la création du modèle
Balises [Chaîne] Utilisé pour afficher une liste de chaînes représentant les balises utilisées dans AEM
Référence de contenu Chaîne Utilisé pour afficher le chemin vers une autre ressource dans AEM
Référence du fragment Un type de modèle Utilisé pour référencer un autre fragment de contenu d’un certain type de modèle, défini lors de la création du modèle

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.

Chemin

Le champ de chemin est utilisé comme identificateur dans 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 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 :

{
  personByPath(_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

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 :

Champ
stringMetadata:[StringMetadata]!
stringArrayMetadata:[StringArrayMetadata]!
intMetadata:[IntMetadata]!
intArrayMetadata:[IntArrayMetadata]!
floatMetadata:[FloatMetadata]!
floatArrayMetadata:[FloatArrayMetadata]!
booleanMetadata:[BooleanMetadata]!
booleanArrayMetadata:[booleanArrayMetadata]!
calendarMetadata:[CalendarMetadata]!
calendarArrayMetadata:[CalendarArrayMetadata]!

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 :

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

REMARQUE

Différence entre les métadonnées normales et les métadonnées de tableau
Gardez à l’esprit que StringMetadata et StringArrayMetadata se rapportent tous deux à ce qui est stocké dans le référentiel et non à la façon dont vous les récupérez.

Par exemple, en appelant le champ stringMetadata, vous recevriez un tableau de toutes les métadonnées stockées dans le référentiel comme String et en appelant stringArrayMetadata, vous recevriez un tableau de toutes les métadonnées stockées dans le référentiel comme String[].

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 :

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    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 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.

Variables GraphQL

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
        }
    }
}
 
### in query variables
{
    "variation": "uk"
}

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.

Directives GraphQL

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}
 
### in query variables
{
    "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.

Par exemple, la requête (de base) suivante filtre toutes les personnes dont le nom est Jobs ou Smith :

query {
  personList(filter: {
    name: {
      _logOp: OR
      _expressions: [
        {
          value: "Jobs"
        },
        {
          value: "Smith"
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

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

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 :

Requêtes conservées (cache)

Après avoir préparé une requête avec une requête POST, elle peut être exécutée avec une requête GET qui peut être mise en cache par des caches HTTP ou un réseau CDN.

Cela est nécessaire, car les requêtes POST ne sont généralement pas mises en cache et si vous utilisez GET avec la requête comme paramètre, il existe un risque important que le paramètre devienne trop volumineux pour les services et intermédiaires HTTP.

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

  • Configuration globale et point de terminaison
    La requête a accès à tous les modèles de fragment de contenu.
  • Configuration(s) de sites spécifiques et point(s) de fin
    La création d’une requête persistante pour une configuration Sites spécifique nécessite un point de terminaison 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 de sites WKND, une configuration de sites spécifique à WKND correspondante et un point de terminaison spécifique à WKND doivent être créés à l’avance.
REMARQUE

Voir Activation de la fonctionnalité de fragment de contenu dans le navigateur de configuration pour plus d’informations.

Les Requêtes de persistance GraphQL doivent être activées pour la configuration Sites appropriée.

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 de terminaison 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 de terminaison global, mais la requête sera enregistrée comme suit :
    /conf/global/settings/graphql/persistentQueries/my-query
REMARQUE

Il s’agit de deux requêtes différentes, enregistrées sous des chemins différents.

Il se trouve qu'ils utilisent le même modèle - mais via différents points de terminaison.

Vous trouverez ci-dessous les étapes nécessaires à la conservation d’une requête donnée :

  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 conservée 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
            }
          }
        }
      }'
    
  8. Exécution d’une requête avec des paramètres.

    Par exemple :

    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
    $ curl -X GET \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
  9. Pour exécuter la requête lors de la publication, l’arborescence persistante associée doit être répliquée.

    • Utilisation d’un POST pour la réplication :

      $curl -X POST   http://localhost:4502/bin/replicate.json \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -F path=/conf/wknd/settings/graphql/persistentQueries/plain-article-query \
        -F cmd=activate
      
    • Utilisation d’un module :

      1. Créez une définition de module.
      2. Incluez la configuration (par exemple, /conf/wknd/settings/graphql/persistentQueries).
      3. Créez le module.
      4. Répliquez le module.
    • Utilisation de l’outil de réplication/distribution.

      1. Accédez à l’outil Distribution.
      2. Sélectionnez l’activation de l’arborescence pour la configuration (par exemple, /conf/wknd/settings/graphql/persistentQueries).
    • Utilisation d’un workflow (via la configuration du lanceur de workflow) :

      1. Définissez une règle de lancement de workflow pour exécuter un modèle de workflow qui répliquerait la configuration sur différents événements (par exemple, créer, modifier, entre autres).
  10. Une fois que la configuration de la requête est publiée, les mêmes principes s’appliquent, en utilisant simplement le point d’entrée de publication.

    REMARQUE

    Pour un accès anonyme, le système suppose que l’ACL permet à « tout le monde » d’avoir accès à la configuration de la requête.

    Si ce n’est pas le cas, l’exécution sera impossible.

    REMARQUE

    Les points-virgules (;) des URL doivent être codés.

    Par exemple, comme dans la demande d’exécution d’une requête persistante :

    curl -X GET \ "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters%3bapath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    

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

REMARQUE

Pour un aperçu détaillé de la politique de partage des ressources CORS dans AEM, voir Description du partage des ressources Cross-Origin (CORS).

Pour accéder au point d’entrée GraphQL, une stratégie CORS doit être configurée dans le référentiel Git du client. Vous devez pour cela ajouter un fichier de configuration CORS OSGi approprié pour le ou les points 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 au point d’entrée de 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

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 :

  • spécifie un nom d’hôte de site web approuvé ; soit allow.hosts, soit allow.hosts.regexp,
  • accorde l’accès pour ce nom d’hôte.

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":[
      ""
    ]
}
ATTENTION

Il incombe au client de :

  • n’accorder l’accès qu’aux domaines approuvés ;
  • s’assurer qu’aucune information sensible n’est exposée
  • ne pas utiliser la syntaxe de caractère générique [*] ; cette méthode désactive à la fois l’accès authentifié au point d’entrée GraphQL et l’expose par ailleurs vis-à-vis du monde entier.
ATTENTION

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.

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 GraphQL d’AEM 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 GraphQL d’AEM.
       »

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

Sur cette page