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.
- Utilisez une authentification limitée au document et de courte durée ; les en-têtes et les champs restent visibles dans l’Assembly Status, donc protégez l’Assembly ID et l’URL de statut.
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/${assembly.id}.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é
Un document peut arriver à moitié vide lorsqu’un graphique ou une police n’est pas prêt au moment de la capture. wait_until sélectionne un état de chargement du navigateur et vaut par défaut networkidle; ses autres valeurs sont domcontentloaded, load et commit. L’inactivité du réseau ne prouve pas que les données de l’application, une animation ou un graphique différé ont fini de s’afficher. Choisir un état antérieur peut raccourcir l’attente, mais ne peut pas corriger un contenu qui manque encore avec la valeur par défaut.
delay ajoute une pause fixe après l’état de chargement sélectionné. Pour un contenu rendu tardivement, faites en premier lieu en sorte que la page soit rendue à partir de données prêtes lorsque c’est possible, puis testez un délai borné lorsque la page ne peut pas signaler sa disponibilité via son comportement de chargement. Cette pause augmente la latence à chaque rendu, y compris ceux qui n’en avaient pas besoin. Vérifiez le PDF obtenu au lieu de considérer l’inactivité du réseau ou une attente fixe comme une garantie d’exhaustivité du contenu.
wait_until
Par défaut : networkidle. Un état de chargement du navigateur ne garantit pas que le contenu de l’application est prêt.
delay
Ajoute une pause fixe après l’état de chargement sélectionné, à chaque rendu. À tester pour un contenu qui finit de s’afficher plus tard.
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 de courte durée, de préférence utilisable une seule fois, limité à un seul document. Toute personne détenant l’Assembly ID ou l’URL de statut peut récupérer l’Assembly Status sans authentification supplémentaire, y compris ses champs. L’exemple transmet le jeton via fields.token, il y est donc visible. notification_payload: ["without_params"] retire params, template et merged_params des notifications ; il ne retire pas les champs et ne masque pas le Status. N’utilisez jamais ici de jeton de compte réutilisable. Gardez les ID, les URL de statut et les réponses de statut brutes hors des journaux publics et des réponses client, masquez les jetons dans les journaux de l’application et faites expirer l’accès au document indépendamment de la conservation du Status.
{
"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 vaut par défaut networkidle et sélectionne un état de chargement du navigateur. Il ne garantit pas que les graphiques, les polices ou les données d’application différés soient prêts.
- Le paramètre delay ajoute une pause fixe une fois l’état de chargement atteint. Testez un délai borné pour un contenu rendu tardivement et tenez compte de la latence ajoutée à chaque rendu.
- 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 ?
Il est possible que la page n’ait pas fini d’afficher le contenu de son application. La valeur par défaut de wait_until est déjà networkidle, ce qui ne garantit pas que les graphiques ou les polices différés soient prêts. Effectuez le rendu à partir de données prêtes lorsque c’est possible, ou testez un délai borné après l’état de chargement. Inspectez le PDF pour confirmer que le contenu manquant apparaît ; la pause fixe augmente la latence à 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.