PEIQ Knowledge Base
[0-21] PEIQ DAM-API
in bearbeitung
Transportverfahren | Übertragung per Restful API (https) |
|---|---|
Objekt | Embeds, Bilder, PRINT NGEN-ID und Hash-Wert als eindeutige Merkmale |
Trigger | Request durch Drittsystem |
Typische Drittsysteme | Typische Anbindungen sind Drittsysteme zur Content-Erstellung für Online |
Beispieldaten | siehe unten |
Mit der hier beschriebenen Exportfunktion können Embeds abgefragt, angelegt und geupdatet sowie Bilder durch Dritte via Restful API gesucht (Ergebnisliste mit Metadaten und Preview-Link) und in verschiedenen Auflösungen von PRINT NGEN in das Drittsystem exportiert werden.
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:
Embed-Typ
Externe ID
Titel
URL
Embed-Code
Keywords
Zusatz-Attribute
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/ |
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
| 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
| 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 https://peiq.atlassian.net/wiki/spaces/PPSD/pages/934510607 ü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 https://peiq.atlassian.net/wiki/spaces/PPSD/pages/1050247173 übertragen werden.
Maßgebliche DB-Tabellen
DBild, DEmbed
Verwandte Seiten
Optionale, weitergehende Infos (auf Anfrage)
Historie
| Version | Date | Comment |
|---|---|---|
| Current Version (v. 33) | 2023-05-09 12:05 | Alexander Steichele |
| v. 32 | 2023-05-09 09:21 | Johanna Cüsters |
| v. 31 | 2023-05-09 09:10 | Johanna Cüsters |
| v. 30 | 2023-04-05 08:10 | Daniela Nguyen |
| v. 29 | 2023-04-03 14:37 | Daniela Nguyen |
| v. 28 | 2022-11-25 10:20 | Daniela Nguyen |
| v. 27 | 2022-08-22 09:39 | Alexander Steichele |
| v. 26 | 2022-08-05 12:26 | Former user |
| v. 25 | 2022-08-04 06:31 | Violetta Stegen |
| v. 24 | 2022-07-27 10:54 | Violetta Stegen |
| v. 23 | 2022-07-20 09:25 | Violetta Stegen |
| v. 22 | 2022-06-21 08:31 | Daniela Nguyen |
| v. 21 | 2022-06-21 06:16 | Violetta Stegen |
| v. 20 | 2022-06-17 14:27 | Daniela Nguyen |
| v. 19 | 2022-06-15 12:59 | Former user |
| v. 18 | 2022-06-10 14:01 | Daniela Nguyen |
| v. 17 | 2022-06-10 14:00 | Daniela Nguyen |
| v. 16 | 2022-05-17 09:49 | Daniela Nguyen |
| v. 15 | 2022-04-20 11:42 | Former user |
| v. 14 | 2022-02-21 10:55 | Violetta Stegen |
| v. 13 | 2022-02-21 10:54 | Violetta Stegen |
| v. 12 | 2022-02-15 09:35 | Violetta Stegen |
| v. 11 | 2022-02-15 09:30 | Violetta Stegen |
| v. 10 | 2022-02-14 12:53 | Violetta Stegen |
| v. 9 | 2022-02-11 14:45 | Manh Long Nguyen |
| v. 8 | 2022-02-03 10:46 | Violetta Stegen |
| v. 7 | 2022-02-02 12:25 | Violetta Stegen |
| v. 6 | 2022-02-02 10:06 | Violetta Stegen |
| v. 5 | 2022-02-01 11:12 | Violetta Stegen |
| v. 4 | 2022-01-31 12:24 | Violetta Stegen |
| v. 3 | 2022-01-31 12:08 | Violetta Stegen |
| v. 2 | 2022-01-31 12:07 | Violetta Stegen |
| v. 1 | 2021-11-03 14:25 | Katharina Marxreiter |