Sie sehen sich Hilfeinhalte der folgenden Version an:

Erfahren Sie mehr über die Unterstützung von Inhaltsfragmenten in der AEM Assets-HTTP-API.

Überblick

Hinweis:

Die Assets-HTTP-API umfasst:

  • Assets-REST-API
    • einschließlich Unterstützung für Inhaltsfragmente

Die aktuelle Implementierung der AEM Assets-HTTP-API ist REST.

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

Die API ermöglicht es Ihnen, AEM als Headless-CMS (Content Management System) auszuführen, indem Sie einer Javascript-Frontend-Applikation Content Services bereitstellen. Oder jeder anderen Applikation, die HTTP-Anforderungen ausführen und JSON-Antworten verarbeiten kann.

Beispielsweise benötigen frameworkbasierte oder benutzerdefinierte Single-Page-Applikationen (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 Zugriff auf diese Ressourcen.  

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. (Beachten Sie, dass Sie die JSON-Ausgabe nicht über die Assets-REST-API anpassen können). Mit der Assets-REST-API können Entwickler Inhalte ändern, indem sie neue Assets erstellen, aktualisieren oder vorhandene Assets, Inhaltsfragmente und Ordner löschen.

Die Assets-REST-API:

Voraussetzungen

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

Hinweis:

Für ältere Versionen als AEM 6.5 müssen Sie ein Feature Pack installieren, um die vollständige Unterstützung für Inhaltsfragmente zu erhalten. In manchen Nutzungsszenarien müssen Sie eine zusätzliche Konfiguration ausführen. Weitere Informationen finden Sie im Abschnitt Sicherheit.

Schlüsselkonzepte

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

Die HTTP-Methode ermittelt den auszuführenden Vorgang:

  • GET: Zum Abrufen einer JSON-Darstellung eines Assets bzw. Ordners
  • POST: Zum Erstellen neuer Elemente oder Ordner
  • PUT: Zum Aktualisieren der Eigenschaften eines Assets oder eines Ordners
  • LÖSCHEN: Zum Löschen eines Assets oder Ordners

Hinweis:

Mit dem Anforderungstext 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-Anforderung erstellt werden soll.

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

Transaktionsverhalten

Alle Anforderungen sind atomisch.

Dies bedeutet, dass die folgenden (write-)Anforderungen 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

Aspekt Assets-REST-API
AEM-Komponente
(Komponenten mit Sling-Modellen)
Geeignete Nutzungsszenarien Universell.

Optimiert für den Einsatz in einer Single-Page-Applikation (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 /api/assets und ist /content/dam zugeordnet (im Repository).

Für den Zugriff auf
/content/dam/we-retail/en/experiences/arctic-surfing-in-lofoten

verwenden Sie beispielsweise die folgende Anforderung:
/api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.model.json

Muss über eine AEM-Komponente auf einer AEM-Seite referenziert werden.

Verwendet den Selektor .model, um die JSON-Darstellung zu erstellen.

Beispiel-URL:
http://localhost:4502/content/we-retail/language-masters/en/experience/arctic-surfing-in-lofoten.model.json

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

Sicherheit

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

Hinweis:

Weitere Informationen finden Sie unter:

In Umgebungen mit bestimmten Authentifizierungsanforderungen wird OAuth empfohlen.  

Verfügbare Funktionen

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

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 soll
  • limit: Die maximale Anzahl von zurückgegebenen Entitäten

Die Antwort enthält Paging-Informationen im Bereich Eigenschaften der SIREN-Ausgabe. Diese Eigenschaft srn:paging enthält die Gesamtzahl der (untergeordneten) Entitäten (total), Versatz und Rand (offset, limit), wie in der Anforderung angegeben.

Hinweis:

Paging wird normalerweise auf Containerentitäten (d. h. Ordner oder Assets mit Ausgabeformaten) angewendet, da sie auf die untergeordneten Objekte des angeforderten Elements verweisen.

Beispiel: Paging

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

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

Entitätstypen

Ordner

Ordner dienen als Container für Assets und andere Ordner. Ihre Struktur entspricht den Inhaltsrepositorys 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 bereitgestellt.

Hinweis:

Je nach Asset-Typ 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.

Assets

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

Die Binärdaten eines Assets werden als SIREN-Link vom Typ content bereitgestellt (auch als rel-Attribut bekannt).

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

Inhaltsfragmente

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

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 Nutzlast eines Fragments.

Inhaltsmodelle und Inhaltsfragmente

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 Nutzlast ableiten. So sind z. B. Datentypen Teil der Definition.

Zum Erstellen eines neuen Inhaltsfragments muss der Pfad (des internen Repositorys) angegeben werden.

Zugehörige Inhalte

Zugehöriger Inhalt wird derzeit nicht bereitgestellt.

Verwendung

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

Vorsicht:

Die Dispatcher-Konfiguration auf AEM-Cloudinstanzen blockiert möglicherweise den Zugriff auf /api.

Hinweis:

Weitere Informationen finden Sie in der API-Referenz. Besonders interessant: Adobe Experience Manager Assets API – Inhaltsfragmente.

Lesen/Bereitstellen

Nutzung erfolgt über:

GET /{cfParentPath}/{cfName}.json

Beispiel:

http://localhost:4502/api/assets/we-retail/en/experiences/arctic-surfing-in-lofoten.json

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

Zwei Arten von Lesevorgängen sind möglich:

  • Beim Lesen eines spezifischen Inhaltsfragments über einen Pfad gibt diese Methode die JSON-Darstellung des Inhaltsfragments zurück.
  • Beim Lesen eines Ordners mit Inhaltsfragmenten über einen Pfad gibt diese Methode die JSON-Darstellung aller Inhaltsfragmente in diesem Ordner zurück.

Erstellen

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

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. Für Aktualisierungen muss zudem eine gültige Eigenschaft vom Typ cq:model angegeben werden.

Löschen

Nutzung erfolgt über:

DELETE /{cfParentPath}/{cfName}

Beschränkungen

Es gibt einige Einschränkungen:

  • Varianten können weder geschrieben noch aktualisiert werden. Werden diese Varianten einer Nutzlast hinzugefügt (z. B. für Aktualisierungen), werden sie ignoriert. Jedoch ist die Variante über die Bereitstellung verfügbar (GET).
  • Inhaltsfragmentmodelle werden derzeit nicht unterstützt: sie können weder gelesen noch erstellt werden. Zum Erstellen eines neuen oder Aktualisieren eines vorhandenen Inhaltsfragments müssen Entwickler 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 enthält.

Statuscodes und Fehlermeldungen

Unter den entsprechenden Voraussetzungen werden möglicherweise die folgenden Statuscodes angezeigt:

  1. 202 (OK)

    Wird zurückgegeben, wenn:

    • ein Inhaltsfragment per GET
      angefordert wurde
    • ein Inhaltsfragment per PUT aktualisiert wurde
  2. 201 (Erstellt)

    Wird zurückgegeben, wenn:

    • ein Inhaltsfragment per POST erstellt wurde
  3. 404 (Nicht gefunden)

    Wird zurückgegeben, wenn:

    • das angeforderte Inhaltsfragment nicht vorhanden ist
  4. 500 (Interner Serverfehler)

    Hinweis:

    Dieser Fehler wird zurückgegeben:

    • wenn ein Fehler, der mit keinem bestimmten Code identifiziert werden kann, aufgetreten ist
    • wenn als Nutzlast „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 POST erstellt wurde)
    • Kein Inhaltsfragmentmodell bereitgestellt (Null-Wert), Ressource ist ungültig (mögliches Berechtigungsproblem) oder die Ressource ist keine gültige Fragmentvorlage:
      • Kein Inhaltsfragmentmodell angegeben
      • Ressource mit dem angegebenen Modell „/foo/bar/qux“ kann nicht erstellt werden
      • Die Ressource /foo/bar/qux“ kann nicht an eine Inhaltsfragmentvorlage angepasst werden
    • Das Inhaltsfragment konnte nicht erstellt werden (möglicherweise ein Berechtigungsproblem):
      • Inhaltsfragment konnte nicht erstellt werden
    • Titel oder Beschreibung und konnte nicht aktualisiert werden:
      • Wert konnte nicht für Inhaltsfragment festgelegt werden
    • Metadaten konnten nicht festgelegt werden:
      • Metadaten konnten nicht für Inhaltsfragment festgelegt werden
    • Inhaltselement wurde nicht gefunden oder konnte nicht aktualisiert werden
      • Inhaltselement konnte nicht aktualisiert werden
      • Fragmentdaten des Elements konnten nicht aktualisiert werden

    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}.."
      }
    }

API-Referenz

Zusätzliche Ressourcen

Weitere Informationen finden Sie unter:

Dieses Werk unterliegt den Bedingungen der Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.  Twitter™- und Facebook-Beiträge fallen nicht unter die Bedingungen der Creative Commons-Lizenz.

Rechtliche Hinweise   |   Online-Datenschutzrichtlinie