Version | Artikel-Link |
---|---|
AEM as a Cloud Service | Hier klicken |
AEM 6.5 | Dieser Artikel |
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-HTTP-API umfasst die:
Die aktuelle Implementierung der Assets-HTTP API basiert auf dem REST-Architekturstil.
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).
Mit der API können Sie Adobe Experience Manager als Headless-CMS (Content Management System) betreiben, indem Sie einer JavaScript-Frontend-Anwendung Content Services bereitstellen. 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.
Es ist nicht möglich, die JSON-Ausgabe über die Assets-REST-API anzupassen.
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:
folgt dem HATEOAS-Prinzip
implementiert das SIREN-Format
Die Assets-REST-API ist in jeder standardmäßigen Installation einer aktuellen AEM-Version verfügbar.
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
).
/content/dam/path/to/asset
/api/assets/path/to/asset
Um beispielsweise auf /content/dam/wknd/en/adventures/cycling-tuscany
zuzugreifen, fordern Sie /api/assets/wknd/en/adventures/cycling-tuscany.json
an.
Der Zugriff über:
/api/assets
erfordert keine Verwendung des .model
-Selektors./content/path/to/page
erfordert die Verwendung des .model
-Selektors.Die HTTP-Methode ermittelt den auszuführenden Vorgang:
Mit dem Anfragetext und/oder den URL-Parametern können Sie einige dieser Vorgänge konfigurieren. Sie definieren damit beispielsweise, dass ein Ordner oder ein Asset über eine POST-Anfrage erstellt werden soll.
Das genaue Format der unterstützten Anforderungen ist in der API-Referenzdokumentation definiert.
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.
Aspekt | Assets-REST-API |
AEM-Komponente (Komponenten mit Sling-Modellen) |
Geeignete Nutzungsszenarien | Universell. | Optimiert für den Einsatz in einer Single Page Application (SPA) oder in einem beliebigen anderen Kontext (Inhalt verbrauchend). Kann auch Layoutinformationen enthalten. |
Unterstützte Vorgänge | Erstellen, Lesen, Aktualisieren, Löschen. Weitere Vorgänge abhängig von Entitätstyp. |
Schreibgeschützt. |
Zugriff | Direkter Zugriff möglich. Verwendet den Endpunkt Ein Beispielpfad würde wie folgt aussehen: |
Muss über eine AEM-Komponente auf einer AEM-Seite referenziert werden. Verwendet den Selektor Ein Beispielpfad würde wie folgt aussehen: |
Sicherheit | Mehrere Optionen sind möglich. OAuth wird vorgeschlagen und kann separat von der obigen Standardeinrichtung konfiguriert werden. |
Verwendet die oben beschriebene Standardeinrichtung von AEM. |
Anmerkungen zur Architektur | Der Schreibzugriff gilt in der Regel für eine Autoreninstanz. Der Lesezugriff kann auch an eine Veröffentlichungsinstanz weitergeleitet werden. |
Da dieser Vorgang schreibgeschützt ist, wird er in der Regel für Veröffentlichungsinstanzen verwendet. |
Ausgabe | JSON-basierte SIREN-Ausgabe: ausführlich, aber leistungsstark. Ermöglicht die Navigation innerhalb des Inhalts. | JSON-basierte proprietäre Ausgabe über Sling-Modelle konfigurierbar. Die Navigation durch die Inhaltsstruktur ist schwer zu implementieren (jedoch nicht unmöglich). |
Wenn die Assets-REST-API in einer Umgebung ohne spezifische Authentifizierungsanforderungen verwendet wird, muss der CORS-Filter von AEM richtig konfiguriert werden.
Weitere Informationen finden Sie unter:
In Umgebungen mit bestimmten Authentifizierungsanforderungen wird OAuth empfohlen.
Inhaltsfragmente sind eine bestimmte Art von Assets. Informationen finden Sie unter Arbeiten mit Inhaltsfragmenten.
Weitere Informationen zu den über die APIs verfügbaren Funktionen:
Die Assets-REST-API unterstützt Paging (für GET-Anfragen) über die URL-Parameter:
offset
: Die Nummer der ersten (untergeordneten) Entität, die abgerufen werden solllimit
: Die maximale Anzahl von zurückgegebenen Entitäten.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.
Paging wird normalerweise auf Container-Entitäten (d. h. Ordner oder Assets mit Ausgabedarstellungen) angewendet, da sie auf die untergeordneten Objekte des angeforderten Elements verweisen.
GET /api/assets.json?offset=2&limit=3
...
"properties": {
...
"srn:paging": {
"total": 7,
"offset": 2,
"limit": 3
}
...
}
...
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, usw. Assets werden als untergeordnete Entitäten von Ordnern und Unterordnern bereitgestellt.
Je nach Asset-Typ der untergeordneten Assets und Ordner enthält die Liste der untergeordneten Entitäten möglicherweise bereits die gesamten Eigenschaften, die die untergeordnete Entität definieren. Alternativ werden einer Entität in dieser Liste der untergeordneten Entitäten möglicherweise nicht alle Eigenschaften bereitgestellt.
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.
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.
Inhaltsfragmente:
stellen keine Binärdaten bereit.
sind vollständig in der JSON-Ausgabe enthalten (innerhalb der Eigenschaft properties
).
Gelten auch als atomisch, d. h. die Elemente und Varianten werden als Teil der Eigenschaften des Fragments anstatt als Links oder untergeordnete Entitäten bereitgestellt. Dies ermöglicht einen effiziente Zugriff auf die Payload eines Fragments.
Derzeit werden die Modelle, die die Struktur eines Inhaltsfragments definieren, nicht über eine HTTP-API bereitgestellt. Daher benötigt der Benutzer (zumindest einige) Informationen über das Modell eines Fragments. Die meisten Informationen kann er jedoch aus der Payload ableiten. So sind z. B. Datentypen Teil der Definition.
Zum Erstellen eines neuen Inhaltsfragments muss der Pfad (des internen Repositorys) für das Modell angegeben werden.
Zugehörige Inhalte werden derzeit nicht bereitgestellt.
Die Verwendung unterscheidet sich je nachdem, ob Sie eine AEM-Autoren- oder Veröffentlichungsumgebung zusammen mit Ihrem spezifischen Verwendungsszenario verwenden.
Es wird dringend empfohlen, dass die Erstellung in einer Autoreninstanz erfolgt (und derzeit gibt es keine Möglichkeit, ein Fragment mit dieser API für die Veröffentlichungsinstanz zu replizieren).
Die Bereitstellung ist in beiden Umgebungen möglich, da AEM angeforderte Inhalte nur im JSON-Format bereitstellt.
Das Speichern und Bereitstellen über eine AEM-Autoreninstanz sollte für Mediathekanwendungen hinter einer Firewall ausreichen.
Für die Live-Web-Bereitstellung wird eine AEM-Veröffentlichungsinstanz empfohlen.
Die Dispatcher-Konfiguration auf AEM-Instanzen blockiert möglicherweise den Zugriff auf /api
.
Weitere Informationen finden Sie in der API-Referenz. Besonders interessant: Adobe Experience Manager Assets API – Inhaltsfragmente.
Nutzung erfolgt über:
GET /{cfParentPath}/{cfName}.json
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:
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.
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.
Nutzung erfolgt über:
DELETE /{cfParentPath}/{cfName}
Es gibt einige Beschränkungen:
Unter den entsprechenden Voraussetzungen werden möglicherweise die folgenden Status-Codes angezeigt:
200 (OK)
Wird zurückgegeben, wenn:
GET
angefordert wurdePUT
aktualisiert wurde201 (Erstellt)
Wird zurückgegeben, wenn:
POST
erstellt wurde404 (Nicht gefunden)
Wird zurückgegeben, wenn:
das angeforderte Inhaltsfragment nicht vorhanden ist
500 (Interner Server-Fehler)
Dieser Fehler wird zurückgegeben:
Nachfolgend finden Sie allgemeine Szenarien, in denen dieser Fehlerstatus in Kombination mit der Fehlermeldung (monospace) zurückgegeben wird:
Übergeordneter Ordner ist nicht vorhanden (wenn ein Inhaltsfragment per POST
erstellt wurde)
Es wird kein Inhaltsfragmentmodell bereitgestellt (cq:model fehlt), es kann nicht gelesen werden (aufgrund eines ungültigen Pfads oder eines Berechtigungsproblems) oder es gibt kein gültiges Fragmentmodell:
No content fragment model specified
Cannot create a resource of given model '/foo/bar/qux'
Das Inhaltsfragment konnte nicht erstellt werden (möglicherweise ein Berechtigungsproblem):
Could not create content fragment
Titel oder Beschreibung konnte nicht aktualisiert werden:
Could not set value on content fragment
Metadaten konnten nicht festgelegt werden:
Could not set metadata on content fragment
Inhaltselement wurde nicht gefunden oder konnte nicht aktualisiert werden
Could not update content element
Could not update fragment data of element
Die detaillierten Fehlermeldungen werden im Allgemeinen im folgenden Typ zurückgegeben:
{
"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}.."
}
}
Hier finden Sie detaillierte API-Referenzen:
Weitere Informationen finden Sie unter: