Unterstützung von Inhaltsfragmenten in der AEM Assets-HTTP-API content-fragments-support-in-aem-assets-http-api

Überblick overview

Erfahren Sie mehr über die Unterstützung für Inhaltsfragmente in der Assets-HTTP-API, einem wichtigen Teil der Headless-Bereitstellungs-Funktion in AEM.

Die Assets-REST-API ermöglicht Entwicklern von Adobe Experience Manager den direkten Zugriff auf (in AEM gespeicherte) Inhalte über die HTTP-API über CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren, Löschen).

Die API ermöglicht es Ihnen, Adobe Experience Manager als Headless-CMS (Content-Management-System) auszuführen, indem einer JavaScript-Frontend-Anwendung Content-Services zur Verfügung gestellt werden. Oder jedem anderen Programm, das HTTP-Anfragen ausführen und JSON-Antworten verarbeiten kann.

Beispielsweise benötigen Framework-basierte oder benutzerdefinierte Single Page Applications (SPA), die über die HTTP-API bereitgestellten Inhalte häufig im JSON-Format.

AEM-Kernkomponenten stellen eine sehr umfassende, flexible und anpassbare API bereit, die erforderliche Lesevorgänge für diesen Zweck durchführen kann und deren JSON-Ausgabe angepasst werden kann. Dazu sind jedoch Kenntnisse von AEM WCM (Web Content Management) für die Implementierung erforderlich, da sie in (API-)Seiten gehostet werden müssen, die auf dedizierten AEM-Vorlagen basieren. Nicht jede SPA-Entwicklungsorganisation hat direkten Zugriff auf dieses Wissen.

Hier kann die Assets-REST-API eingesetzt werden. Damit können Entwickler direkt auf Assets (z. B. Bilder und Inhaltsfragmente) zugreifen, ohne sie zuerst in eine Seite einzubetten, und ihre Inhalte im serialisierten JSON-Format bereitstellen.

Mit der Assets-REST-API können Entwickler Inhalte ändern, indem sie neue Assets, Inhaltsfragmente und Ordner erstellen, aktualisieren oder vorhandene Assets, Inhaltsfragmente und Ordner löschen.

Die Assets-REST-API:

Voraussetzungen prerequisites

Die Assets-REST-API ist in jeder standardmäßigen Installation einer aktuellen AEM-Version verfügbar.

Wichtige Konzepte key-concepts

Die Assets-REST-API bietet REST-ähnlichen Zugriff auf Assets, die in einer AEM-Instanz gespeichert sind.

Sie verwendet den /api/assets-Endpunkt und benötigt für den Zugriff auf das Asset dessen Pfad (ohne das Präfix /content/dam).

Um beispielsweise auf /content/dam/wknd/en/adventures/cycling-tuscanyzuzugreifen, fordern Sie /api/assets/wknd/en/adventures/cycling-tuscany.json an.

Die HTTP-Methode ermittelt den auszuführenden Vorgang:

Das genaue Format der unterstützten Anforderungen ist in der API-Referenzdokumentation definiert.

Transaktionsverhalten transactional-behavior

Alle Anfragen sind atomisch.

Dies bedeutet, dass die folgenden (write)-Anfragen nicht in einer einzelnen Transaktion kombiniert werden können, die als einzelne Entität ausgeführt werden oder fehlschlagen könnte.

AEM (Assets)-REST-API und AEM-Komponenten im Vergleich aem-assets-rest-api-versus-aem-components

Sicherheit security

Wenn die Assets-REST-API in einer Umgebung ohne spezifische Authentifizierungsanforderungen verwendet wird, muss der CORS-Filter von AEM richtig konfiguriert werden.

In Umgebungen mit bestimmten Authentifizierungsanforderungen wird OAuth empfohlen.

Verfügbare Funktionen available-features

Inhaltsfragmente sind eine bestimmte Art von Assets. Informationen finden Sie unter Arbeiten mit Inhaltsfragmenten.

Weitere Informationen zu den über die APIs verfügbaren Funktionen:

Paging paging

Die Assets-REST-API unterstützt Paging (für GET-Anfragen) über die URL-Parameter:

Die Antwort enthält Paging-Informationen im Bereich properties der SIREN-Ausgabe. Diese Eigenschaft srn:paging enthält die Gesamtzahl der (untergeordneten) Entitäten (total), den Offset und das Limit ( offset, limit), wie in der Anfrage angegeben.

Beispiel: Paging example-paging

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

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

Entitätstypen entity-types

Ordner folders

Ordner dienen als Container für Assets und andere Ordner. Ihre Struktur entspricht den Inhalts-Repositorys von AEM.

Die Assets-REST-API gewährt Zugriff auf die Eigenschaften eines Ordners, z. B. Name, Titel und so weiter. Assets werden als untergeordnete Entitäten von Ordnern und Unterordnern bereitgestellt.

Assets assets

Wenn ein Asset angefordert wird, gibt die Antwort die Metadaten (z. B. Titel, Name und andere Informationen) wie vom entsprechenden Asset-Schema definiert zurück.

Die Binärdaten eines Assets werden als SIREN-Link vom Typ content dargestellt.

Assets können mehrere Ausgabedarstellungen aufweisen. Diese werden in der Regel als untergeordnete Entitäten bereitgestellt. Eine Ausnahme stellt die Ausgabedarstellung der Miniaturen dar, die als Link vom Typ thumbnail (rel="thumbnail") bereitgestellt wird.

Inhaltsfragmente content-fragments

Ein Inhaltsfragment ist ein spezieller Asset-Typ. Es kann für den Zugriff auf strukturierte Daten wie Texte, Zahlen und Daten verwendet werden.

Da es einige Unterschiede zu Standard-Assets (z. B. Bildern oder Audio) aufweist, gelten einige zusätzliche Regeln für die Verarbeitung.

Darstellung representation

Inhaltsfragmente:

Inhaltsmodelle und Inhaltsfragmente content-models-and-content-fragments

Derzeit werden die Modelle, die die Struktur eines Inhaltsfragments definieren, nicht über eine HTTP-API bereitgestellt. Daher benötigen Benutzende (zumindest einige) Informationen über das Modell eines Fragments, obwohl die meisten Informationen aus der Payload abgeleitet werden können, beispielsweise Datentypen. Teil der Definition.

Zum Erstellen eines Inhaltsfragments muss der Pfad (des internen Repositorys) für das Modell angegeben werden.

Zugehörige Inhalte associated-content

Zugehörige Inhalte werden derzeit nicht bereitgestellt.

Verwenden using

Die Verwendung unterscheidet sich je nachdem, ob Sie eine AEM-Autoren- oder Veröffentlichungsumgebung zusammen mit Ihrem spezifischen Verwendungsszenario verwenden.

Lesen/Bereitstellen read-delivery

Nutzung erfolgt über:

GET /{cfParentPath}/{cfName}.json

Zum Beispiel:

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

Die Antwort ist serialisiertes JSON mit dem im Inhaltsfragment strukturierten Inhalt. Verweise werden als Referenz-URLs bereitgestellt.

Zwei Arten von Lesevorgängen sind möglich:

Erstellen create

Nutzung erfolgt über:

POST /{cfParentPath}/{cfName}

Der Hauptteil muss eine JSON-Darstellung des zu erstellenden Inhaltsfragments enthalten – einschließlich des anfänglichen Inhalts, der für Inhaltsfragmentelemente festgelegt werden soll. Sie müssen die Eigenschaft cq:model festlegen und auf ein gültiges Inhaltsfragmentmodell verweisen. Andernfalls tritt ein Fehler auf. Außerdem müssen Sie eine Kopfzeile vom Typ Content-Type hinzufügen, für die application/json festgelegt ist.

Update update

Nutzung erfolgt über

PUT /{cfParentPath}/{cfName}

Der Hauptteil muss eine JSON-Darstellung davon enthalten, was für das angegebene Inhaltsfragment aktualisiert werden soll.

Dies kann einfach der Titel oder die Beschreibung eines Inhaltsfragments bzw. ein einzelnes Element oder alle Elementwerte und/oder Metadaten sein.

Löschen delete

Nutzung erfolgt über:

DELETE /{cfParentPath}/{cfName}

Beschränkungen limitations

Es gibt einige Beschränkungen:

Status-Codes und Fehlermeldungen status-codes-and-error-messages

Unter den entsprechenden Voraussetzungen werden möglicherweise die folgenden Status-Codes angezeigt:

API-Referenz api-reference

Hier finden Sie detaillierte API-Referenzen:

Zusätzliche Ressourcen additional-resources

Weitere Informationen finden Sie unter: