PEIQ Knowledge Base
[0-24] PEIQ PRINT API - Pages
Transportverfahren | Übertragung per Restful API (https) |
|---|---|
Objekt | PRINT NGEN Seiten |
Trigger | Request durch Drittsystem |
Typische Drittsysteme | Typische Anbindungen sind Drittsysteme zur Content-Erstellung für Online |
Beispieldaten | siehe unten |
Hier sind die Pages-Endpunkte der PRINT API beschrieben. Der aktuelle Funktionsumfang kann über folgenden Link eingesehen werden: https://mt-master-create.peiq.cloud/printapi/ui/index.html.
Insbesondere bei Updates ist es wichtig, dass das Absetzen von Requests sequenziell erfolgt. Erst nach Erhalt der Response darf erneut ein Request zum selben Element (z.B. Artikel, Seite) geschickt werden. Andernfalls können in PRINT NGEN Fehler an den betroffenen Elementen auftreten.
Inhaltsverzeichnis
Funktionalitäten der Pages-Endpunkte der PRINT API
Abrufen der Metadaten von Seiten
Abrufen der Metadaten einer Liste von Seiten
Abrufen des Layouts einer Seite
Abrufen der platzierten Artikel auf einer Seite
Preview von Seiten
Updaten von Metadaten einer bestimmten Seite
Suchen von Seiten: GET /pages/search
Über den Endpunkt “GET /pages/search” der PRINT API können von einem Drittsystem aus Seitensuchen mit bestimmten Suchkriterien im PEIQ DAM durchgeführt werden. Die Metadaten der gefundenen Seiten können anschließend über den Endpunkt „GET /pages/{id}“ im Detail abgerufen werden. Die Suchergebnisse werden nach Erstellungsdatum absteigend sortiert.
Dieser Endpunkt sucht ausschließlich Produktionsseiten, keine Vorlagenseiten.
Für die Nutzung des Endpunkts muss eine „projectId“ im Request übergeben werden, die PEIQ definiert. Mit der “projectId=Print” können die Seiten in PRINT NGEN gesucht werden.
Folgende Seiten werden automatisch aus den Suchergebnissen herausgefiltert:
Seiten im Status = ”Löschen”
Seiten von E-Paper-Produkten
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:
Suchparameter | Beschreibung |
|---|---|
objects | Objekt |
editions | Ausgabe |
categories | Ressort |
page_numbers | Seitennummer |
publication_dates | Erscheinungstag |
product_types | Produkttyp |
offset | Gibt an, welche Suchergebnisse in der Ergebnisliste am Anfang übersprungen werden sollen. |
limit | Maximale Anzahl der Suchergebnisse |
Die übergebenen Werte der einzelnen Parameter werden nicht auf Korrektheit geprüft. Fehlerhafte oder ungültige Werte führen dazu, dass keine passenden Ergebnisse im PEIQ DAM gefunden werden.
Weitere Informationen zu den Parametern “offset” und “limit” sind hier zu finden: https://peiq.atlassian.net/wiki/spaces/PPSD/pages/1989541891/0-24+PEIQ+PRINT+API+-+Articles#Suche-nach-bestimmten-Artikeln%3A-GET-%2Farticles%2Fsearch.
Abrufen der Metadaten einer Seite: GET /pages/{id}
Ist die CID (= Cluster-ID) 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 |
page_number | Nummer der Seite | SeitNr |
page_number_right | Nummer der rechten Seite | RSeitNr |
product | CID des Druckprodukts, in dem die Seite liegt | ← DDruckProdukt |
cycling_mother_id | CID der Mutterseite der Durchlaufseite. Wenn das Feld leer ist, handelt es sich nicht um eine Durchlaufseite. | CID der Mutterseite |
status | Status | Status |
shakeable | Seite mit ASSIST-Hintergrundprozess schüttelbar | DLaySchuettelbar |
shakeable_assist | Seite mit dem ASSIST-Dialog manuell schüttelbar | MitAssistSchuetteln |
Abrufen der Metadaten einer Doppelseite
Der Abruf der Metadaten einer Doppelseite über die PRINT API erfolgt auf dieselbe Weise wie bei einer Einzelseite. In der API-Response werden jedoch zusätzliche Informationen zur rechten Seite der Doppelseite bereitgestellt.
Diese zusätzlichen Felder sind:
name_right
category_index_right
category_right
page_number_right
Sie sind ebenfalls in der obenstehenden Metadatentabelle aufgeführt und dort detailliert beschrieben.
Abrufen des Layouts einer Seite
Über den Parameter “fields=layout” des Endpunktes “GET /pages/{id}” ist es möglich, das Layout einer Seite (Einzelseite oder Doppelseite) abzufragen. Beispiel:
GET /pages/78-15236370?fields=layout
Folgende Informationen werden im zusätzlichen Feld “layout” zurückgespielt:
PRINT-API-Feld | Beschreibung | PRINT-NGEN-Eigenschaft |
|---|---|---|
id | Eindeutige ID des Layoutelements innerhalb dieses Layouts | BeID |
parent_id | ID des übergeordneten Layoutelements. Der Seitencontainer hat kein übergeordnetes Element. | BeID des übergeordneten Elements |
type | Typ dieses Layoutelements: Container, Bild, Form, Text | BeTyp |
object_type | Unterkategorie des Typs: Seite, Anzeige, … | OT |
name | Name dieses Layoutelements | BeName |
region:
| Begrenzungsrechteck des Layoutelements relativ zum Seitencontainer in Millimetern in folgender Syntax: "region": {
"left": 12.5,
"top": 15,
"width": 325,
"height": 21.079999923706055
}, | - |
content_type | Cluster-Typ: “DText” (Artikel), “DBild” (Bild), “DAnzeige” (Anzeige). Nicht alle Layout-Elemente haben einen Inhaltscluster. | TabellenName |
content_id | ID des Clusters | CID |
inherit_page_id | ID der Mutterseite. Nur bei layouterbenden Seiten oder Durchlaufseiten. | CID der Mutterseite |
inherit_element_id | ID des Layoutelements auf der Mutterseite. Nur bei layouterbenden Seiten oder Durchlaufseiten. | BeID von dem Mutterelement |
template_id | ID der Vorlage für dieses Layoutelement | CID der Vorlagen |
template_name | Name der Vorlage für dieses Layoutelement | VorlagenName |
template_library | Bibliotheksname der Vorlage für dieses Layoutelement | VorlagenBibliothek |
placing_on_page | Gibt an, wo das Layoutelement automatisch durch ASSIST auf der Seite platziert werden kann. | PlatzierungAufSeite |
Abrufen des Layouts mehrerer Seiten
Über den Parameter “fields=layout” des Endpunkts “GET /pages” können die oben genannten Metadaten für mehrere Seiten (Einzelseiten und Doppelseiten) gleichzeitig abgerufen werden.
Beispielaufruf:
GET /pages/?fields=layout
Hierzu muss im Request-Body eine Liste mit den CIDs der Seiten übergeben werden. Beispielsweise:
{
"ids": [
"204-17348946",
"204-17348947",
"204-12798045",
"204-12798045",
"204-12798018"
]
}Abrufen der platzierten Artikel auf einer Seite
Diese Funktion steht aktuell nur für Einzelseiten zur Verfügung.
Über den Parameter “fields=article_boxes” des Endpunktes “GET /pages/{id}” ist es möglich, die auf einer Seite platzierten Artikel abzufragen. Bespiel:
GET /pages/78-15236370?fields=article_boxes
Folgende Informationen werden im zusätzlichen Feld “article_boxes” zurückgespielt:
PRINT-API-Feld | Beschreibung | PRINT-NGEN-Eigenschaft |
|---|---|---|
article_id | Eindeutige ID des Artikels | CID |
x | X-Position in mm relativ zum linken Seitenrand | XPos |
y | Y-Position in mm relativ zum linken Seitenrand | YPos |
width | Breite in mm des Artikelcontainers | Breite |
height | Höhe in mm des Artikelcontainers | Hoehe |
Abrufen des Seitenlayouts sowie der platzierten Artikel einer Seite
Diese Funktion steht aktuell nur für Einzelseiten zur Verfügung.
Über den Parameter “fields=layout,article_boxes” des Endpunktes “GET /pages/{id}” ist es möglich, das Layout einer Seite als auch die auf der Seite platzierten Artikel abzufragen. Beispiel:
GET /pages/78-15236370?fields=article_boxes,layout
Die zurückgespielten Informationen können den vorangegangenen Kapiteln entnommen werden.
Abrufen der Metadaten einer Liste von Seiten: GET /pages
Wie im Kapitel #Abrufen-der-Metadaten-einer-Seite%3A-GET-%2Fpages%2F%7Bid%7D erläutert, kann ein Drittsystem über die CID einer Seite Metainformationen über die PRINT API abfragen. Die oben aufgeführten Metadaten können jedoch auch für mehrere Seiten gleichzeitig abgefragt werden. Hierzu muss im Request body eine Liste mit den betreffenden CIDs übergeben werden. Beispielsweise:
{
"ids": [
"78-1523637",
"78-1523638"
]
}Als Rückinformation erhält das Drittsystem sodann eine kommaseparierte Auflistung der mitgegebenen CIDs der jeweiligen Seiten.
Preview von Seiten: GET /pages/preview/{id}/{resolution} kund:innenspezifisch
Ist die CID einer Seite bekannt, kann die Vorschau dieser Seite abgerufen werden. Hier können als “resolution” folgende Werte beim Request mitgegeben werden:
thumb: 150 PixellowRes: 320 Pixel. Diese Vorschau ist für die Darstellung von mehreren Seiten in einer Seitenübersicht empfohlen.midRes: 900 PixelhighRes: 2100 Pixel. Diese Vorschau ist für die Darstellung einzelner Seiten im Lesemodus empfohlen. HighRes-Vorschaubilder sollten nicht in hoher Frequenz abgerufen werden.
Die Pixelanzahl entspricht hier der Höhe des Bildes. Alle Auflösungen sind standardmäßig im WEBP-Format komprimiert.
Updaten von Metadaten einer bestimmten Seite: PUT /pages/{id}
Ist die CID (= Cluster-ID) einer Seite bekannt, können über den Endpunkt “PUT /pages/{id}” der PRINT API von einem Drittsystem aus folgende Metadaten der Seite upgedatet werden:
Metadaten Tabelle
PRINT-API-Feld | Beschreibung | PRINT-NGEN-Eigenschaft | Hinweis |
page_layout | Seitenaufteilung einer Seite (für Assist relevant) | SeitenAufteilung |
|
category | Ressort einer Einzelseite oder beider Seiten einer Doppelseite | DLayRessort | Es kann in einem Call nur eines von beiden Feldern (“category” oder “category_right”) mitgegeben werden. Sollen die Doppelseitenhälften unterschiedliche Ressorts bekommen, muss beim 1. Request “category” und beim 2. Request “category_right” mitgegeben werden. Das Feld “category_right” ist nur bei Doppelseiten erlaubt. |
category_right | Ressort der rechten Seite einer Doppelseite | DLayRRessort |
Hierzu muss im Request-Body eine Liste mit den betreffenden Metadaten übergeben werden. Beispielsweise:
{
"page_layout": "1_4_1",
"category": "pol"
}Das Ressort sollte für layouterbende und durchlaufende Seiten nicht geändert werden, da diese das Ressort der Mutterseite übernehmen und nicht in jedem Fall gewährleistet werden kann, dass bei Ressortänderung für eine erbende Seite über die API wieder das Ressort der Mutter gesetzt wird.
Wenn eine Ressortänderung für die Mutterseite und alle ihre erbenden Seiten erzielt werden soll, muss die Ressortänderung nur für die Mutterseite vorgenommen werden.
Nach dem Setzen eines neuen Ressorts, werden für diese Seite automatisch folgende Aktionen ausgeführt, die für die weitere Produktion notwendig sind:
Anpassen des Seitenkopfes gemäß dem neuen Ressort
Anpassen des Seitennamens, sofern kein manueller Name vergeben wurde.
Achtung: Wenn der neu generierte Name an dem Erscheinungstag bereits vergeben ist, kann der Name nicht gesetzt werden. Hier wird der Fehlercode 409 mit einer entsprechenden Fehlermeldung zurückgegeben. Das übergebene Ressort bleibt gesetzt und wird nicht auf den alten Wert zurückgesetzt.Wenn es sich um eine Mutterseite handelt, wird das neue Ressort auch an den erbenden Seiten gesetzt.
Verwandte Seiten
Disclaimer
Für die vorliegende Systemübersicht/Publikation behalten wir uns alle Rechte vor. Nachdruck, Vervielfältigung und Verbreitung (auch auszugsweise) ist nur mit schriftlicher Genehmigung der PEIQ GmbH erlaubt. Wir behalten uns vor, die Systemübersicht/Publikation jederzeit ohne vorherige Ankündigung zu ändern und/oder zu erweitern. Die vorliegenden Angaben dienen lediglich Informationszwecken. Die PEIQ GmbH übernimmt keinerlei Haftung und/oder Garantie für Fehler und/oder unvollständige Angaben in der Systemübersicht/Publikation, mit Ausnahme von vorsätzlich falschen oder arglistig verschwiegenen Angaben. Da unsere Software laufend weiter entwickelt wird, handelt es sich bei den vorliegenden nur um allgemeine Angaben. Es handelt sich weder um eine Zusicherung von Mindestvertragsinhalten, noch um Beschaffenheitsgarantien im Sinne des § 443 BGB.
Nur für PEIQ-Mitarbeiter: