Points clés à retenir
- Définissez le format pdf sur /html/convert ; les autres formats produisent des captures d’écran.
- Contrôlez le moment de la prise de l’instantané avec wait_until et, uniquement si nécessaire, delay.
- Transmettez les informations d’authentification dans les en-têtes plutôt que d’intégrer les informations d’identification dans l’URL.
La plupart des besoins en PDF partent d’une page dont le rendu est déjà correct dans un navigateur. Effectuer le rendu de cette page côté serveur coûte généralement moins cher que de maintenir une seconde mise en page dans une bibliothèque PDF, à condition de maîtriser le moment du rendu et les entrées.
L’essentiel
- Effectuez le rendu à partir d’une URL de modèle stable et versionnée afin qu’une modification de la conception ne puisse pas altérer un document émis.
- Fusionnez les documents en plusieurs parties avec /document/merge plutôt que de concaténer les PDF vous-même.
Effectuer le rendu de la page existante
La plupart des besoins en PDF partent d’une page dont le rendu est déjà correct dans un navigateur : une facture, un relevé, un rapport. Maintenir une seconde mise en page dans une bibliothèque PDF duplique ce travail et conduit inévitablement à des divergences entre les deux. /html/convert effectue le rendu de la page avec un navigateur sans interface graphique et renvoie le résultat. C’est le réglage format: "pdf" qui distingue un document d’une capture d’écran. Le même Robot produit des fichiers jpeg, jpg et png, qui sont des images de la page plutôt que des documents paginés.
Le Robot accepte soit une valeur url désignant la page à rendre, soit un fichier HTML téléversé. Effectuer le rendu à partir d’une URL est généralement le meilleur choix pour les documents qui existent déjà sous forme de pages, car cela conserve une seule source de vérité. Le téléversement de HTML convient aux documents assemblés à la volée, pour lesquels aucune URL stable n’existe.
{
"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",
"acl": "bucket-default",
"path": "inv/1043.pdf"
}
}
}format: "pdf"
Produit le document. Les autres formats capturent plutôt une image de la page.
url ou téléversement
Effectuez le rendu d’une page existante à partir de son URL, ou téléversez le HTML généré lorsqu’aucune URL stable n’existe.
omit_background
S’applique uniquement aux images en sortie. La transparence ne peut pas être conservée dans un PDF.
Contrôler le moment de la prise de l’instantané
Le problème le plus courant est un document dont le rendu manuel est correct, mais que le Robot renvoie à moitié vide, car l’instantané a été pris avant le chargement des polices ou la fin du tracé d’un graphique. wait_until correspond à l’état de chargement du navigateur et permet d’exprimer précisément cette dépendance. Choisir le bon état de chargement résout la plupart des problèmes de synchronisation sans ajouter de latence fixe.
delay ajoute ensuite une pause fixe. Cette pause est parfois nécessaire pour les animations ou les widgets de fournisseurs externes qui se déclarent prêts avant de l’être réellement, mais elle a un coût à chaque rendu, y compris ceux qui n’en avaient pas besoin. Choisissez d’abord une valeur plus précise pour wait_until, et considérez delay comme une solution de repli plutôt que comme le choix par défaut.
wait_until
Exprime la dépendance réelle à l’état de chargement du navigateur. Privilégiez ce paramètre.
delay
Une pause fixe facturée à chaque rendu. Utilisez-la uniquement lorsqu’un état de chargement ne permet pas d’exprimer l’attente.
Feuille de style d’impression
Vérifiez la page dans l’aperçu avant impression d’un navigateur avant d’effectuer son rendu côté serveur.
Accéder aux pages protégées sans divulguer d’informations d’identification
Le rendu utilise un véritable navigateur, la page doit donc être accessible depuis Transloadit. Les documents nécessitent généralement une authentification, ce qui laisse deux possibilités. Le paramètre headers transmet les informations d’authentification avec la requête, ce qui convient à un accès par jeton. Vous pouvez aussi émettre une URL signée à courte durée de validité qui donne accès à un seul document pendant une brève période.
Utilisez un jeton à courte durée de validité dont la portée se limite à un seul document. Les en-têtes évitent de l’exposer dans l’URL, mais ne le masquent ni dans les paramètres de l’Assembly ni dans les journaux de l’application. Limitez l’accès aux enregistrements des Assemblies, masquez les jetons dans vos propres journaux et définissez notification_payload sur ["without_params"] pour exclure les paramètres des notifications.
{
"notification_payload": ["without_params"],
"steps": {
"rendered": {
"robot": "/html/convert",
"url": "https://example.com/reports/q3",
"format": "pdf",
"wait_until": "networkidle",
"headers": {
"Authorization": "Bearer ${fields.token}"
}
}
}
}headers
Transmet hors de l’URL un jeton à courte durée de validité dont la portée se limite au document. Traitez les paramètres des Assemblies et les journaux comme des données sensibles.
URL signées à usage unique
Accordez l’accès à un seul document pendant une brève période lorsque l’authentification par en-tête n’est pas disponible.
Jamais dans la chaîne de requête
Les informations d’identification qui y sont placées sont enregistrées partout où l’URL utilisée pour le rendu est stockée.
Rendre un document réémis identique à l’original
Une facture est un document à usage juridique, et la version qu’un client reçoit en mars doit toujours produire un rendu identique en novembre. Deux habitudes permettent d’y parvenir. Effectuez le rendu à partir d’une URL de modèle versionnée afin qu’une modification ultérieure de la conception ne puisse pas altérer un document déjà émis, et stockez le fichier obtenu plutôt que de le régénérer à la demande.
Les documents assemblés à partir de plusieurs parties méritent un traitement explicite. Utilisez /document/merge avec les alias document_1, document_2 et les alias as suivants pour définir l’ordre, puis bundle_steps: true pour réunir les parties. Cela évite de dépendre des noms des fichiers d’entrée ou de donner à un second service accès aux parties.
{
"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": {
"steps": [
{ "name": "cover", "as": "document_1" },
{ "name": "detail", "as": "document_2" }
],
"bundle_steps": true
},
"robot": "/document/merge"
}
}
}Versionner le modèle
Un changement de conception devrait produire de nouveaux documents, sans modifier rétroactivement ceux déjà émis.
Stocker sans régénérer
Conservez le fichier produit afin qu’une réémission soit une copie plutôt qu’un nouveau rendu.
/document/merge
Réunit des documents en plusieurs parties dans une seule Assembly ; utilisez des alias as explicites pour contrôler l’ordre.
Garder le coût du rendu prévisible
Le rendu d’une page coûte plus cher qu’une conversion de format, car il démarre un navigateur, récupère des sous-ressources et attend que la page se stabilise. Ce coût est justifié pour un document demandé par un client, mais constitue un gaspillage si le même relevé est généré à nouveau chaque fois que quelqu’un ouvre une vue en liste. La solution habituelle consiste à effectuer le rendu une fois, au moment où le document devient définitif, puis à servir le fichier stocké.
La génération en masse mérite un traitement distinct. Une exécution de fin de mois qui produit des milliers de relevés ne devrait pas concurrencer le rendu qu’un client attend. De plus, l’application d’une valeur fixe de delay à tout un lot finit par représenter un coût réel en temps et en argent. Mesurer le coût par document émis, plutôt que par Assembly, tend à révéler rapidement ces situations.
Effectuer le rendu à la finalisation
Produisez le fichier lorsque le document devient définitif, pas à chaque consultation.
Séparer les exécutions en masse
Séparez les traitements par lots de fin de mois des rendus qu’une personne attend.
Auditer les délais fixes
Une pause d’une seconde passe inaperçue une fois, mais devient coûteuse sur dix mille documents.
Vérifier le document avant qu’un client ne le voie
Un rendu peut réussir tout en étant incorrect. Le Robot renvoie un PDF valide, que le graphique ait été tracé ou non : un contrôle qui vérifie seulement si un fichier a été produit ne détectera donc pas une page blanche. Des assertions peu coûteuses détectent la plupart de ces problèmes : une taille plausible en octets, le nombre de pages attendu et la présence d’une chaîne connue, comme le numéro du document.
Effectuer un rendu au format png en plus du PDF pendant le développement permet un contrôle visuel rapide, facile à examiner lors de la revue. Comparer un nouveau rendu à une image de référence stockée permet de détecter des régressions de mise en page qu’un contrôle de la taille en octets ne peut pas repérer. Ces contrôles n’ont pas leur place dans le traitement en production, mais sont utiles dans le pipeline de déploiement des modifications du modèle.
Vérifier le contenu, pas seulement l’existence
Vérifiez le nombre de pages et un identifiant connu, plutôt que la seule existence d’un fichier.
Rendus sous forme d’images pour examen
Un rendu de la même page au format png permet d’examiner les modifications du modèle en un coup d’œil.
Comparer à une référence
La comparaison visuelle détecte les régressions de mise en page que les contrôles de taille ne repèrent pas.
Détails techniques à connaître
- Le paramètre format accepte jpeg, jpg, pdf et png. Seul pdf produit un document ; les autres valeurs permettent de capturer une image de la page.
- Le paramètre omit_background s’applique aux images produites et n’a aucun effet lorsque format vaut pdf ; la transparence ne peut donc pas être conservée dans le document.
- Le paramètre wait_until correspond à l’état de chargement du navigateur sous-jacent, ce qui permet d’attendre de façon fiable les polices, les graphiques et les données à chargement tardif avant la prise de l’instantané.
- Le paramètre delay ajoute une pause fixe une fois l’état de chargement atteint. Cette méthode manque de précision et augmente le coût et la latence de chaque rendu ; préférez donc un wait_until plus ciblé lorsque c’est possible.
- Une facture obtenue par rendu est un document à usage juridique. Effectuer le rendu à partir d’une URL de modèle immuable et stocker le fichier obtenu plutôt que de le régénérer à la demande permet de conserver une copie réémise identique à l’original.
- Comme le rendu s’effectue dans un véritable navigateur, la page doit être accessible depuis Transloadit. Les pages protégées par un cookie de session nécessitent soit une URL signée à usage unique, soit des informations d’identification transmises via le paramètre headers.
Une approche pratique
- 1
Créez le document comme une page ordinaire avec une feuille de style d’impression et vérifiez-le d’abord dans un navigateur.
- 2
Effectuez son rendu avec /html/convert en utilisant le format pdf et une valeur explicite pour wait_until.
- 3
Stockez le résultat dans un bucket privé avec les identifiants ayant servi à le produire. Utilisez bucket-default pour les buckets S3 dont les ACL sont désactivées et imposez les règles d’accès au moyen de la politique du bucket.
- 4
Fusionnez les pages complémentaires dans un seul fichier avec /document/merge lorsque le document comporte plusieurs parties.
Quand Transloadit est utile
Utilisez /html/convert avec le format pdf lorsque le document existe déjà sous forme de page web ou peut être rendu sous cette forme. Indiquez une valeur pour url, ou téléversez du HTML et laissez le Robot effectuer le rendu du fichier téléversé. Combinez-le avec /document/merge lorsque plusieurs pages doivent être réunies dans un seul fichier.
Périmètre architectural
/html/convert effectue le rendu d’une page avec un navigateur sans interface graphique et produit donc une copie visuelle paginée plutôt qu’un PDF balisé et accessible. Les documents nécessitant une structure sélectionnable, des champs de formulaire ou des formats d’archivage à long terme tels que PDF/A doivent être produits par un générateur de documents dédié.
Questions fréquentes
Pourquoi manque-t-il des graphiques ou des polices dans mon PDF ?
L’instantané a presque certainement été pris avant la fin de leur chargement. Définissez wait_until sur un état de chargement qui couvre cette dépendance. Ajoutez delay uniquement si un état de chargement ne permet pas de l’exprimer, en gardant à l’esprit que la pause est facturée à chaque rendu.
Puis-je produire un PDF avec un arrière-plan transparent ?
Non. omit_background agit sur les images en sortie et n’a aucun effet lorsque format vaut pdf. Si la transparence est requise, effectuez plutôt le rendu au format png, puis insérez cette image dans un document.
Comment effectuer le rendu d’une page nécessitant une connexion ?
Transmettez les informations d’authentification via le paramètre headers, ou émettez une URL signée à courte durée de validité dont la portée se limite à un seul document. Évitez de placer des informations d’identification dans la chaîne de requête, car l’URL utilisée pour le rendu est consignée partout où le rendu est journalisé.
Le résultat est-il un PDF accessible et balisé ?
Non. Un navigateur sans interface graphique produit une copie visuelle paginée, pas un document balisé doté d’un ordre de lecture, de champs de formulaire ou d’une conformité PDF/A. Des exigences de ce type nécessitent un générateur de documents dédié plutôt qu’un rendu de page.
Comment réunir plusieurs pages rendues dans un seul fichier ?
Effectuez le rendu de chaque partie et transmettez les résultats à /document/merge dans la même Assembly. Attribuez les alias document_1, document_2 et les alias as suivants, puis activez bundle_steps: true. Sans alias explicites, le Robot trie les fichiers par nom de fichier et non selon l’ordre des noms de Steps dans le tableau.