Adobe Experience Manager Assets-HTTP-API

Überblick

Die Assets HTTP-API ermöglicht die Erstellung-Lesen-Update-Löschvorgänge (CRUD) für digitale Assets, einschließlich Metadaten, Darstellungen und Kommentare, zusammen mit strukturierten Inhalten mit Inhaltsfragmenten Experience Manager. Sie wird unter /api/assets bereitgestellt und als REST-API implementiert. Dazu gehört die Unterstützung von Inhaltsfragmenten.

So greifen Sie auf die API zu:

  1. Öffnen Sie das Dokument zum API-Service unter https://[hostname]:[port]/api.json.
  2. Folgen Sie dem Dienstlink Assets, der zu https://[hostname]:[server]/api/assets.json führt.

Die API antwortet mit einer JSON-Datei für einige MIME-Typen und einem Antwort-Code für alle MIME-Typen. Die JSON-Antwort ist optional und kann zum Beispiel nicht für PDF-Dateien verfügbar sein. Verwenden Sie den Antwort-Code für weitere Analysen oder Aktionen.

HINWEIS

Alle API-Aufrufe zum Hochladen oder Aktualisieren von Assets oder Binärdateien im Allgemeinen (wie Darstellungen) werden für Experience Manager als Cloud Service-Bereitstellung nicht mehr unterstützt. Verwenden Sie zum Hochladen von Binärdateien stattdessen direkte binäre Upload-APIs.

Inhaltsfragmente

Ein Inhaltsfragment ist ein besonderer Asset-Typ. Sie kann u. a. für den Zugriff auf strukturierte Daten wie Texte, Zahlen und Daten verwendet werden. Da es bei standard-Elementen (z. B. Bildern oder Dokumenten) mehrere Unterschiede gibt, gelten einige zusätzliche Regeln für die Verarbeitung von Inhaltsfragmenten.

Weitere Informationen finden Sie unter Unterstützung für Inhaltsfragmente in der Experience Manager Assets HTTP-API.

Datenmodell

Die HTTP-API Assets stellt zwei Hauptelemente, Ordner und Assets (für Standard-Assets) zur Verfügung. Außerdem werden detailliertere Elemente für die benutzerdefinierten Datenmodelle bereitgestellt, die strukturierte Inhalte in Inhaltsfragmenten beschreiben. Weitere Informationen finden Sie unter Datenmodelle für Inhaltsfragmente.

Ordner

Ordner sind wie Ordner in den herkömmlichen Dateisystemen. Ordner können nur Assets, nur Ordner oder Ordner und Assets enthalten. Ordner enthalten folgende Komponenten:

Entitäten: Zu den Entitäten eines Ordners zählen die untergeordneten Elemente, z. B. die Ordner und Assets.

Eigenschaften:

  • name ist der Name des Ordners. Dies entspricht dem letzten Segment im URL-Pfad ohne die Erweiterung.
  • title Ist ein optionaler Titel des Ordners, der anstelle des Namens angezeigt werden kann
HINWEIS

Einige Eigenschaften des Ordners oder Assets sind einem anderen Präfix zugeordnet. Das jcr-Präfix von jcr:title, jcr:description und jcr:language werden mit dem dc-Präfix ersetzt. Daher enthalten im zurückgegebenen JSON dc:title und dc:description die Werte aus jcr:title bzw. jcr:description.

Links-Ordner stellen drei Links bereit:

  • self: Link zu sich selbst.
  • parent: Link zum übergeordneten Ordner.
  • thumbnail: (Optionaler) Link zu einem Ordnerminiaturbild.

Assets

In Experience Manager enthalten Assets die folgenden Elemente:

  • Die Eigenschaften und Metadaten des Assets.
  • Ursprünglich wurde die Binärdatei des Assets hochgeladen.
  • Mehrere Darstellungen wie konfiguriert. Dabei kann es sich um Bilder unterschiedlicher Größe, Videos unterschiedlicher Kodierungen oder extrahierte Seiten aus PDF- oder Adobe InDesign-Dateien handeln.
  • Optionale Kommentare.

Weitere Informationen über Elemente in Inhaltsfragmenten finden Sie unter Unterstützung von Inhaltsfragmenten in der Experience Manager Assets-HTTP-API.

In Experience Manager enthält ein Ordner die folgenden Komponenten:

  • Entitäten: Die untergeordneten Elemente von Assets sind die Ausgabedarstellungen.
  • Eigenschaften.
  • Links.

Verfügbare Funktionen

Die HTTP-API Assets umfasst die folgenden Funktionen:

HINWEIS

Zur leichteren Lesbarkeit werden in den folgenden Beispielen die vollständigen cURL-Notierungen weggelassen. Die Notation korreliert mit Resty, einem Skriptumbruch für cURL.

Abrufen von Ordnerauflistungen

Ruft eine Siren-Darstellung eines vorhandenen Ordners und seiner untergeordneten Entitäten ab (Unterordner oder Assets).

Anfrage: GET /api/assets/myFolder.json

Antwort-Codes: Die Antwort-Codes sind:

  • 200 – OK – Erfolg.
  • 404 – NICHT GEFUNDEN – Ordner existiert nicht oder ist nicht zugänglich.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Antwort: Die Klasse der zurückgegebenen Entität ist ein Asset oder ein Ordner. Die Eigenschaften der enthaltenen Entitäten bilden eine Teilmenge der vollständigen Eigenschaften jeder Entität. Um eine vollständige Darstellung der Entität zu erreichen, sollten Kunden den Inhalt der URL abrufen, auf die der Link mit einem rel von self verweist.

Erstellen von Ordnern

Erstellt eine sling: OrderedFolder am angegebenen Pfad. Wenn * anstelle eines Knotennamens angegeben wird, verwendet das Servlet den Parameternamen als Knotenname. Die Anforderung akzeptiert eine der folgenden Optionen:

  • Eine Siren-Darstellung des neuen Ordners
  • Ein Satz aus Name-Wert-Paaren, kodiert als application/www-form-urlencoded oder multipart/ form- data. Diese sind nützlich, um einen Ordner direkt aus einem HTML-Formular zu erstellen.

Eigenschaften des Ordners können auch als Parameter für die URL-Abfrage angegeben werden.

Wenn der übergeordnete Knoten des angegebenen Pfades nicht vorhanden ist, schlägt der API-Aufruf mit einem Antwort-Code 500 fehl. Ein Aufruf gibt einen Antwortcode 409 zurück, wenn der Ordner vorhanden ist.

Parameter: name ist der Ordnername.

Anfrage

  • POST /api/assets/myFolder -H"Content-Type: application/json" -d '{"class":"assetFolder","properties":{"title":"My Folder"}}'
  • POST /api/assets/* -F"name=myfolder" -F"title=My Folder"

Antwort-Codes: Die Antwort-Codes sind:

  • 201 – ERSTELLT – bei erfolgreicher Erstellung.
  • 409 - KONFLIKT - wenn Ordner vorhanden.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn die Stammsammlung nicht gefunden oder nicht aufgerufen werden kann.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Erstellen von Assets

Informationen zum Erstellen eines Assets finden Sie unter Hochladen von Assets. Ein Asset kann nicht mit der HTTP-API erstellt werden.

Aktualisieren von Asset-Binärdateien

Informationen zum Aktualisieren von Asset-Binärdateien finden Sie unter Hochladen von Assets. Sie können eine Asset-Binärdatei nicht mit der HTTP-API aktualisieren.

Aktualisieren von Metadaten eines Assets

Aktualisiert die Asset-Metadateneigenschaften. Wenn Sie eine Eigenschaft im dc:-Namespace aktualisieren, aktualisiert die API dieselbe Eigenschaft im jcr-Namespace. Die API synchronisiert die Eigenschaften unter den beiden Namespaces nicht.

Anfrage: PUT /api/assets/myfolder/myAsset.png -H"Content-Type: application/json" -d '{"class":"asset", "properties":{"dc:title":"My Asset"}}'

Antwort-Codes: Die Antwort-Codes sind:

  • 200 – OK – wenn das Asset erfolgreich aktualisiert wurde.
  • 404 – NICHT GEFUNDEN – wenn das Asset nicht gefunden oder unter dem angegebenen URI nicht aufgerufen werden konnte.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn die Stammsammlung nicht gefunden oder nicht aufgerufen werden kann.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Erstellen von Asset-Ausgabedarstellungen

Erstellen Sie eine Darstellung für ein Asset. Wenn der Name nicht als Anfrageparameter angegeben wurde, wird der Dateiname als Ausgabedarstellungsname verwendet.

Parameter: Die Parameter sind name für den Namen der Ausgabedarstellung und file als ein Dateiverweis.

Anfrage

  • POST /api/assets/myfolder/myasset.png/renditions/web-rendition -H"Content-Type: image/png" --data-binary "@myRendition.png"
  • POST /api/assets/myfolder/myasset.png/renditions/* -F"name=web-rendition" -F"file=@myRendition.png"

Antwort-Codes

  • 201 – ERSTELLT - wenn die Ausgabedarstellung erfolgreich erstellt wurde.
  • 404 – NICHT GEFUNDEN – wenn das Asset nicht gefunden oder unter dem angegebenen URI nicht aufgerufen werden konnte.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn die Stammsammlung nicht gefunden oder nicht aufgerufen werden kann.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Aktualisieren von Asset-Ausgabedarstellungen

Aktualisierungen ersetzen eine Asset-Darstellung durch die neuen Binärdaten.

Anfrage: PUT /api/assets/myfolder/myasset.png/renditions/myRendition.png -H"Content-Type: image/png" --data-binary @myRendition.png

Antwort-Codes: Die Antwort-Codes sind:

  • 200 – OK – wenn die Ausgabedarstellung erfolgreich aktualisiert wurde.
  • 404 – NICHT GEFUNDEN – wenn das Asset nicht gefunden oder unter dem angegebenen URI nicht aufgerufen werden konnte.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn die Stammsammlung nicht gefunden oder nicht aufgerufen werden kann.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Hinzufügen eines Kommentars zu einem Asset

Parameter: Die Parameter werden message für den Nachrichtentext des Kommentars und annotationData für die Anmerkungsdaten im JSON-Format verwendet.

Anfrage: POST /api/assets/myfolder/myasset.png/comments/* -F"message=Hello World." -F"annotationData={}"

Antwort-Codes: Die Antwort-Codes sind:

  • 201 – ERSTELLT - wenn der Kommentar erfolgreich erstellt wurde.
  • 404 – NICHT GEFUNDEN – wenn das Asset nicht gefunden oder unter dem angegebenen URI nicht aufgerufen werden konnte.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn die Stammsammlung nicht gefunden oder nicht aufgerufen werden kann.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Kopieren von Ordnern oder Assets

Kopiert einen Ordner oder ein Asset in dem angegebenen Pfad in ein neues Ziel.

Anfrage-Header: Die Parameter sind:

  • X-Destination – ein neuer Ziel-URI im Bereich der API-Lösung, in den die Ressource kopiert werden soll.
  • X-Depth – entweder infinity oder 0. Mit 0 werden nur die Ressource und ihre Eigenschaften kopiert und nicht ihre untergeordneten Elemente.
  • X-Overwrite – Verwenden Sie F, um ein Überschreiben eines Assets am vorhandenen Ziel zu verhindern.

Anfrage: COPY /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-copy"

Antwort-Codes: Die Antwort-Codes sind:

  • 201 – ERSTELLT – wenn der Ordner/das Asset in ein nicht vorhandenes Ziel kopiert wurde.
  • 204 – KEIN INHALT – wenn der Ordner/das Asset in ein vorhandenes Ziel kopiert wurde.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn ein Anfrage-Header fehlt.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Verschieben von Ordnern oder Assets

Verschiebt einen Ordner oder ein Asset in dem angegebenen Pfad in ein neues Ziel.

Anfrage-Header: Die Parameter sind:

  • X-Destination – ein neuer Ziel-URI im Bereich der API-Lösung, in den die Ressource kopiert werden soll.
  • X-Depth – entweder infinity oder 0. Mit 0 werden nur die Ressource und ihre Eigenschaften kopiert und nicht ihre untergeordneten Elemente.
  • X-Overwrite - Verwenden Sie T zum erzwungenen Löschen einer vorhandenen Ressource oder F zum Überschreiben einer vorhandenen Ressource.

Anfrage: MOVE /api/assets/myFolder -H"X-Destination: /api/assets/myFolder-moved"

Antwort-Codes: Die Antwort-Codes sind:

  • 201 – ERSTELLT – wenn der Ordner/das Asset in ein nicht vorhandenes Ziel kopiert wurde.
  • 204 – KEIN INHALT – wenn der Ordner/das Asset in ein vorhandenes Ziel kopiert wurde.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn ein Anfrage-Header fehlt.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Löschen eines Ordners, eines Assets oder einer Ausgabedarstellung

Löscht eine Ressource(nstruktur) im angegebenen Pfad.

Anfrage

  • DELETE /api/assets/myFolder
  • DELETE /api/assets/myFolder/myAsset.png
  • DELETE /api/assets/myFolder/myAsset.png/renditions/original

Antwort-Codes: Die Antwort-Codes sind:

  • 200 – OK – wenn der Ordner erfolgreich gelöscht wurde.
  • 412 – VORBEDINGUNG FEHLGESCHLAGEN – wenn die Stammsammlung nicht gefunden oder nicht aufgerufen werden kann.
  • 500 – INTERNER SERVER-FEHLER – wenn etwas anderes schief geht.

Tipps, Best Practices und Einschränkungen

  • Nach der Ausschaltzeit sind ein Asset und seine Ausgabedarstellungen weder über die Assets-Web-Oberfläche noch über die HTTP-API verfügbar. Die API gibt die Fehlermeldung 404 zurück, wenn die Einschaltzeit in der Zukunft oder die Ausschaltzeit in der Vergangenheit liegt.

  • Assets HTTP API gibt nicht die vollständigen Metadaten zurück. Die Namensraum sind hartcodiert und nur diese Namensraum werden zurückgegeben. Vollständige Metadaten finden Sie im Asset-Pfad /jcr_content/metadata.json.

  • Einige Eigenschaften von Ordnern oder Assets werden einem anderen Präfix zugeordnet, wenn sie mithilfe von APIs aktualisiert werden. Das jcr-Präfix von jcr:title, jcr:description und jcr:language werden mit dem dc-Präfix ersetzt. Daher enthalten im zurückgegebenen JSON dc:title und dc:description die Werte aus jcr:title bzw. jcr:description.

Auf dieser Seite