Page Comparison

Funktionalitäten der DAM - API

• Abfrage von Bildern durch Dritte via Restful API und Export in verschiedenen Auflösungen

• Abfrage, Anlage und Aktualisierung von Embeds Anlegen von Assets

• Suche nach Assets

• Abrufen von Wertelisten für die Bildsuche

• Abrufen der neusten Bilder

• Abrufen der Bilddateien für Bilder und Logos

• Abrufen der Metainformationen für Bilder und Logos

• Ändern der Metainformationen für Bilder und Logos

• Abrufen der API-Infomrationen

Inhaltsverzeichnis

Allgemeine Beschreibung

Mit der den hier beschriebenen Exportfunktion Funktionen können Assets im NGEN DAM (Bilder, Logos, Embeds) durch Dritte via Restful API abgefragt gesucht und die Metadaten sowie Bilddaten in verschiedenen Auflösungen von PRINT NGEN in das Drittsystem exportiert werden. Weiterhin können Embeds über die API abgefragt, angelegt und geupdatet werdenabgefragt werden. Zudem kann das Drittsystem neue Assets anlegen und Metadaten updaten.

Typische Anbindung sind Drittsysteme zur Content-Erstellung für Online.

Die Print API korrespondiert dazu. Die in der PRINT API referenzierten Bilder sind entsprechend über die DAM API abrufbar.

Der aktuelle Funktionsumfang kann über folgenden Link eingesehen werden: https://mt-master-create-test.peiq.cloud/damapi/damapi.html

Austauschformat und Übertragung der Daten

Metadaten der Bild-Daten, die übertragen werden können:

• Pixeldaten

• IPTC-Daten (geänderte Metadaten optional)

• Bildunterschrift (optional)

• Ort/Stadt (optional)

• Kategorien (optional)

Metadaten der Embed-Daten, die übertragen werden können:

Empfohlene Verwendung der DAM API

Suche nach bestimmten Embeds

GET /embeds/{id}

Über die DAM API können einzelne Embeds aus der Datenbank abgefragt werden, die in CREATE angelegt wurden.

Beispiel: {baseUrl}/damapi/v1/embeds/{261-4048935}

Anlegen von Embeds

POST /embeds

Über die DAM API können einzelne Embeds angelegt werden. Dazu muss das Embed im body als gültiges JSON übergeben werden.

Beispiel: {baseUrl}/damapi/v1/embeds

{
  "type": "Twitter",
  "external_id": "1426915704062816260",
  "title": "Twitter Embed",
  "url": "https://twitter.com/_Seebruecke_/status/1426915704062816260",
  "html_code": "",
  "keywords": [
    {
      "name": "Twitter",
      "type": "topic",
      "priority": 5
    },
    {
      "name": "Embed",
      "type": "topic",
      "priority": 3
    }
  ],
  "settings": [
    {
      "setting": "width",
      "value": "584"
    },
  ]
}

Update von Embeds

PUT /embeds/{id}

Über die DAM API können bestimmte Embeds geupdatet werden. Im Body müssen alle Felder, die aktualisiert werden sollen, als gültiges JSON mitgegeben werden. Felder, die nicht angegeben werden, werden nicht verändert.

Beispiel: {baseUrl}/damapi/v1/embeds/{261-4048935}

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 NGen = Original) gesucht

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

Abrufen von Wertelisten

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 NGEN Werteliste WL_DBild_IptcRes zurück. 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}

Wurden z. B. über den E-Paper-Export die beschnittenen Bilder (Hard-Crop) exportiert und die IDs der zugehörigen Originalbilder (unbeschnitten) sind bekannt, können die Originalbilder per DAM API in der gewünschten Auflösung (HighRes, MidRes, LowRes, Thumbnail, Online) 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

...

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

...

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

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 ist 104857600 Bytes (100 MB). 

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

Ändern von Metadaten bestehender NGEN-Bilder

PUT /images/{id}

Ein Drittsystem kann Metadaten bestehender 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.

Maßgebliche DB-Tabellen

...

Images

Die Endpunkte für Bilder sind auf folgender Seite beschrieben: [0-21] DAM API - Images

Logos

Die Endpunkte für Logos sind auf folgender Seite beschrieben: [0-21] DAM API - Logos

Embeds

Die Endpunkte für Embeds sind auf folgender Seite beschrieben: [0-21] DAM API - Embeds. Diese Endpunkte sind nur bei Einsatz von PEIQ CREATE relevant.

Infos

Abrufen der API-Informationen

GET /info

Über diesen Endpunkt kann die Version der DAM API sowie der API User abgefragt werden. 

Maßgebliche DB-Tabellen

DBild, DLogo, DEmbed

Verwandte Seiten

^{Nur für PEIQ-Mitarbeiter:innen}

/wiki/spaces/CORE/pages/915931174