Wichtigste Erkenntnisse
- Legen Sie für /html/convert das Format pdf fest; die anderen Formate erzeugen stattdessen Screenshots.
- Steuern Sie mit wait_until, wann der Snapshot erstellt wird, und verwenden Sie delay nur bei Bedarf.
- Übermitteln Sie die Zugangsdaten zur Authentifizierung über Header, statt sie in die URL einzubetten.
Die meisten PDF-Anforderungen beginnen mit einer Seite, die bereits im Browser korrekt dargestellt wird. Diese Seite serverseitig zu rendern ist in der Regel kostengünstiger, als ein zweites Layout in einer PDF-Bibliothek zu pflegen, sofern Zeitpunkt und Eingaben kontrolliert werden.
Worauf es besonders ankommt
- Rendern Sie über eine stabile, versionierte Vorlagen-URL, damit eine Designänderung ein bereits ausgestelltes Dokument nicht verändern kann.
- Führen Sie mehrteilige Dokumente mit /document/merge zusammen, statt PDFs selbst zu verketten.
Bereits vorhandene Seite rendern
Die meisten PDF-Anforderungen beginnen mit einer Seite, die bereits korrekt in einem Browser gerendert wird: einer Rechnung, einem Kontoauszug oder einem Bericht. Ein zweites Layout in einer PDF-Bibliothek zu pflegen, dupliziert diese Arbeit und führt zwangsläufig dazu, dass sich die zwei Layouts auseinanderentwickeln. Der Robot /html/convert rendert die Seite mit einem Headless-Browser und gibt das Ergebnis zurück. Die Einstellung format: "pdf" unterscheidet ein Dokument von einem Screenshot. Derselbe Robot erzeugt jpeg, jpg und png; dabei handelt es sich um Bilder der Seite statt um paginierte Dokumente.
Der Robot akzeptiert entweder eine zu rendernde url oder eine hochgeladene HTML-Datei. Für Dokumente, die bereits als Seiten vorliegen, ist das Rendern einer URL meist die bessere Wahl, da so eine einzige verlässliche Quelle erhalten bleibt. Das Hochladen von HTML eignet sich für Dokumente, die dynamisch zusammengestellt werden und für die keine stabile URL vorhanden ist.
{
"steps": {
"rendered": {
"robot": "/html/convert",
"url": "https://example.com/inv/1043?v=3",
"format": "pdf",
"wait_until": "networkidle"
},
"exported": {
"use": "rendered",
"robot": "/s3/store",
"credentials": "my_s3_credentials",
"path": "inv/1043.pdf"
}
}
}format: "pdf"
Erzeugt das Dokument. Die anderen Formate erfassen stattdessen ein Bild der Seite.
url oder Upload
Rendern Sie eine vorhandene Seite anhand ihrer URL oder laden Sie generiertes HTML hoch, wenn keine stabile URL vorhanden ist.
omit_background
Gilt nur für die Bildausgabe. Transparenz kann nicht in eine PDF-Datei übernommen werden.
Zeitpunkt des Snapshots steuern
Am häufigsten tritt der Fehler auf, dass ein Dokument beim manuellen Rendern korrekt aussieht, vom Robot jedoch nur halb leer ausgegeben wird, weil der Snapshot erstellt wurde, bevor die Schriftarten geladen waren oder ein Diagramm fertig gezeichnet war. wait_until entspricht dem Ladezustand des Browsers und drückt diese Abhängigkeit präzise aus. Mit dem richtigen Ladezustand lassen sich die meisten Timing-Probleme beheben, ohne eine feste Latenz hinzuzufügen.
delay fügt danach eine feste Pause ein. Sie ist gelegentlich für Animationen oder Drittanbieter-Widgets erforderlich, die ihre Bereitschaft zu früh melden. Diese Pause fällt jedoch bei jedem einzelnen Render-Vorgang an, auch wenn sie nicht benötigt wird. Verwenden Sie zuerst ein spezifischeres wait_until und behandeln Sie delay als Ausweichlösung statt als Standard.
wait_until
Drückt die tatsächliche Abhängigkeit vom Ladezustand des Browsers aus. Bevorzugen Sie diese Option.
delay
Eine feste Pause, die bei jedem Render-Vorgang anfällt. Verwenden Sie sie nur, wenn sich die Wartebedingung nicht durch einen Ladezustand ausdrücken lässt.
Druck-Stylesheet
Prüfen Sie die Seite in der Druckvorschau eines Browsers, bevor Sie sie serverseitig rendern.
Auf geschützte Seiten zugreifen, ohne Zugangsdaten offenzulegen
Da beim Rendern ein echter Browser ausgeführt wird, muss die Seite für Transloadit erreichbar sein. Dokumente liegen üblicherweise hinter einer Authentifizierung, sodass zwei praktikable Optionen bleiben. Der Parameter headers übermittelt die Authentifizierung mit der Anfrage und eignet sich damit für tokenbasierten Zugriff. Alternativ können Sie eine kurzlebige signierte URL ausstellen, die für einen kurzen Zeitraum Zugriff auf genau ein Dokument gewährt.
Zugangsdaten sollten Sie keinesfalls in den Query-String der gerenderten URL aufnehmen. Solche URLs landen in Protokollen und im gespeicherten Datensatz des gerenderten Inhalts. Anders als ein Header lassen sie sich problemlos wiederverwenden, falls dieser Datensatz offengelegt wird.
{
"steps": {
"rendered": {
"robot": "/html/convert",
"url": "https://example.com/reports/q3",
"format": "pdf",
"wait_until": "networkidle",
"headers": [
"Authorization: Bearer ${fields.token}"
]
}
}
}headers
Übermittelt Tokens mit der Anfrage statt in der URL, sodass sie nicht in Protokollen erscheinen.
Signierte Einmal-URLs
Gewährt für einen kurzen Zeitraum Zugriff auf ein einzelnes Dokument, wenn keine Header-Authentifizierung verfügbar ist.
Niemals im Query-String
Dort hinterlegte Zugangsdaten werden überall aufgezeichnet, wo die gerenderte URL gespeichert wird.
Neu ausgestelltes Dokument mit dem Original identisch halten
Eine Rechnung ist ein Dokument für rechtliche Zwecke, und die Version, die ein Kunde im März erhält, sollte im November noch identisch gerendert werden. Zwei Vorgehensweisen gewährleisten das. Rendern Sie über eine versionierte Vorlagen-URL, damit eine spätere Designänderung ein bereits ausgestelltes Dokument nicht verändern kann, und speichern Sie die resultierende Datei, statt sie bei Bedarf neu zu erzeugen.
Aus mehreren Teilen zusammengesetzte Dokumente sollten Sie ausdrücklich als solche verarbeiten. /document/merge führt gerenderte Seiten innerhalb derselben Assembly zu einer Datei zusammen. So bleibt ihre Reihenfolge deterministisch und Sie vermeiden einen zweiten Dienst, der Zugriff auf die einzelnen Teile benötigt.
{
"steps": {
"cover": {
"robot": "/html/convert",
"url": "https://example.com/stmt/cover?v=3",
"format": "pdf",
"wait_until": "networkidle"
},
"detail": {
"robot": "/html/convert",
"url": "https://example.com/stmt/detail?v=3",
"format": "pdf",
"wait_until": "networkidle"
},
"statement": {
"use": ["cover", "detail"],
"robot": "/document/merge"
}
}
}Vorlage versionieren
Eine Designänderung sollte neue Dokumente erzeugen und nicht bereits ausgestellte Dokumente rückwirkend verändern.
Speichern statt neu generieren
Bewahren Sie die erzeugte Datei auf, damit eine erneute Ausgabe als Kopie statt durch neues Rendern erfolgt.
/document/merge
Führt mehrteilige Dokumente in einer Assembly mit deterministischer Reihenfolge zusammen.
Rendering-Kosten planbar halten
Das Rendern einer Seite ist aufwendiger als eine Formatkonvertierung, da dabei ein Browser gestartet wird, Unterressourcen abgerufen werden und auf den stabilen Zustand der Seite gewartet wird. Dieser Aufwand ist für ein von einem Kunden angefordertes Dokument angemessen, aber unnötig, wenn derselbe Kontoauszug jedes Mal neu gerendert wird, sobald jemand eine Listenansicht öffnet. Üblicherweise rendern Sie das Dokument daher einmal bei seiner Finalisierung und liefern anschließend die gespeicherte Datei aus.
Die Massengenerierung sollte separat behandelt werden. Ein Monatsendlauf, der Tausende Kontoauszüge erzeugt, sollte nicht mit einem Render-Vorgang konkurrieren, auf den ein Kunde wartet. Zudem summiert sich ein festes delay in einem solchen Batch zu erheblichem Zeit- und Kostenaufwand. Wenn Sie die Kosten pro ausgestelltem Dokument statt pro Assembly messen, werden solche Muster meist schnell sichtbar.
Bei der Finalisierung rendern
Erzeugen Sie die Datei bei der Finalisierung des Dokuments und nicht bei jedem Aufruf.
Massenläufe trennen
Trennen Sie Monatsend-Batches von Render-Vorgängen, auf die eine Person wartet.
Feste Verzögerungen prüfen
Eine Pause von einer Sekunde fällt einmal nicht auf, verursacht bei zehntausend Dokumenten jedoch hohe Kosten.
Dokument prüfen, bevor Kunden es sehen
Ein Render-Vorgang kann erfolgreich sein und dennoch ein falsches Ergebnis liefern. Der Robot gibt unabhängig davon, ob das Diagramm gezeichnet wurde, eine gültige PDF-Datei zurück. Eine Prüfung, die nur ermittelt, ob eine Datei erzeugt wurde, erkennt daher keine leere Seite. Einfache Plausibilitätsprüfungen decken die meisten Fehler ab: eine realistische Bytegröße, die erwartete Seitenzahl und das Vorhandensein einer bekannten Zeichenfolge wie der Dokumentnummer.
Wenn Sie während der Entwicklung neben dem PDF auch in png rendern, erhalten Sie eine schnelle visuelle Kontrolle, die sich bei der Prüfung leicht mit bloßem Auge durchführen lässt. Der Vergleich eines neuen Renderings mit einem gespeicherten Referenzbild deckt zudem Layoutregressionen auf, die sich durch eine Prüfung der Bytegröße nicht erkennen lassen. Beides gehört nicht in den Produktionspfad, ist aber für die Pipeline sinnvoll, mit der Vorlagenänderungen ausgeliefert werden.
Inhalt statt Existenz prüfen
Prüfen Sie die Seitenzahl und einen bekannten Identifikator, statt nur festzustellen, ob eine Datei vorhanden ist.
Bild-Renderings zur Prüfung erzeugen
Ein png derselben Seite macht Vorlagenänderungen auf einen Blick überprüfbar.
Mit einer Referenz vergleichen
Ein visueller Vergleich deckt Layout-Regressionen auf, die bei Größenprüfungen unentdeckt bleiben.
Wissenswerte technische Details
- Der Parameter format akzeptiert jpeg, jpg, pdf und png. Nur pdf erzeugt ein Dokument; die übrigen Formate erfassen ein Bild der Seite.
- Der Parameter omit_background gilt für die Bildausgabe und hat keine Auswirkung, wenn format auf pdf gesetzt ist. Transparenz kann daher nicht in das Dokument übernommen werden.
- Der Parameter wait_until entspricht dem zugrunde liegenden Ladezustand des Browsers. Damit lässt sich zuverlässig warten, bis Schriftarten, Diagramme und spät geladene Daten verfügbar sind, bevor der Snapshot erstellt wird.
- Der Parameter delay fügt eine feste Pause ein, nachdem der Ladezustand erreicht wurde. Dieses grobe Mittel erhöht bei jedem Rendern die Kosten und Latenz. Verwenden Sie daher nach Möglichkeit einen spezifischeren Wert für wait_until.
- Eine gerenderte Rechnung ist ein Dokument für rechtliche Zwecke. Wenn Sie über eine unveränderliche Vorlagen-URL rendern und die resultierende Datei speichern, statt sie bei Bedarf neu zu erzeugen, bleibt eine erneut ausgestellte Kopie mit dem Original identisch.
- Da das Rendering in einem echten Browser erfolgt, muss die Seite für Transloadit erreichbar sein. Seiten, die durch ein Session-Cookie geschützt sind, benötigen entweder eine signierte Einmal-URL oder Zugangsdaten, die über den Parameter headers übergeben werden.
Ein praxisnaher Ansatz
- 1
Erstellen Sie das Dokument als normale Seite mit einem Druck-Stylesheet und überprüfen Sie es zunächst in einem Browser.
- 2
Rendern Sie es mit /html/convert im Format pdf und einem explizit angegebenen wait_until.
- 3
Speichern Sie das Ergebnis zusammen mit den zugehörigen Identifikatoren in Ihrem eigenen Bucket.
- 4
Führen Sie ergänzende Seiten mit /document/merge zu einer einzigen Datei zusammen, wenn das Dokument aus mehreren Teilen besteht.
Wann Transloadit hilfreich ist
Verwenden Sie /html/convert mit dem Format pdf, wenn das Dokument bereits als Webseite vorliegt oder als solche gerendert werden kann. Geben Sie eine url an, oder laden Sie HTML hoch und lassen Sie den Robot die hochgeladene Datei rendern. Kombinieren Sie den Robot mit /document/merge, wenn mehrere Seiten in eine Datei gehören.
Architekturgrenze
/html/convert rendert eine Seite mit einem Headless-Browser und erzeugt daher eine paginierte visuelle Kopie statt einer barrierefreien PDF-Datei mit Tags. Dokumente, die eine auswählbare Struktur, Formularfelder oder Langzeitarchivformate wie PDF/A benötigen, sollten mit einem speziellen Dokumentgenerator erstellt werden.
Häufig gestellte Fragen
Warum fehlen in meiner PDF-Datei Diagramme oder Schriftarten?
Der Snapshot wurde mit ziemlicher Sicherheit erstellt, bevor diese Inhalte vollständig geladen waren. Setzen Sie wait_until auf einen Ladezustand, der die Abhängigkeit abdeckt. Fügen Sie delay nur hinzu, wenn sich dies nicht durch einen Ladezustand ausdrücken lässt. Beachten Sie dabei, dass die Pause bei jedem Rendern berechnet wird.
Kann ich eine PDF-Datei mit transparentem Hintergrund erstellen?
Nein. omit_background wirkt sich auf die Bildausgabe aus und hat keine Wirkung, wenn format auf pdf gesetzt ist. Wenn Transparenz erforderlich ist, rendern Sie stattdessen als png und fügen Sie dieses Bild in ein Dokument ein.
Wie rendere ich eine Seite, für die eine Anmeldung erforderlich ist?
Übergeben Sie die Authentifizierung über den Parameter headers oder verwenden Sie eine kurzlebige signierte URL, deren Berechtigungsumfang auf das einzelne Dokument beschränkt ist. Platzieren Sie keine Zugangsdaten im Query-String, da die gerenderte URL überall dort aufgezeichnet wird, wo das Rendern protokolliert wird.
Ist die Ausgabe eine barrierefreie PDF-Datei mit Tags?
Nein. Ein Headless-Browser erzeugt eine paginierte visuelle Kopie und kein Dokument mit Tags, Lesereihenfolge, Formularfeldern oder PDF/A-Konformität. Für solche Anforderungen ist statt des Renderns einer Seite ein spezieller Dokumentgenerator erforderlich.
Wie führe ich mehrere gerenderte Seiten zu einer einzigen Datei zusammen?
Rendern Sie jeden Teil und übergeben Sie die Ergebnisse innerhalb derselben Assembly an /document/merge. Wenn die Zusammenführung in der Assembly erfolgt, bleibt die Reihenfolge deterministisch und kein weiterer Dienst muss Zugriff auf die einzelnen Teile erhalten.