Prise en charge des fragments de contenu dans l’API HTTP AEM Assets

Présentation

Découvrez la prise en charge des fragments de contenu dans l’API HTTP Assets, un élément important de la fonctionnalité de diffusion d’AEM découplé.

L’API REST Assets permet aux développeurs d’Adobe Experience Manager as a Cloud Service d’accéder au contenu (stocké dans AEM) directement via l’API HTTP, via des opérations CRUD (création, lecture, mise à jour et suppression).

L’API permet d’utiliser Adobe Experience Manager as a Cloud Service en tant que système de gestion de contenu (CMS) sans interface utilisateur en fournissant des services de contenu à une application frontale JavaScript. Ou toute autre application pouvant exécuter des requêtes HTTP et gérer les réponses JSON.

Par exemple, les applications sur une seule page, basées sur la structure ou personnalisées, nécessitent du contenu fourni via l’API HTTP, souvent au format JSON.

Bien que les composants de base AEM fournissent une API très complète, flexible et personnalisable pouvant traiter les opérations de lecture requises à cette fin, et dont la sortie JSON peut être personnalisée, ils ne nécessitent pas de connaissances sur AEM WCM (Web Content Management) pour la mise en œuvre, car ils doivent être hébergés sur des pages reposant sur des modèles AEM dédiés. Les entreprises de développement d’applications sur une seule page n’ont pas toutes accès à ces connaissances.

Dans ce cas, l’API REST Assets peut être utilisée. Elle permet aux développeurs d’accéder à des ressources (par exemple, des images et des fragments de contenu) directement, sans devoir d’abord les intégrer dans une page puis diffuser leur contenu au format JSON sérialisé.

L’API REST Assets permet également aux développeurs de modifier du contenu, en créant, en mettant à jour ou en supprimant des ressources, des fragments de contenu et des dossiers.

L’API REST Assets :

• suit le principe HATEOAS

• met en œuvre le format SIREN

Conditions préalables

L’API REST Assets est disponible pour chaque installation prête à l’emploi d’une version récente d’Adobe Experience Manager as a Cloud Service.

Concepts clés

L’API REST Assets offre un accès de type REST aux ressources stockées dans une instance AEM.

Elle utilise le point d’entrée /api/assets et requiert le chemin d’accès de la ressource pour y accéder (sans /content/dam qui précède).

• Cela signifie que pour accéder à la ressource à l’adresse suivante :
  • /content/dam/path/to/asset
• Vous devez demander :
  • /api/assets/path/to/asset

Par exemple, pour accéder à /content/dam/wknd/en/adventures/cycling-tuscany, demandez /api/assets/wknd/en/adventures/cycling-tuscany.json

La méthode HTTP détermine l’opération à exécuter :

• GET : pour récupérer une représentation JSON d’une ressource ou d’un dossier
• POST : pour créer des ressources ou des dossiers
• PUT : pour mettre à jour les propriétés d’une ressource ou d’un dossier
• DELETE : pour supprimer une ressource ou un dossier

Le format exact des requêtes prises en charge est défini dans la variable Référence d’API documentation.

Comportement transactionnel

Toutes les requêtes sont atomiques.

Cela signifie que les requêtes suivantes (write) ne peuvent pas être combinées en une seule transaction pouvant aboutir ou échouer en tant qu’entité unique.

API REST AEM (Assets) et composants AEM

Sécurité

Si l’API REST Assets est utilisée dans un environnement sans conditions d’authentification spécifiques, le filtre CORS d’AEM doit être configuré correctement.

Il est recommandé d’utiliser OAuth dans les environnements ayant des exigences d’authentification spécifiques.

Fonctionnalités disponibles

Les fragments de contenu sont un type spécifique de ressource. Voir Utilisation de fragments de contenu.

Pour plus d’informations sur les fonctionnalités disponibles via l’API, voir :

• L’API REST Assets
• Types d’entité, où sont expliquées les fonctionnalités propres à chaque type pris en charge (en fonction des fragments de contenu).

Pagination

L’API REST Assets prend en charge la pagination (pour les requêtes GET) via les paramètres d’URL :

• offset : nombre de premières entités (enfants) à extraire
• limit : nombre maximal d’entités renvoyées

La réponse contiendra les informations de pagination dans la section properties de la sortie SIREN. Cette propriété srn:paging contient le nombre d’entités (enfants) (total), le décalage et la limite (offset, limit) tels que spécifiés dans la requête.

Exemple : pagination

GET /api/assets.json?offset=2&limit=3

...
"properties": {
    ...
    "srn:paging": {
        "total": 7,
        "offset": 2,
        "limit": 3
    }
    ...
}
...

Types d’entités

Dossiers

Les dossiers servent de conteneurs pour les ressources et d’autres dossiers. Elles reflètent la structure du référentiel de contenu AEM.

L’API REST Assets expose l’accès aux propriétés d’un dossier (par exemple, son nom, son titre, etc.). Les ressources sont exposées en tant qu’entités enfants de dossiers et de sous-dossiers.

Assets

Si une ressource est demandée, la réponse renvoie ses métadonnées, telles que le titre, le nom et les autres informations, comme défini par le schéma des ressources respectives.

Les données binaires d’une ressource sont exposées sous la forme d’un lien SIREN de type content.

Les ressources peuvent comporter plusieurs rendus. Elles sont généralement exposées en tant qu’entités enfants, à l’exception du rendu de miniature, qui est exposé sous la forme d’un lien de type thumbnail (rel="thumbnail").

Fragments de contenu

Un fragment de contenu est un type de ressource spécial. Il permet d’accéder aux données structurées, telles que les textes, les nombres, les dates, etc.

Comme il existe plusieurs différences au sein des ressources standard (telles que les images ou le son), certaines règles supplémentaires s’appliquent pour les gérer.

Représentation

Les fragments de contenu :

• N’exposent aucune donnée binaire.

• Sont entièrement contenus dans la sortie JSON (dans la propriété properties).

• Sont également considérés comme atomiques, c’est-à-dire que les éléments et les variations sont exposés dans les propriétés du fragment et non pas en tant que liens ou entités enfants. Cela permet un accès efficace à la payload d’un fragment.

Modèles et fragments de contenu

Actuellement, les modèles qui définissent la structure d’un fragment de contenu ne sont pas exposés via une API HTTP. Par conséquent, le consommateur doit disposer d’informations sur le modèle d’un fragment (au moins un minimum), bien que la plupart des informations puissent être déduites de la charge utile (par exemple, les types de données, etc.). font partie de la définition.

Pour créer un fragment de contenu, le chemin (référentiel interne) du modèle doit être indiqué.

Contenu associé

Le contenu associé n’est actuellement pas exposé.

Utilisation de

L’utilisation peut varier selon que vous utilisez un environnement d’auteur ou de publication AEM dans votre cas d’utilisation spécifique.

• Il est vivement recommandé de lier la création à une instance d’auteur (et il n’existe actuellement aucun moyen de répliquer un fragment pour publier à l’aide de cette API).

• La diffusion est possible à partir des deux, car AEM diffuse le contenu demandé au format JSON uniquement.

  • Le stockage et la diffusion depuis une instance d’auteur AEM doivent suffire pour les applications de bibliothèque multimédia situées derrière le pare-feu.

  • Pour une diffusion web en direct, une instance de publication AEM est recommandée.

Limites

Il existe quelques restrictions :

• Les modèles de fragment de contenu ne sont actuellement pas pris en charge : ils ne peuvent pas être lus ni créés. Pour pouvoir créer un fragment de contenu, ou en mettre un existant à jour, les développeurs doivent connaître le chemin correct vers le modèle de fragment de contenu. Actuellement, la seule méthode pour obtenir un aperçu de ces éléments est via l’interface utilisateur d’administration.
• Les références sont ignorées. Actuellement, il n’existe aucune vérification pour savoir si un fragment de contenu existant est référencé. Par conséquent, la suppression d’un fragment de contenu, par exemple, peut entraîner des problèmes sur une page contenant une référence au fragment de contenu en question.
• Type de données JSON L’API REST définit actuellement la sortie du type de données JSON sur chaîne de caractères.

Codes d’état et messages d’erreur

Les codes d’état suivants s’affichent dans les circonstances pertinentes :

• 200 (OK)

  Affiché dans le scénario suivant :

  • demande d’un fragment de contenu via GET
  • mise à jour réussie d’un fragment de contenu via PUT

• 201 (Créé)

  Affiché dans le scénario suivant :

  • création réussie d’un fragment de contenu via POST

• 404 (Introuvable)

  Affiché dans le scénario suivant :

  • le fragment de contenu demandé n’existe pas

• 500 (Erreur interne du serveur)

  REMARQUE

  Cette erreur est renvoyée :

  • lorsqu’une erreur ne pouvant pas être identifiée avec un code spécifique s’est produite ;
  • lorsque la payload donnée n’était pas valide

  L’exemple suivant répertorie les scénarios courants lorsque cet état d’erreur est renvoyé, ainsi que le message d’erreur (monospace) généré :

  • Le dossier parent n’existe pas (lors de la création d’un fragment de contenu via POST)

  • Aucun modèle de fragment de contenu n’est fourni (cq:model est manquant) ou ne peut être lu (en raison d’un chemin d’accès non valide ou d’un problème d’autorisation) ou il n’existe aucun modèle de fragment valide :

    • No content fragment model specified
    • Cannot create a resource of given model '/foo/bar/qux'

  • Impossible de créer le fragment de contenu (problème d’autorisation potentiel) :

    • Could not create content fragment

  • Le titre et/ou la description n’ont pas pu être mis à jour :

    • Could not set value on content fragment

  • Impossible de définir les métadonnées :

    • Could not set metadata on content fragment

  • Élément de contenu introuvable ou impossible à mettre à jour

    • Could not update content element
    • Could not update fragment data of element

  Les messages d’erreur détaillés sont généralement renvoyés de la façon suivante :

  {
    "class": "core/response",
    "properties": {
      "path": "/api/assets/foo/bar/qux",
      "location": "/api/assets/foo/bar/qux.json",
      "parentLocation": "/api/assets/foo/bar.json",
      "status.code": 500,
      "status.message": "...{error message}.."
    }
  }
  

Référence d’API

Pour accéder aux références d’API détaillées :

• API Adobe Experience Manager Assets – Fragments de contenu

• API HTTP Assets

  • Fonctionnalités disponibles

Ressources supplémentaires

Pour plus d’informations, voir :

• Documentation de l’API HTTP Assets
• Session AEM Gem : OAuth

Ressources Business.Adobe.com