PEIQ Knowledge Base
[0-24] PEIQ PRINT API
Transportverfahren | Übertragung per Restful API (https) |
---|---|
Objekt | PRINT NGEN Artikel und Seiten |
Trigger | Request durch Drittsystem |
Typische Drittsysteme | Typische Anbindungen sind Drittsysteme zur Content-Erstellung für Online |
Beispieldaten | siehe unten |
Mit den hier beschriebenen Funktionen können Artikel abgefragt, angelegt und aktualisiert 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.
Die Bereitstellung der Zugangsdaten zur Authentifizierung erfolgt durch PEIQ. Zudem sind Mitwirkungspflichten zur Aktivierung der API notwendig. Bei Interesse wenden Sie sich daher bitte an das PEIQ Support Team.
Funktionalitäten der PRINT API
Anlegen von Artikeln
Updaten von Artikeln
Abrufen der Metadaten von Artikeln
Suche nach bestimmten Artikeln
Preview von Artikeln
Abrufen der Metadaten von Seiten
Preview von Seiten
Abrufen der API Informationen
Inhaltsverzeichnis
Allgemeine Beschreibung
Funktionalitäten der PRINT API
Mit den hier beschriebenen Funktionen können Printartikel aus dem PEIQ DAM durch Dritte via Restful API abgefragt, in PRINT NGEN angelegt, geändert und vom PEIQ DAM in das Drittsystem exportiert werden.
Typische Anbindung sind Drittsysteme zur Content-Erstellung für Online.
Die DAM 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/printapi/ui/index.html
Empfohlene Verwendung der PRINT API
Anlegen eines Artikels: POST /articles/json
Über den Endpunkt POST /articles/json können in PRINT NGEN Printartikel angelegt werden. Dazu muss der Artikel im Body als gültiges JSON übergeben werden.
Die Struktur des JSONs ist im Swagger dokumentiert und entspricht der JSON-Struktur der Livingdocs API (siehe Doku [0-17] INBOUND Schnittstelle zu Livingdocs API | Artikel mit Bilder | Artikel JSON). Bei der Print API werden die Inhalte des Artikels jedoch unter “articlecontent“ übertragen anstatt unter “livingdoc”. Ein Beispiel-JSON ist unten aufgeführt.
Über das Feld “publications” wird gesteuert, ob in PRINT NGEN ein oder mehrere Printartikel für verschiedene Ausgaben erstellt werden. Die aus einem Artikel-Dokument erstellten Artikel haben in PRINT NGEN alle die gleiche externe ID (Eigenschaft “DExterneID”).
Beim Import läuft ein XSLT-Stylesheet, das die übergebenen Artikelinhalte unter “articlecontent“ in die entsprechenden Bereiche und Tags umwandelt (siehe Produktübergreifender Standard: Tags/Makros/Bereiche für XSLT Stylesheets).
Die CID des neu erstellten Artikels wird in der API-Response im Feld “created” zurückgegeben. Wurden mehrere Artikel erstellt, werden die CIDs kommasepariert angegeben. Wurde ein Artikel mit Infobox-Artikel erstellt, wird nur die CID des Hauptartikels zurückgegeben.
{
"created": [
"1-987654323"
],
"updated": []
}
Die erstellten Artikel können unter folgender Namenskonvention (“DTextName”) gefunden werden:
Artikelname des Hauptartikels: “printapi-{Externe-ID}”
z. B. “printapi-123456”Artikelname des Infoboxartikels: “printapi-{Externe-ID}_infobox{Nummer}”
z. B. “printapi-123456_infobox1”
Optional kann die Zusammensetzung des Artikelnamens kund:innenspezifisch an das angebundene System angepasst werden, z. B. “cue-123456”. Die Namenskonvention entspricht hier bei Hauptartikeln “{Name Drittsystem}-{Externe-ID}” und bei Infoboxen “{Name Drittsystem}-{Externe-ID}_infobox({Nummer bei mehr als einem Infobox-Artikel})”.
Interne Bilder
Existiert das Bild, das für einen Artikel verwendet werden soll, bereits im PEIQ DAM, so kann dieses über die CID im Feld "component": "image","content": {"ngen_id": ""} angegeben werden. Bei Verwendung eines internen Bildes werden Bildinformationen, die ggf. über das JSON übertragen werden (z. B. Bildunterschrift, Bildursprung) nicht berücksichtigt. Das Bild bleibt in PRINT NGEN unverändert.
Wenn die für das interne Bild angegebene CID nicht im System existiert oder nicht zu einem Bild gehört, wird der Artikel nicht in PRINT NGEN angelegt. In der API-Response wird dann der Fehlercode 400 mit folgender Fehlermeldung ausgegeben:
"error": "Object reference not set to an instance of an object."
Für den Image-Component kann entweder die URL eines externen Bildes unter "component": "image","content": "image": {"originalUrl": ""} oder ein internes Bild übertragen werden - nicht beides gleichzeitig.
Inhaltliche Fehler
Bei inhaltlichen / syntaktischen Fehlern im Artikel-JSON, ist das XML nicht gültig und kann damit nicht verarbeitet werden. Das XSLT zum Umwandeln der Bereiche und Tags kann nicht ablaufen und der Artikel kann somit nicht angelegt werden. In der API wird der Fehlercode 400 zurück geliefert. In der API-Response steht die Ursache, weshalb der Import fehlgeschlagen ist, z. B.:
Fehler bei der Verarbeitung des Inhalts: Fehler beim Ausführen des Xslt:'„' is an unexpected token. The expected token is '"' or '''. Line 1, position 1496.
Beispiel-JSON
{
"systemdata": {
"documentId": "3429489"
},
"metadata": {
"publications": [
{
"object": "ta",
"value": "ta-ma",
"category": "wirt",
"pageIndex": 2,
"printContentType": "aufmacher",
"date": "2024-08-25"
},
{
"object": "ta",
"value": "ta-dah",
"category": "pol",
"pageIndex": 1,
"printContentType": "standard",
"collective":"Sonderthema",
"date": "2024-08-25"
}
]
},
"articlecontent": {
"content": [
{
"component": "head",
"content": {
"catchline": "Eine Dachzeile <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>",
"title": "Ein Titel <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>",
"lead": "Eine Unterzeile <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>",
"author": "Hans Mustermann",
"authorShortnames": "HM",
"city": "München"
}
},
{
"component": "lead-p",
"content": {
"opener": "München.",
"text": "Inhalt des Vorspanns <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>."
}
},
{
"component": "p",
"content": {
"text": "Inhalt des Textes <strong>mit Text in Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup> im Absatz."
}
},
{
"component": "p",
"content": {
"text": "Das ist der zweite Absatz. Dieser Absatz besteht aus mehreren Sätzen. Das ist der dritte Satz."
}
},
{
"component": "subtitle",
"content": {
"title": "Das ist ein Zwischentitel <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>"
}
},
{
"component": "quote",
"content": {
"text": "Das ist ein Zitat <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>.",
"source": "Hans Mustermann 2024 <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>"
}
},
{
"component": "question",
"content": {
"text": "Das ist eine Frage <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>. Quo vadis?"
}
},
{
"component": "answer",
"content": {
"text": "Das ist eine Antwort <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>. Nach Rom."
}
},
{
"component": "image",
"content": {
"ngen_id": "204-11471260"
}
},
{
"component": "image",
"content": {
"caption": "Das ist die Bildbeschreibung <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>.",
"source": "Bildquelle",
"labelSource": "Quellverweis",
"image": {
"originalUrl": "https:\\meine.bilder.de\bilder_extern\u0007akjshdkjasfhkjahdkj.jpg",
"origins": [
{
"name": "Archiv XYZ",
"identifier": "XYZ_12747372"
}
],
"crop": {
"x": 100,
"y": 120,
"width": 1200,
"height": 800
}
}
}
},
{
"component": "list",
"content": {
"title": "Dies ist der Titel der Liste <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>."
},
"containers": {
"list": [
{
"component": "list_item",
"content": {
"text": "Punkt 1 <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>"
}
},
{
"component": "list_item",
"content": {
"text": "Punkt 2"
}
}
]
}
},
{
"component": "infobox",
"content": {
"title": "Der Titel der Infobox <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>",
"text": "<p>Der erste Absatz <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>.</p><p>Der zweite Absatz</p>",
"caption": "Das ist die Bildbeschreibung.",
"source": "Bildquelle",
"labelSource": "Quellverweis",
"image": {
"originalUrl": "https:\\meine.bilder.de\bilder_extern\u0007akjshdkjasfhkjahdkj.jpg",
"origins": [
{
"name": "Archiv XYZ",
"identifier": "XYZ_12747372"
}
],
"crop": {
"x": 100,
"y": 120,
"width": 1200,
"height": 800
}
}
}
},
{
"component": "infobox",
"content": {
"title": "Der Titel der zweiten Infobox ohne Bild",
"text": "<p>Der erste Absatz <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>.</p><p>Der zweite Absatz</p>"
}
},
{
"component": "infobox",
"content": {
"title": "Der Titel der Infobox 3 mit NGEN-Bild",
"text": "<p>Der erste Absatz <strong>mit Bold</strong> <em>und Kursiv</em>, <sub>mit Hochgestellt</sub> <sup>und Tiefgestellt</sup>.</p><p>Der zweite Absatz</p>",
"ngen_id": "204-11471260"
}
}
]
}
}
Updaten / Ändern eines Artikels: POST /articles/json
Beim Endpunkt POST /articles/json muss im Body des Request das vollständige Artikel-Dokument mit den Aktualisierungen in den Metadaten und dem Text als gültiges JSON mitgegeben werden. Die CIDs der aktualisierten Artikel werden in der API-Response im Feld “updated“ ausgegeben:
Wird eine “publication” bei einem Update ergänzt, wird ein neuer Artikel erstellt. Die CID des neu erstellten Artikels wird in der API-Response im Feld “created“ ausgegeben.
Wird das Feld “publications” bei einem Update leer übertragen ("publications":[]
), wird der bzw. werden die Artikel zu dieser externen ID in PRINT NGEN auf den Status “Löschen” gestuft. Das Stufen auf den Status “Löschen” wird nicht als Update gewertet. Somit bleibt das Feld “updated” in der API-Response leer:
Generell greift hier die gleiche Update-Logik wie für Livingdocs-Artikel, siehe Kund:innenspezifische Update-Logik von Livingdocs-Artikeln in PRINT NGEN. Sie ist standardmäßig in der PRINT API aktiviert und nicht statusabhängig, d. h. die Artikel zu der externen ID werden immer aktualisiert.
Abrufen der Metadaten eines Artikels: GET /articles/{id}
Ist die CID eines Artikel bekannt, kann ein Drittsystem über den Endpunkt GET /articles/{id} der PRINT API Metainformationen eines Artikels abrufen.
Über den optionalen Parameter “fields” können die Felder “text” und/oder “pages” mit abgerufen werden. Beispiel: GET {baseUrl}/articles/{id}?fields=text,pages
In der Response wird der Artikelinhalt im Feld “text” im XML-Format übergeben. Im Feld “pages” sind die IDs der Seiten aufgelistet, auf denen der Artikel platziert ist. Über den Endpunkt GET pages/{id} können die Metadaten der Seite abgerufen werden. Aus Performancegründen sollten die optionalen Felder “text” und “pages” nur dann abgerufen werden, wenn diese zwingend benötigt werden.
Metadaten Tabelle
PRINT API Feld | Beschreibung | PRINT NGEN Eigenschaft |
id | PRINT NGEN CID | CID |
external_id | Externe ID | DExterneID |
version | Versionsnummer | CV |
creation_timestamp | Erstellt Am | CED |
creation_user | Erstellt Von | CEB |
modification_timestamp | Zuletzt Geändert Am | CGD |
modification_user | Zuletzt Geändert Von | CGB |
object | Zeitungsobjekt | DTextObjekt |
edition | Ausgabe | DTextAusgabe |
category | Ressort | DTextRessort |
publication_date | Erscheinungstag | DTextErschAm |
planned_page | Für Seite | DTextGeplSeite |
format | Formatname | DTextFormatName |
name | Artikelname | DTextName |
text | Textinhalt | Text |
status | Artikelstatus | Status |
pages | Platziert auf den Seiten | ← DLayout |
Suche nach bestimmten Artikeln: GET /articles/search
Von einem Drittsystem aus können über den Endpunkt GET /articles/search der PRINT API Artikelsuchen mit bestimmten Suchbedingungen im PEIQ DAM abgesetzt werden. Im Anschluss können die gefundenen Artikelmetadaten über den Endpunkt GET article/{id} abgerufen werden. Die Ergebnisse beim Absetzen der Artikelsuche werden nach dem Erstelldatum absteigend sortiert.
Bei diesem Endpunkt muss eine “projectId” im Request mitgegeben werden, die PEIQ definiert. Mit der “projectId=Print” können die Printartikel in PRINT NGEN gesucht werden.
Für das Absetzen der Suche können mehrere Suchparameter mit “&” kombiniert werden. Die Werte der Suchparameter können kommasepariert angegeben werden. Mögliche Parameter sind:
search: Volltextsuche (Groß-/Kleinschreibung wird nicht berücksichtigt)
publication_dates: Erscheinungstag
states: Status
categories: Ressort
editions: Ausgabe
objects: Objekt
external_ids: Externe ID
offset: Gibt an, welche Suchergebnisse in der Ergebnisliste am Anfang übersprungen werden sollen.
limit: Maximale Anzahl der Suchergebnisse. Ohne Parameter “limit” werden standardmäßig 100 Ergebnisse zurückgegeben. Das Maximum sind 1.000 Ergebnisse bei einem Aufruf.
Soll per PRINT API eine Suche in PRINT NGEN abgesetzt werden, wird beim ersten Request kein Offset angegeben. In der Response kommt ein Offset zurück, der beim nächsten Aufruf mitgegeben muss, um den nächsten Block der Suchergebnisse zu erhalten. Der Offset besteht aus der Kombination aus CED und CID eines Startartikels (z. B. "20211117-11:52:58/1-16114101").
Beispiel für den Abruf der ersten 50 Artikel:
{baseUrl}/articels/search?projectId=Print&limit=50
Beispiel für den Abruf der nächsten 50 Artikel:
{baseUrl}/articels/search?projectId=Print&limit=50&offset=20210714-13:42:41/1-16059606
Abrufen der Metadaten einer Seite: GET /pages/{id}
Ist die CID einer Seite bekannt, kann ein Drittsystem folgende Metainformationen der Seite über die PRINT API abfragen:
Metadaten Tabelle
PRINT API Feld | Beschreibung | PRINT NGEN Eigenschaft |
id | PRINT NGEN CID | CID |
version | Versionsnummer | CV |
layout_version | Layout-Version | LayoutVersion |
creation_timestamp | Erstellt Am | CED |
creation_user | Erstellt Von | CEB |
modification_timestamp | Zuletzt Geändert Am | CGD |
modification_user | Zuletzt Geändert Von | CGB |
publication_date | Erscheinungstag | DLayErschAm |
type | Seitentyp (Links, Rechts, Doppel) | SeitenTyp |
object | Zeitungsobjekt | DLayObjekt |
edition | Ausgabe | DLayAusgabe |
category | Ressort | DLayRessort |
category_right | Ressort der rechten Seite einer Doppelseite | DLayRRessort |
category_index | Ressortindex | RessortIndex |
category_index_right | Ressortindex der rechten Seite einer Doppelseite | RRessortIndex |
name | Seitenname | DLayName |
name_right | Seitenname der rechten Seite einer Doppelseite | DLayRName |
product | CID des Druckproduktes, in dem die Seite liegt | ← DDruckProdukt |
cycling_page | Durchlaufseite ja/nein | DurchlaufSeite |
status | Status | Status |
Preview von Artikeln: GET /articles/preview/{id}/{resolution}/{page_id} (kundenspezifisch)
Ist die NGEN-CID eines Artikels bekannt, kann die Vorschau dieses Artikels abgerufen werden. Hier gibt es folgende Möglichkeiten:
Der Artikel ist noch nicht platziert und es soll daher die Vorschau des unplatzierten Artikels abgerufen werden. Die Abfrage erfolgt hier mit GET /articles/preview/{id}/{resolution}, wobei es sich bei der id um die CID des Artikels handelt.
Der Artikel ist bereits auf einer oder mehreren Seiten platziert und es soll die Vorschau des Artikels von einer Seite abgerufen werden. Die Abfrage erfolgt hier mit GET /articles/preview/{id}/{resolution}/{page_id}, wobei es sich bei der id um die CID des Artikels handelt. Mit page_id muss die CID der Seite mitgegeben werden, auf der der Artikel platziert ist und von der die Vorschau des Artikels abgerufen werden soll.
Der Artikel ist bereits platziert, die Seiten-CID ist jedoch nicht bekannt. Die Abfrage erfolgt hier mit GET /articles/preview/{id}/{resolution}, wobei es sich bei der id um die CID des Artikels handelt. Ist der Artikel auf mehreren Seiten platziert, wird das Layout des Artikels auf der ersten gefundenen Seite zurückgeliefert.
Als resolution können beim Request folgende Werte mitgegeben werden:
thumb: 150 Pixel
lowRes: 600 Pixel
midRes: 800 Pixel
highRes: 1900 Pixel
Die Pixelanzahl ist hier die Breite des Bildes.
Preview von Seiten: GET /pages/preview/{id}/{resolution} (kundenspezifisch)
Ist die CID einer Seite bekannt, kann die Vorschau dieser Seite abgerufen werden.
Auch hier können als resolution beim Request folgende Werte mitgegeben werden:
thumb: 150 Pixel
lowRes: 320 Pixel
midRes: 900 Pixel
highRes: 2100 Pixel
Die Pixelanzahl ist hier die Höhe des Bildes.
Abrufen der API-Informationen: GET /info
Über diesen Endpunkt kann die Version der PRINT API sowie der API User abgefragt werden.
Vergleich PRINT API vs. Livingdocs API
PRINT API | Livingdocs API |
POST /articles/json identisch wie Livingdocs API | GET v1/print/document identisch wie PRINT API |
GET /articles/search Hier werden die neusten Artikel in PRINT NGEN zurückgeliefert. Zudem stehen weitere Filtermöglichkeiten zur Verfügung. | GET api/v1/publicationEvents Hier werden die neusten, publizierten Artikel in Livingdocs zurückgeliefert. |
GET /articles/{id} | nicht vorhanden |
GET /articles/search | nicht vorhanden |
GET /pages/{id} | nicht vorhanden |
Verwandte Seiten
Nur für PEIQ-Mitarbeiter:
https://peiq.atlassian.net/wiki/x/cACZY