...
Transportverfahren | Übertragung per Restful API (https) |
---|---|
Objekt | Embeds, Bilder, NGenPRINT 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 |
Info |
---|
Mit der hier beschriebenen Exportfunktion können Embeds abgefragt, angelegt und geupdatet sowie Bilder durch Dritte via Restful API gesucht werden (Ergebnisliste mit Metadaten und Preview-Link) und Bilder in verschiedenen Auflösungen von NGen PRINT NGEN in das Drittsystem exportiert werden. |
Inhaltsverzeichnis
Expand | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Funktionalitäten der DAM-API
Mit der hier beschriebenen Exportfunktion können Bilder durch Dritte via Restful API gesucht werden (Ergebnisliste mit Metadaten und Preview-Link) und Bilder abgefragt und in verschiedenen Auflösungen von NGen 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)
Ausbaustufen
--
Mitwirkungspflichten/Beistellung des Kunden
Tests
Aufbereitung und Übertragung der Daten
Token
Zur Authentifizierung muss im Header der im folgenden beschriebenen Aufrufe ein Token mitgegeben werden. Dieser wird durch PEIQ festgelegt und bei der Einrichtung mitgeteilt.
GET /images/latest (Abfrage der neu erstellten Bilder)
Über den Endpunkt GET /images/latest können Drittsysteme die neu erstellten Bilder seit einem bestimmten Offset abfragen. Wird kein Offset mitgegeben, werden die IDs der ersten Bilder zurückgeliefert. Jede Abfrage liefert einen Offset zurück, der bei der nächsten Abfrage mitgegeben werden muss.
...
projectId (string) (erforderlich)
...
Projekt-ID, mit der die API verwendet wird (wird durch PEIQ festgelegt)
Wird verwendet, um in einem bestimmten Bilder-Pool zu suchen
...
offset (string) (beim ersten Aufruf optional, dann erforderlich)
...
Offset des Erstellungsdatums der Bilder für den Aufruf
...
limit (integer) (optional)
...
Max. Anzahl der Bilder, die abgefragt werden sollen (default: 100, maximal: 1000)
Responses
...
200
...
OK
...
400
...
Bad Request
...
401
...
Access Token fehlt oder nicht richtig
...
404
...
Es wurden für die Abfrage keine Bilder gefunden
...
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
Code Block |
---|
{ "offsettype": "stringTwitter", "idsexternal_id": ["1426915704062816260", "title": "Twitter Embed"a1ynb0#x", "9z#uexb8url" ] } |
...
offset
...
Neuer Offset des Erstellungsdatums der Bilder
...
ids
...
Bild-IDs, die die Abfrage zurückliefert
GET /images/search (Suche nach Bildern)
Über den Endpunkt GET /images/search können Drittsysteme Suchen nach Bildern im NGen DAM absetzen. Die Suche kann über beliebig viele Parameter eingeschränkt werden. Zurückgeliefert werden die Bilder in der Reihenfolge ihres Erstellungsdatums.
Parameter, die bei der Abfrage mitgegeben werden können
...
projectId (string) (erforderlich)
...
Projekt-ID, mit der die API verwendet wird (wird duch PEIQ festgelegt)
Wird verwendet, um in einem bestimmten Bilder-Pool zu suchen
...
search (string) (optional)
...
Volltextsuche (ohne Berücksichtigung der Groß-/Kleinschreibung), Suche liefert die Bilder zurück, die alle angegebenen Wörter enthält (z.B. Suche nach “angela merkel” liefert die Bilder zurück die “angela” und “merkel” enthalten)
...
categories (array (string)) (optional)
...
Suche nach Bildern mit bestimmten Kategorien/Ressorts, die gesuchten Kategorien/Ressorts sind mit “OR” verbunden, d.h. es werden die Bilder zurückgeliefert, die mindestens einer der Kategorien entsprechen
...
services (array (string)) (optional)
...
Suche nach Bildern eines/r bestimmten Dienstes/Agentur, die gesuchten Services sind mit “OR” verbunden, d.h. es werden die Bilder zurückgeliefert, die mindestens einer der Services entsprechen
...
credit (string) (optional)
...
Suche nach Bildern mit bestimmtem Copyright
...
sentFrom (string ($date-time)) (optional)
...
Suche nach Bildern, die ab einem bestimmten Zeitpunkt erstellt wurden, z.B. “2021-01-20T09:15:28Z”
...
sentFrom (string ($date-time)) (optional)
...
Suche nach Bildern, die bis zu einem bestimmten Zeitpunkt erstellt wurden, z.B. “2022-01-20T09:15:28Z”
...
offset (string) (optional)
...
Suche in bestimmtem Offset des Erstellungsdatums der Bilder
...
limit (integer) (optional)
...
Max. Anzahl der Bilder, die abgefragt werden sollen (default: 100, maximal: 1000)
Responses
...
200
...
OK
...
400
...
Bad Request
...
401
...
Access Token fehlt oder nicht richtig
...
404
...
Es wurden für die Abfrage keine Bilder gefunden
War der Aufruf OK, werden die Bild-IDs nach folgendem Schema als JSON zurückgeliefert:
Code Block |
---|
{ "offset": "string: "https://twitter.com/_Seebruecke_/status/1426915704062816260", "html_code": "", "datakeywords": [ { "idname": "stringTwitter", "captiontype": "string", topic", "priority": 5 }, { "categoryname": "stringEmbed", "credittype": "stringtopic", "locationpriority": 3 "string",} ], "settings": [ { "widthsetting": 0"width", "heightvalue": 0"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}
...
offset
...
Neuer Offset des Erstellungsdatums der Bilder
...
id
...
Bild-ID, die die Abfrage zurückliefert
...
caption
...
Beschreibung des Bildes
...
category
...
Kategorie/Ressort des Bildes
...
credit
...
Copyright des Bildes
...
location
...
Ort/Stadt des Bildes
...
width
...
Breite des Bildes (in Pixel)
...
height
...
Höhe des Bildes (in Pixel)
GET /images/[id]/[resolution]
Über den Endpunkt GET /images/[id]/[resolution] können Drittsysteme einzelne Bild-Dateien aus dem NGen DAM abrufen. Die HighRes-Auflösung kann bei allen Bild-Typen abgefragt werden, alle anderen Auflösungen nur bei JPG und PNG.
Parameter, die bei der Abfrage mitgegeben werden können
...
id (string) (erforderlich)
...
Bild-ID, die über den Endpunkt GET /images/latest oder GET /images/search zurückgeliefert wurde
...
resolution (string) (erforderlich)
...
Auflösung, die abgerufen werden soll: Thumbnail, LowRes, MidRes, HighRes
...
updateMetadata (boolean) (optional)
...
Update der IPTC-Daten in der Bild-Datei entsprechend der im DAM gespeicherten (geänderten) Metadaten
Verlangsamt die Performanc und sollte daher nur falls erforderlich auf “true” gesetzt werden (z.B. zur Archivierung)
Default ist “false”
Responses
...
200
...
OK
...
400
...
Bad Request
...
401
...
Access Token fehlt oder nicht richtig
...
404
...
Das Bild wurde nicht gefunden
War der Aufruf OK, werden die Bilder als string zurückgeliefert/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 [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.
Maßgebliche DB-Tabellen
DBild, DEmbed
...
Verwandte Seiten
Filter by label (Content by label) | |
---|---|
|
...
Related Labels | |
---|---|
|
Verwandte Seiten
|
Include Page | ||||
---|---|---|---|---|
|
Optionale, weitergehende Infos (auf Anfrage)
/wiki/spaces/CORE/pages/915931174
Historie
Change History |
---|