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

Version
Lien de l’article
AEM 6.5
Cliquez ici
AEM as a Cloud Service
Cet article

Découvrez la prise en charge des fragments de contenu dans l’API HTTP Assets, un élément important de la fonctionnalité de diffusion Adobe Experience Manager (AEM) sans interface utilisateur.

NOTE
L’API HTTP Assets englobe les éléments suivants :
  • API REST Assets
  • Prise en charge des fragments de contenu
L’implémentation actuelle de l’API HTTP Assets est basée sur le style architectural REST.
NOTE
Pour obtenir les informations les plus récentes sur les API de Experience Manager, consultez également la page API ADOBE EXPERIENCE MANAGER AS A CLOUD SERVICE.

La variable 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, au moyen des opérations CRUD (Create, Read, Update, Delete).

L’API vous permet d’utiliser Adobe Experience Manager as a Cloud Service en tant que CMS (Content Management System) sans interface utilisateur en fournissant Content Services à 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.

while Composants principaux d’AEM fournir une API personnalisable pouvant traiter les opérations de lecture requises à cette fin et dont la sortie JSON peut être personnalisée ; elles nécessitent AEM savoir-faire WCM (Web Content Management) pour la mise en oeuvre ; En effet, elles doivent être hébergées sur des pages basées sur des modèles d’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é.

NOTE
Il est impossible de personnaliser la sortie JSON de l’API REST Assets.

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

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’Adobe Experience Manager as a Cloud Service.

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

  • Cela signifie que pour accéder à la ressource à l’adresse suivante :
    • /content/dam/path/to/asset
  • Requête :
    • /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

NOTE
Accès via :
  • /api/assets ne nécessite pas l’utilisation du sélecteur .model.
  • /content/path/to/page nécessite l’utilisation du sélecteur .model.

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
  • SUPPRIMER  - pour supprimer une ressource ou un dossier.
NOTE
Le corps de la requête et/ou les paramètres URL peuvent être utilisés pour configurer certaines de ces opérations ; par exemple, spécifier qu’un dossier ou une ressource doivent être créés par une requête POST.

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

Aspect
API REST Assets
Composant AEM
(composants utilisant des modèles Sling)
Cas d’utilisation pris en charge
Objectif général.

Optimisé pour une utilisation dans une application monopage ou tout autre contexte (utilisant du contenu).

Il peut également contenir des informations de mise en page.

Opérations prises en charge

Créer, Lire, Mettre à jour, Supprimer.

Avec des opérations supplémentaires, selon le type d’entité.

Lecture seule.
Accès

Il est accessible directement.

Utilise le point d’entrée /api/assets , mappé sur /content/dam (dans le référentiel).

Voici un exemple de chemin : /api/assets/wknd/en/adventures/cycling-tuscany.json

Il doit être référencé par le biais d’un composant AEM sur une page AEM.

Utilise le sélecteur .model pour créer la représentation JSON.

Voici un exemple de chemin :
/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json

Sécurité

Plusieurs options sont possibles.

OAuth est proposé ; peut être configuré séparément de la configuration standard.

Utilise la configuration AEM standard.
Remarques architecturales

L’accès en écriture s’adresse généralement à une instance d’auteur.

La lecture peut également être dirigée vers une instance de publication.

Cette approche étant en lecture seule, elle est généralement utilisée pour les instances de publication.
Sortie
Sortie SIREN basée sur JSON : détaillée, mais puissante. Il permet de naviguer dans le contenu.
Sortie propriétaire basée sur JSON ; configurable via les modèles Sling. La navigation dans la structure de contenu est difficile à mettre en œuvre (mais pas nécessairement impossible).

Sécurité security

Si l’API REST Assets est utilisée dans un environnement sans conditions d’authentification spécifiques, AEM filtre CORS 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 :

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

L’API REST Assets prend en charge la pagination (pour les demandes de GET) au moyen des paramètres d’URL :

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

La réponse contient des informations de pagination dans le cadre de la fonction properties de la sortie SIREN. Ceci srn:paging contient le nombre total d’entités (enfants) ( total), le décalage et la limite ( offset, limit) comme spécifié dans la requête.

NOTE
La pagination est généralement appliquée aux entités de conteneur (c’est-à-dire les dossiers ou les ressources comportant des rendus), car elle a trait aux enfants de l’entité demandée.

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 et son titre. Les ressources sont exposées en tant qu’entités enfants de dossiers et de sous-dossiers.

NOTE
Selon le type de ressource des ressources et dossiers enfants, la liste des entités enfants peut déjà contenir l’ensemble complet des propriétés qui définissent l’entité enfant respective. Une autre possibilité consiste à afficher uniquement un jeu limité de propriétés pour une entité dans cette liste d’entités enfants.

Assets assets

Si une ressource est demandée, la réponse renvoie ses métadonnées, telles que le titre, le nom et d’autres informations, telles que définies par le schéma de ressource correspondant.

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. Ils peuvent être utilisés pour accéder à des données structurées, telles que des textes, des nombres, des 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 :

  • N’exposent aucune donnée binaire.

  • Sont contenus dans la sortie JSON (dans la variable properties ).

  • Ils sont aussi considérés comme atomiques. En d’autres termes, les éléments et les variations sont exposés dans les propriétés du fragment par rapport aux liens ou aux entités enfants. Cela permet un accès efficace à la payload d’un fragment.

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 variable client doit connaître le modèle d’un fragment (au moins un minimum), bien que la plupart des informations puissent être déduites de la charge utile, car 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 fourni.

Contenu associé associated-content

Le contenu associé n’est pas exposé.

Utiliser using

L’utilisation peut varier selon que vous utilisez un environnement de création AEM ou de publication, ainsi que votre cas d’utilisation spécifique.

CAUTION
La configuration de Dispatcher sur AEM instances cloud peut bloquer l’accès à /api.

Limites limitations

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 ou mettre à jour un fragment de contenu existant, 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 La sortie de l’API REST de la variable Type de données JSON is sortie basée sur des chaînes.

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

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 au moyen de GET
    • mise à jour réussie d’un fragment de contenu au moyen de PUT
  • 201 (Créé)

    Affiché dans le scénario suivant :

    • création réussie d’un fragment de contenu au moyen de POST
  • 404 (Introuvable)

    Affiché dans le scénario suivant :

    • le fragment de contenu demandé n’existe pas
  • 500 (Erreur interne du serveur)

    note note
    NOTE
    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 (à espacement fixe) généré :

    • Le dossier parent n’existe pas (lors de la création d’un fragment de contenu au moyen de 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 renvoyés de la manière suivante :

    code language-xml
    {
      "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 api-reference

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

Ressources supplémentaires additional-resources

Pour en savoir plus, voir :

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab