[0-21] PEIQ DAM-API

IN BEARBEITUNG

Inhaltsverzeichnis

Funktionalitäten der DAM-API

Mit der hier beschriebenen Exportfunktion können Bilder durch Dritte via Restful API abgefragt und in verschiedenen Auflösungen von PRINT NGEN in das Drittsystem exportiert werden.

Weiterhin können Embeds über die API abgefragt, angelegt und geupdatet werden.

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

Der aktuelle Funktionsumfang kann über Swagger UI 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:

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

DBild, DEmbed

Verwandte Seiten

• Page:
  PEIQ Schnittstellen und Bebauungsplan
• Page:
  [0-15] OUTBOUND Online-Export CREATE-Artikel

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

/wiki/spaces/CORE/pages/915931174