Points clés à retenir
- Utilisez
/upload/handlesuivi de/tus/storepour transmettre sans modification un fichier téléversé à un point de terminaison compatible avec tus. - Exécutez
/image/optimizeavant/tus/storelorsque le système récepteur doit recevoir une image optimisée. - Exécutez
/video/encodeavec un préréglage testé avant/tus/storelorsque la destination doit recevoir une variante destinée à la lecture.
Le protocole tus permet le téléversement avec reprise ; ce n’est pas un produit de stockage objet. Dans ces flux de travail, un client téléverse en premier lieu vers une Assembly Transloadit, des Steps facultatifs de traitement d’images ou de vidéos créent la sortie souhaitée, puis /tus/store lance un téléversement tus sortant distinct vers le point de terminaison de destination configuré. Cette distinction compte pour les informations d’identification, les nouvelles tentatives, les URL de résultat et la réconciliation de l’application.
L’essentiel
- Stockez les en-têtes d’autorisation de la destination dans des informations d’identification de Template de type HTTP plutôt que dans des Instructions visibles par le navigateur.
- Réconciliez l’Assembly et l’application réceptrice avant de marquer une ressource comme prête dans l’état du produit.
Modéliser tus comme une frontière de livraison
Un téléversement vers Transloadit et un export via /tus/store sont deux transferts distincts. Le premier fait entrer les octets du client dans une Assembly. L’Assembly peut laisser le fichier inchangé ou créer une image ou une vidéo dérivée. Le second transfert envoie le résultat sélectionné de Transloadit vers votre point de terminaison tus. Cette architecture est utile lorsque la plateforme réceptrice expose déjà tus, mais que vous souhaitez tout de même bénéficier d’un traitement géré avant la livraison.
Tout ce qui suit l’achèvement du protocole relève de la destination. Son application décide de déplacer le fichier téléversé vers un stockage durable, de créer un enregistrement de ressource, d’effectuer une analyse de sécurité du fichier, de le publier ou de le rejeter ultérieurement. Enregistrez à la fois l’identifiant de l’Assembly et l’identité stable attribuée par le système récepteur. Ne supposez pas que l’URL de téléversement tus est un identifiant d’objet permanent ou une URL de livraison permettant la lecture, sauf si le système récepteur garantit explicitement ce contrat.
Transfert entrant
Client → Assembly Transloadit, avec la méthode de téléversement sélectionnée par le SDK ou l’intégration.
Transfert sortant
Résultat de l’Assembly → /tus/store → point de terminaison de destination configuré, compatible avec tus.
Frontière de durabilité
La persistance et la publication côté réception restent en dehors du protocole tus et du flux de travail Transloadit.
Relayer un fichier téléversé sans le transformer
Utilisez le Template de téléversement seul lorsque la destination doit recevoir le fichier original accepté par l’Assembly. /upload/handle expose cette entrée sous la forme :original, et /tus/store la sélectionne via use. Le paramètre obligatoire endpoint doit contenir l’URL de destination qui crée les téléversements tus, et non l’URL d’un objet existant ou d’une page de téléchargement dans un navigateur.
L’exemple référence des informations d’identification de Template de type HTTP pour les en-têtes statiques de la destination. Conservez allow_steps_override à false lorsque les clients ne doivent ni remplacer le point de terminaison, ni supprimer l’authentification, ni rediriger un fichier. Si le récepteur a besoin du contexte du locataire ou de la ressource, préférez des métadonnées non secrètes avec un point de terminaison autorisé par le serveur ou un ensemble d’informations d’identification à portée limitée, et validez de nouveau ce contexte côté récepteur.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"delivered": {
"use": ":original",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Optimiser une image avant sa livraison via tus
Pour un contrat limité aux images, reliez /image/optimize à :original et livrez le résultat du Step optimized. L’exemple conserve les métadonnées et utilise une optimisation PNG sans perte (lossy: false) ; cette option n’affecte pas l’optimisation JPEG, GIF, WebP ou SVG. Évaluez si la suppression des métadonnées ou l’optimisation PNG avec perte est appropriée avant de modifier ces paramètres, car l’une comme l’autre peut altérer des informations attendues par l’application réceptrice. La valeur priority: "compression-ratio" de l’exemple, différente de celle par défaut, privilégie une sortie plus petite au détriment de la vitesse de traitement ; conversion-speed, la valeur par défaut, fait le compromis inverse.
Cette recette ne redimensionne pas l’image et ne change pas son format. Ajoutez /image/resize avant l’optimisation lorsque le système récepteur exige des dimensions fixes ou un format précis. Stockez ou livrez l’original séparément lorsque la récupération et un retraitement ultérieur sont importants. Un type d’image non pris en charge peut traverser /image/optimize sans modification ; effectuez donc une validation explicite lorsque le système récepteur impose un format.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"optimized": {
"use": ":original",
"robot": "/image/optimize",
"priority": "compression-ratio",
"preserve_meta_data": true,
"lossy": false
},
"delivered": {
"use": "optimized",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Encoder une vidéo avant sa livraison via tus
Pour un contrat limité aux vidéos, reliez /video/encode au téléversement et fournissez à /tus/store le Step contenant le résultat encodé. web/mp4/720p constitue un point de départ concret pour du MP4 avec une résolution définie, et non une recommandation universelle de préréglage. Testez les dimensions de la source, la fréquence d’images, l’audio, les sous-titres, la compatibilité de lecture, le temps de traitement et le coût au regard des exigences réelles du système récepteur.
L’encodage vidéo et le transfert tus sortant peuvent chacun se prolonger au-delà de la durée d’une requête de l’application. Utilisez Assembly Status ou un callback d’achèvement vérifié, puis contrôlez l’état d’achèvement propre à l’application réceptrice. Stockez ou relayez la source séparément lorsqu’elle est nécessaire pour un réencodage de meilleure qualité, un audit, une récupération ou une migration.
{
"allow_steps_override": false,
"steps": {
":original": { "robot": "/upload/handle" },
"encoded": {
"use": ":original",
"robot": "/video/encode",
"preset": "web/mp4/720p"
},
"delivered": {
"use": "encoded",
"robot": "/tus/store",
"endpoint": "https://uploads.example.com/files/",
"credentials": "my_tus_http_credentials"
}
}
}Choisir les en-têtes, les métadonnées et les URL rapportées de manière réfléchie
Utilisez des informations d’identification de Template de type HTTP pour les en-têtes d’autorisation statiques. Le Robot accepte aussi des valeurs dynamiques de headers, mais la signature des Instructions garantit uniquement leur intégrité, jamais leur confidentialité : un navigateur peut lire tout ce qu’il soumet. Les secrets dynamiques ne doivent donc jamais apparaître dans des Instructions visibles par le navigateur. Conservez-les dans des informations d’identification de Template, ou soumettez l’Assembly de serveur à serveur pour que les valeurs n’atteignent jamais le navigateur. Les métadonnées de destination forment une table de correspondance distincte : le Robot remplace les valeurs de filename, basename et extension fournies par l’appelant par des informations issues du fichier traité, tandis que les autres clés sont transmises telles qu’elles ont été définies. Gardez les métadonnées de petite taille, non secrètes et conformes aux champs que le récepteur valide réellement, plutôt que de les traiter comme une autorisation.
Sans url_template, le Robot rapporte l’URL de téléversement renvoyée par la destination. Si ssl_url_template est omis, cette URL ne peut être réutilisée que si elle commence par HTTPS. Les modèles modifient la présentation du résultat ; ils ne modifient pas les permissions du système récepteur, ne transforment pas une URL de téléversement en point de terminaison de téléchargement et ne garantissent pas la stabilité à long terme. Enregistrez l’identifiant canonique de la ressource attribué par le système récepteur une fois que celui-ci a traité le fichier téléversé.
Tester les nouvelles tentatives et rapprocher les états des deux systèmes
Testez les autorisations expirées, les rejets par le point de terminaison, les transferts interrompus, les nouvelles tentatives, les livraisons en doublon, les dépassements de délai du système récepteur et les échecs de traitement côté réception. Rendez la gestion de l’achèvement idempotente, car une notification d’Assembly ou un événement en aval peut être livré plus d’une fois. Le système récepteur devrait rejeter tout contexte faisant référence à un autre locataire, même si un client est parvenu à modifier des métadonnées non secrètes.
Journalisez l’identifiant de l’Assembly, la catégorie du point de terminaison de destination et l’identifiant de la ressource dans le système récepteur, sans journaliser les en-têtes d’autorisation. La durée d’environ 24 heures s’applique uniquement à la copie temporaire du résultat de l’Assembly conservée par Transloadit ; rapprochez donc l’état du système récepteur avant l’expiration de cette copie. Ne considérez la ressource du produit comme prête qu’après la livraison du résultat attendu de l’Assembly et la confirmation, par le système récepteur, de l’état durable ou publié prévu. Ce rapprochement explicite transforme un transfert réussi au niveau du protocole en un flux de travail applicatif fiable.
Détails techniques à connaître
/tus/storeexporte les fichiers sélectionnés parusevers l’URL obligatoire indiquée dans son paramètreendpoint.- Le Robot accepte des informations d’identification de Template de type HTTP afin que des en-têtes d’autorisation statiques puissent être envoyés à la destination sans apparaître dans les Instructions.
- Les en-têtes dynamiques facultatifs
headerssont envoyés à la destination, mais les secrets visibles dans le navigateur resteraient exposés et devraient être évités. - Le Robot définit toujours les clés de métadonnées
filename,basenameetextensionà partir du fichier traité, en remplaçant les valeurs fournies par l’appelant pour ces clés ; les autres clés demetadatasont transmises telles qu’elles ont été définies. - Lorsque
url_templateest absent, le résultat utilise l’URL de téléversement fournie par le serveur tus de destination. - Lorsque
ssl_url_templateest absent, l’URL de téléversement de destination renseigne le champssl_urldu résultat uniquement si cette URL commence par HTTPS. /image/optimizelaisse passer les types d’images non pris en charge sans les modifier ; validez donc les entrées lorsque la destination exige un résultat optimisé./video/encodeaccepte des préréglages tels queweb/mp4/720p, et chaque préréglage doit être testé au regard des exigences de lecture de la destination.- Les résultats temporaires sont normalement conservés pendant 24 heures. Sélectionner « Ne pas enregistrer » peut empêcher le stockage de nouveaux résultats, mais ne supprime pas immédiatement les objets R2 existants. Les fichiers déjà stockés dans R2 restent soumis au cycle de vie minimal de 24 heures de R2. La conservation durable relève de la destination tus réceptrice.
Une approche pratique
- 1
Vérifiez que la destination implémente le protocole tus et définissez ce qu’elle fait une fois le téléversement terminé.
- 2
Créez un ensemble d’informations d’identification de Template de type HTTP pour les en-têtes statiques de la destination et enregistrez des Templates distincts pour le téléversement, les images et les vidéos.
- 3
Testez l’authentification, la reprise des transferts interrompus, les livraisons en doublon, le comportement des URL de résultat et la persistance côté réception.
- 4
Enregistrez l’identifiant de l’Assembly avec l’identité stable de la ressource dans le système récepteur et rapprochez les états d’achèvement de manière idempotente.
Quand Transloadit est utile
Utilisez /tus/store lorsqu’une destination existante accepte les téléversements tus et qu’une Assembly Transloadit doit lui transmettre un original ou un résultat traité. Utilisez un Robot de stockage propre au fournisseur lorsque Transloadit doit prendre en compte une API de bucket et des paramètres d’accès propres au stockage.
Périmètre architectural
/tus/store transmet un résultat sélectionné de l’Assembly à un point de terminaison compatible avec tus. Le protocole tus définit le transfert avec reprise, mais pas la durabilité de la destination, son modèle d’autorisation, sa conservation, son état de publication ou l’URL finale de téléchargement ; ces contrats relèvent du service récepteur et de votre application.
Questions fréquentes
Le navigateur téléverse-t-il directement vers mon point de terminaison tus ?
Non. Dans ces exemples, le navigateur téléverse vers une Assembly Transloadit. Après le traitement, /tus/store agit comme un client tus et téléverse le résultat sélectionné vers le point de terminaison que vous avez configuré. Les deux transferts ont des URL, des informations d’identification, une progression et des périmètres de nouvelle tentative distincts.
La réussite d’un téléversement tus garantit-elle un stockage durable ?
Non. Le protocole tus standardise le transfert avec reprise. Le serveur récepteur décide si le téléversement terminé est stocké durablement, combien de temps il est conservé, qui peut y accéder et si l’URL de téléversement est aussi une URL de téléchargement. Réconciliez un enregistrement de ressource côté récepteur plutôt que de déduire ces propriétés de l’achèvement du protocole.
Comment la destination doit-elle authentifier Transloadit ?
Utilisez le type d’informations d’identification HTTP pour les en-têtes d’autorisation statiques et référencez le nom de l’ensemble d’informations d’identification dans /tus/store. Les valeurs dynamiques de headers sont prises en charge lorsque des informations d’identification statiques ne peuvent pas être utilisées, mais ne placez jamais d’en-têtes sensibles dans des Assembly Instructions visibles par le navigateur.
Un même Template peut-il traiter des fichiers, des images et des vidéos ?
Utilisez des Templates distincts lorsque les politiques de validation et de gestion des échecs diffèrent. Un Template délibérément mixte peut filtrer et créer des branches selon le type de média observé, puis fournir à chaque Step utilisant /tus/store uniquement le résultat créé par sa branche.
Quelle URL apparaît dans le résultat de l’Assembly ?
Par défaut, le Robot utilise l’URL de téléversement renvoyée par le serveur tus. url_template et ssl_url_template peuvent modifier la forme des URL renvoyées, mais ne prouvent pas que l’URL est accessible publiquement en lecture ou reste stable. Vérifiez indépendamment le contrat d’URL du récepteur.