[0-21] DAM API - Images

Funktionalitäten der Images-Endpunkte der DAM API

• Anlegen von Bildern

• Suche nach Bildern

• Abrufen von Wertelisten für die Bildsuche

• Abrufen der neusten Bilder

• Abrufen der Bilddateien

• Abrufen der Bild-Metainformationen

• Ändern der Bild-Metainformationen

Inhaltsverzeichnis

Anlegen von neuen Originalbildern

POST /images

Ein Drittsystem kann Bilder über die DAM API nach PRINT NGEN übertragen. Die Bilder laufen als Originalbilder ohne Mindestverschlagwortung ein. Beim Anlegen des Bildes in PRINT NGEN werden die IPTC-Daten der Bilder ausgelesen und in die PRINT NGEN Eigenschaften geschrieben.

Bei der Übertragung des Bildes wird die Dateigröße überprüft. Die maximal zulässige Größe einer hochzuladenden Datei beträgt 104.857.600 Bytes (100 MB). 

Optional kann in der URL des Request mit dem Parameter “filename” ein Dateiname mitgegeben werden, der in die PRINT NGEN Eigenschaft “BildDateiName” übernommen wird. Ist beim Dateinamen die File-Extension enthalten, wird diese herausgefiltert. Beispiel: {baseUrl}/images?filename=test123.jpg

Bevorzugt ein Drittsystem die Übertragung per sFTP gegenüber der Übertragung per API, können Bilder alternativ auch über die Schnittstelle [0-22] INBOUND Bilder (Archiv) übertragen werden.

Sollen zudem zu den in der Bilddatei enthaltenen IPTC-Daten zusätzliche Metadaten per Metadaten-XML mitgegeben werden bzw. Updates der Bilder bzw. Metadaten erfolgen, können Bilder auch über die Schnittstelle [0-10-4] INBOUND Bilder mit Metadaten-XML übertragen werden.

Suche nach bestimmten Bildern

GET /images/search

Von einem Drittsystem aus können per DAM API Bildersuchen (mit bestimmten Suchbedingungen z. B. bestimmten Kategorien) im PEIQ DAM abgesetzt werden. Im Anschluss können die gefundenen Bilder bei Bedarf in der gewünschten Auflösung über die DAM API abgeholt werden.

Mögliche Parameter

• projectId:

  • Bei projectId="create" wird nur eine Suche unter den CREATE-Bildern abgesetzt.

  • Bei projectId="original" wird unter allen Originalbildern (Status in PRINT NEGN = “Original”) gesucht.

  • Bei projectId="dam" wird unter allen Original- und Archivbildern (Status in PRINT NGEN = “Original” oder “Archiviert”) gesucht.

  • Die Angabe der projectId ist obligatorisch.

• limit: Anzahl der Bilder, die gesucht werden sollen

• search: Volltextsuche

• categories: Ressort (IptcRes)

• services: Dienst (IptcDie)

• credit: Objektrecht (IptcOR)

• sentFrom: Erstellt ab

• sentTo: Erstellt bis

• offset oder offsetindex: Gibt an, wie viele Bilder in der Ergebnisliste am Anfang übersprungen werden sollen

Beispiel: {baseUrl}/images/search?projectId=create&limit=50&search=paderborn&offset=20211201-11:44:06/261-4018999

Response

Beim Endpunkt GET /images/search liefern die Ergebnisfelder folgende Inhalte:

• id: CID

• title: Titel/Überschirft (IptcUeb)

• caption: Caption (Text/|TagName!=BU| Text/BU)

• category: Ressort (IptcRes)

• credit: Objektrecht (IptcOR)

• location: Ort (IptcStadt)

• width: Bildbreite (BildPixelX)

• height: Bildhöhe (BildPixelY)

• object: Objekt (DBildObjekt)

• edition: Ausgabe (DBildAusgabe)

Zudem wird ein Offset mitgeliefert, mit dem im nächsten Request die nächsten Suchergebnisse gefunden werden können.

Abrufen von Wertelisten für die Bildsuche

GET images/values/categories

GET images/values/services

Ein Drittsystem kann eine Liste der Werte für die Suchparameter Ressort (“categories”) und Dienst (“services”) für die anschließende Bildsuche abrufen. Die zurückgegebenen Werte sind nur eine Auswahl der möglichen Suchwerte. Es kann auch mit anderen Werten als den aus der Liste gesucht werden.

Der Endpunkt images/values/categories gibt die Werte der PRINT NGEN Werteliste “WL_DBild_IptcRes” zurück. Der Endpunkt images/values/services gibt die Werte der Werteliste “WL_DBild_IptcDie” zurück.

Abrufen der neuesten Bilder

GET /images/latest

Ein Drittsystem kann die neuesten Bilder per DAM API abrufen. Diese Bilder können im Anschluss in der gewünschten Auflösung über die DAM API abgeholt werden.

Mögliche Parameter

• projectId

• limit

• offset: Beim ersten Aufruf wird der Offset nicht angegeben. Dann kommt beim Ergebnis ein Offset zurück, der beim nächsten Aufruf wieder mitgegeben wird, um den nächsten Block aufzusetzen. Der Offset besteht aus der Kombination aus CED und CID eines Startbildes (z. B. "20211117-11:52:58/1-16114101").

• offsetindex: Dieser enthält die Zahl der Bilder, die in der Ergebnisliste am Anfang übersprungen werden. Übergibt man also “offsetindex=100” so werden die ersten 1-100 Bilder nicht mit ausgeliefert, sondern erst ab dem 101. Bild.

Abrufen der Originalbilder

GET /images/{id}/{resolution}

Die Bilder können in folgenden Auflösungen abgerufen werden:

• HighRes

• MidRes

• LowRes

• Thumbnail

• Online

Beispielhafte Anwendungsfälle:

• Über die DAM API wurde nach bestimmen Bilden gesucht und die IDs der Bilder sind nun bekannt. Die Bilddateien können als nächstes über die ID und Angabe der gewünschten Auflösung abgerufen werden.

• Über den E-Paper-Export wurden die beschnittenen Bilder (Hard-Crop) exportiert und die IDs der zugehörigen Originalbilder (unbeschnitten) sind bekannt. Nun können die Originalbilder per DAM API in der gewünschten Auflösung abgeholt werden.

Beispiel: {baseUrl}/images/1-16116144/HighRes

Abrufen der Bild-Metainformationen

GET /images/{id}

Sind die IDs der Bilder bekannt, kann ein Drittsystem folgende Bild-Metainformationen über die DAM API abrufen, um diese auch im Drittsystem z. B. für Bildersuchen zur Verfügung zu haben:

Beispiel: {baseUrl}/images/1-16116144

Ändern von Metadaten bestehender PRINT NGEN Bilder

PUT /images/{id}

Ein Drittsystem kann Metadaten bestehender PRINT NGEN Bilder ändern. In PRINT NGEN ändern sich damit nicht die Binärdaten der Bilddatei, sondern lediglich die am Bild gespeicherten Eigenschaften.

Folgende Metadaten können geändert werden:

• caption: Caption (Text/)

• honorar_id: Honorar-Empfänger (DBildHonEmpfaenger)

• object: Objekt (DBildObjekt)

• edition: Ausgabe (DBildAusgabe)

• by_line: Autor Name (IptcAN)

• category: Ressort (IptcRes)

• location: Stadt (IptcStadt)

• credit: Objekt Recht (IptcOR)

• country: Land (IptcLand)

• date_time_created: Erstellt-Datum (IptcED)

• object_name: Objekt Name (IptcON)

• service_identifier: Dienst (IptcDie)

• source: Quelle (IptcQue)

• special_instructions: Kommentar (IptcKom)

• title: Titel (IptcUeb)

• urgency: Priorität (IptcPri)

• underline: Bildunterschrift (Text/BU)

• image_source: Bildquelle (Text/BU/Bildquelle)

• keywords: Schlagwörter (SchlagwortXml)

  • name: Name des Schlagworts

  • type: Typ/Kategorie

  • priority: Priorität

• usage_instructions: Verwendungshinweis (DBildVerwendungsHinweis)

• image_region: Bildausschnitt (BildAusschnitt)

  • height: Höhe des Ausschnitts

  • width: Breite des Ausschnitts

  • position_x: X-Koordinate des Eckpunktes des Ausschnitts oben links

  • position_y: Y-Koordinate des Eckpunktes des Ausschnitts oben links

  • Einheit für die Ausschnittsinformationen: 1/10000 zur Gesamthöhe/-breite des Bildes, d.h. height ist 10000 bei einem Ausschnitt über die volle Höhe des Bildes, width ist 10000 bei einem Ausschnitt über die volle Breite des Bildes

Die Metadaten der Bilder können nur in bestimmten Statusstufen geändert werden. Ist ein Bild z. B. schon archiviert oder steht im Status “Repro”, kommt ein entsprechender “error” zurück und die Metadaten werden nicht geändert. Auch Bilder, die sich gerade in Bearbeitung befinden, können nicht aktualisiert werden.

Verwandte Seiten

^{Nur für PEIQ-Mitarbeiter:}

https://peiq.atlassian.net/wiki/spaces/CORE/pages/915931174