Unterstützung von Inhaltsfragmenten in der AEM Assets-HTTP-API content-fragments-support-in-aem-assets-http-api
Übersicht overview
Erfahren Sie mehr über die Unterstützung für Inhaltsfragmente in der Assets-HTTP-API, einem wichtigen Teil der Headless-Bereitstellungs-Funktion in Adobe Experience Manager (AEM).
- Assets-REST-API
- einschließlich Unterstützung für Inhaltsfragmente
Die Assets-REST-API ermöglicht Entwicklungspersonen von Adobe Experience Manager as a Cloud Service den direkten Zugriff auf (in AEM gespeicherte) Inhalte über die HTTP-API mit CRUD-Vorgängen (Erstellen, Lesen, Aktualisieren, Löschen).
Die API ermöglicht es Ihnen, Adobe Experience Manager as a Cloud Service 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.
Single Page Applications (SPA, Einzelseiten-Webanwendungen), ob Framework-basiert oder benutzerdefiniert, erfordern beispielsweise Inhalte, die über die HTTP-API bereitgestellt werden, häufig im JSON-Format.
AEM-Kernkomponenten stellen eine 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. Der Grund dafür ist, dass sie auf 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 Entwicklerinnen und 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
Voraussetzungen prerequisites
Die Assets-REST-API ist in jeder standardmäßigen Installation einer aktuellen Adobe Experience Manager as a Cloud Service-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).
- Das bedeutet, dass Sie für den Zugriff auf das Asset unter
/content/dam/path/to/asset
- Anfrage:
/api/assets/path/to/asset
Um beispielsweise auf /content/dam/wknd/en/adventures/cycling-tuscanyzuzugreifen, fordern Sie /api/assets/wknd/en/adventures/cycling-tuscany.json an.
/api/assetserfordert keine Verwendung des.model-Selektors./content/path/to/pageerfordert die Verwendung des.model-Selektors.
Die HTTP-Methode ermittelt den auszuführenden Vorgang:
- GET: Zum Abrufen einer JSON-Darstellung eines Assets bzw. Ordners
- POST: Zum Erstellen von Assets oder Ordnern
- PUT: Zum Aktualisieren der Eigenschaften eines Assets oder Ordners
- DELETE: Zum Löschen eines Assets oder Ordners
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
(Komponenten mit Sling-Modellen)
Optimiert für den Einsatz in einer Single Page Application (SPA) oder in einem beliebigen anderen Kontext (Inhalt verbrauchend).
Kann auch Layout-Informationen enthalten.
Erstellen, Lesen, Aktualisieren, Löschen.
Weitere Vorgänge je nach Entitätstyp.
Sie können direkt darauf zugreifen.
Verwendet den Endpunkt /api/assets und ist /content/dam zugeordnet (im Repository).
Ein Beispielpfad würde wie folgt aussehen: /api/assets/wknd/en/adventures/cycling-tuscany.json
Muss über eine AEM-Komponente auf einer AEM-Seite referenziert werden.
Verwendet den Selektor .model, um die JSON-Darstellung zu erstellen.
Ein Beispielpfad würde wie folgt aussehen:/content/wknd/language-masters/en/adventures/cycling-tuscany.model.json
Mehrere Optionen sind möglich.
OAuth wird vorgeschlagen und kann separat von der Standardeinrichtung konfiguriert werden.
Der Schreibzugriff gilt in der Regel für eine Autoreninstanz.
Der Lesezugriff kann auch an eine Veröffentlichungsinstanz weitergeleitet werden.
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:
- Die Assets-REST-API
- Entitätstypen, bei denen die für jeden unterstützten Typ spezifischen Funktionen (soweit für Inhaltsfragmente relevant) erläutert werden.
Paging paging
Die Assets-REST-API unterstützt Paging (für GET-Anforderungen) ü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.
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. Beispielsweise sein Name und Titel. 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:
-
stellen keine Binärdaten bereit.
-
sind in der JSON-Ausgabe enthalten (innerhalb der Eigenschaft
properties). -
sie gelten auch als atomisch. Das bedeutet, dass die Elemente und Varianten als Teil der Eigenschaften des Fragments anstatt als Links oder untergeordnete Entitäten bereitgestellt werden. Dies ermöglicht einen effiziente Zugriff auf die Payload eines Fragments.
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 Verbraucher (zumindest einige) Informationen über das Modell eines Fragments. Die meisten Informationen können jedoch aus der Nutzlast abgeleitet werden, da Datentypen usw. Teil der Definition sind.
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 nicht bereitgestellt.
Verwenden using
Die Verwendung unterscheidet sich je nachdem, ob Sie eine AEM-Autoren- oder Veröffentlichungsumgebung zusammen mit Ihrem spezifischen Verwendungsszenario verwenden.
-
Es wird 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 Medienbibliotheksanwendungen hinter einer Firewall ausreichen.
-
Für die Live-Web-Bereitstellung wird eine AEM-Veröffentlichungsinstanz empfohlen.
-
/api.Einschränkungen limitations
Es gibt einige Beschränkungen:
- Inhaltsfragmentmodelle werden derzeit nicht unterstützt: sie können weder gelesen noch erstellt werden. Um ein Inhaltsfragment zu erstellen oder ein bestehendes zu aktualisieren, müssen Entwickelnde den richtigen Pfad zum Inhaltsfragmentmodell kennen. Derzeit ist dies lediglich über die Verwaltungsoberfläche möglich.
- Verweise werden ignoriert. Zurzeit sind keine Überprüfungen für Verweise auf vorhandene Inhaltsfragmente verfügbar. Wenn Sie beispielsweise ein Inhaltsfragment löschen, treten möglicherweise Probleme auf einer Seite auf, die einen Verweis auf das gelöschte Inhaltsfragment enthält.
- JSON-Datentyp Die REST-API-Ausgabe des JSON-Datentyps basiert auf Zeichenfolgen.
Status-Codes und Fehlermeldungen status-codes-and-error-messages
Unter den entsprechenden Voraussetzungen werden möglicherweise die folgenden Status-Codes angezeigt:
-
200 (OK)
Wird zurückgegeben, wenn:
- ein Inhaltsfragment per
GETangefordert wurde - ein Inhaltsfragment mithilfe von
PUTaktualisiert wurde
- ein Inhaltsfragment per
-
201 (Erstellt)
Wird zurückgegeben, wenn:
- ein Inhaltsfragment mithilfe von
POSTerstellt wurde
- ein Inhaltsfragment mithilfe von
-
404 (Nicht gefunden)
Wird zurückgegeben, wenn:
- das angeforderte Inhaltsfragment nicht vorhanden ist
-
500 (Interner Server-Fehler)
note note NOTE Dieser Fehler wird zurückgegeben: - wenn ein Fehler, der mit keinem bestimmten Code identifiziert werden kann, aufgetreten ist
- wenn als Payload „null“ angegeben ist
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
POSTerstellt 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 specifiedCannot 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 elementCould not update fragment data of element
Die detaillierten Fehlermeldungen werden auf folgende Art zurückgegeben:
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}.." } }
API-Referenz api-reference
Hier finden Sie detaillierte API-Referenzen:
Zusätzliche Ressourcen additional-resources
Weitere Informationen finden Sie unter: