Prise en charge des fragments de contenu dans l’API HTTP AEM Assets content-fragments-support-in-aem-assets-http-api

Vue d’ensemble overview

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 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 en tant que système de gestion de contenu (CMS) découplé 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 monopages, 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 :

Conditions préalables prerequisites

L’API REST Assets est disponible pour chaque installation prête à l’emploi d’une version récente d’AEM.

Concepts clés key-concepts

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

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 :

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

Comportement transactionnel transactional-behavior

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 aem-assets-rest-api-versus-aem-components

Sécurité security

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 available-features

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 :

Pagination paging

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

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 example-paging

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

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

Types d’entités entity-types

Dossiers folders

Les dossiers servent de conteneurs pour les ressources et d’autres dossiers. Ils 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 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 content-fragments

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 representation

Les fragments de contenu :

Modèles et fragments de contenu content-models-and-content-fragments

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, la cliente ou le client 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 payload (par exemple, les types de données, etc.). Ces dernières font par ailleurs 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é associated-content

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

Utilisation de using

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

Lecture/Diffusion read-delivery

Mode d’utilisation :

GET /{cfParentPath}/{cfName}.json

Par exemple :

http://<host>/api/assets/wknd/en/adventures/cycling-tuscany.json

La réponse est un JSON sérialisé avec le contenu structuré comme dans le fragment de contenu. Les références sont diffusées en tant qu’URL de référence.

Deux types d’opérations de lecture sont possibles :

Créer create

Mode d’utilisation :

POST /{cfParentPath}/{cfName}

Le corps doit contenir une représentation JSON du fragment de contenu à créer, notamment tout contenu initial devant être défini sur les éléments de fragment de contenu. Il est obligatoire de définir la propriété cq:model, qui doit pointer vers un modèle de fragment de contenu valide. Sans cela, il se produira une erreur. Il est également nécessaire d’ajouter un en-tête Content-Type, défini sur application/json.

Mettre à jour update

Mode d’utilisation :

PUT /{cfParentPath}/{cfName}

Le corps doit contenir une représentation JSON de ce qui doit être mis à jour pour le fragment de contenu donné.

Il peut simplement s’agir du titre ou de la description d’un fragment de contenu, d’un élément unique ou de toutes les valeurs et/ou métadonnées d’un élément.

Supprimer delete

Mode d’utilisation :

DELETE /{cfParentPath}/{cfName}

Limites limitations

Il existe quelques restrictions :

Codes d’état et messages d’erreur status-codes-and-error-messages

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

Référence d’API api-reference

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

Ressources supplémentaires additional-resources

Pour plus d’informations, voir :