PEIQ Knowledge Base

[0-21] DAM API - Images

Transportverfahren

Übertragung per Restful API (https)

Objekt

Bilder, Datenbanktabelle DBild

Trigger

Request durch Drittsystem

Typische Drittsysteme

Typische Anbindungen sind Drittsysteme zur Content-Erstellung für Online

Beispieldaten

siehe unten

Hier sind die Images-Endpunkte der DAM API beschrieben, mit denen Bilder im PRINT NGEN DAM (= Digital Asset Management) angelegt, gesucht, abgerufen und geändert werden können.

Der aktuelle Funktionsumfang kann über folgenden Link eingesehen werden: PEIQ DAM API

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

Beispiel für den Abruf der ersten 500 Bilder: {baseUrl}/images/latest?projectId=create&limit=500

Beispiel für den Abruf der nächsten 500 Bilder: {baseUrl}/images/latest?projectId=create&limit=500&offset=20210714-13:42:41/1-16059606

  • 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:

Beschreibung

DAM API Feld

PRINT NGEN Eigenschaft

ArchivID

archive_id

DBildArchivID

Caption

caption

Text/
TagName!=BU,Beschreibung, IptcUeb

ErstelltAm

creation_timestamp

CED

ErstelltVon

creation_user

CEB

Bilddateiname

filename

BildDateiName

Honorarkürzel

honorar_id

DBildHonEmpfaenger

Objekt

object

DBildObjekt

Ausgabe

edition

DBildAusgabe

Bildursprung

origin

BildUrsprung

OriginalID

original_id

COID

CID

id

CID

Autorname

by_line

IptcAN

Ressort

category

IptcRes

Ort

location

IptcStadt

Objektrecht/Copyright

credit

IptcOR

Land

country

IptcLand

Aufnahmedatum

date_time_created

IptcED

Objektname

object_name

IptcON

Dienst

service_identifier

IptcDie

Quelle

source

IptcQue

Kommentar

special_instructions

IptcKom

Titel/Überschrift

title

IptcUeb

Priorität

urgency

IptcPri

Status

status

Status

Bildunterschrift (BU)

underline

Text/BU

Bildquelle innerhalb der BU

image_source

Text/BU/Bildquelle

Schlagwörter

keywords

  • type = person (für Personen) / location (für Orte) / organisation (für Organisationen) / topic (für allgemeine Schlagwörter)

  • priority = Priorität von 1 bis 5

SchlagwortXml

GeändertAm

modification_timestamp

CGD

GeändertVon

modification_user

CGB

Verwendungshinweis für zurückgezogene Bilder

usage_instructions

DBildVerwendungsHinweis

Bildbreite in Pixel

width

BildPixelX

Bildhöhe in Pixel

height

BildPixelY

SHA1-Wert

sha1

SHA1

Bildausschnitt (wird als relatives Rechteck in 1/10000 Einheiten ausgegeben)

image_region

  • height

  • width

  • position_x

  • position_y

BildAusschnitt

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: