Téléversement de fichiers, optimisation d’images, encodage vidéo et votre propre bucket S3

Séparer les traitements lors du téléversement des traitements lors de la requête

Commencez par deux parcours plutôt que par un vague « pipeline d’optimisation ». Dans le parcours de téléversement, un navigateur envoie un fichier via Uppy et tus à une Assembly Transloadit. Le Template enregistré valide le fichier observé, crée toutes les sorties qui doivent exister immédiatement et exporte les fichiers sélectionnés vers S3. L’application stocke l’identifiant d’Assembly et l’identité de l’objet S3 durable dans l’enregistrement de la ressource.

Dans le parcours de requête, un navigateur demande une URL du Smart CDN. L’URL identifie un Template enregistré et un chemin d’entrée dans S3. En l’absence de résultat en cache, Transloadit importe cet objet, applique le Template avec les Assembly Variables autorisées et sert un résultat via /file/serve. La couche de diffusion met la réponse en cache ; une requête sur un cache chaud peut réutiliser le dérivé sans relancer la transformation.

Stocker un fichier téléversé dans S3 sans le transformer

Utilisez un Template de téléversement seul lorsque Transloadit doit recevoir et exporter le fichier accepté sans modifier les octets de son contenu multimédia. /upload/handle reçoit l’entrée et /s3/store sélectionne :original. Le chemin de destination utilise les Assembly Variables afin que les téléversements simultanés ne s’écrasent pas mutuellement, tout en conservant un nom de fichier d’origine reconnaissable et compatible avec les URL.

Les exemples nécessitent un bucket S3 privé avec Block Public Access activé et Object Ownership défini sur Bucket owner enforced (ACL désactivées). Utilisez des ensembles d’informations d’identification de Template pour une identité AWS dédiée dont l’accès est limité au bucket de destination et aux préfixes nécessaires, en suivant le guide de configuration S3. Chaque export définit explicitement acl: "bucket-default" pour remplacer la valeur par défaut public-read de /s3/store et omettre l’en-tête ACL généré. Ne fournissez pas d’en-têtes ACL ou d’octroi d’autorisations ; acl: "private" envoie toujours une ACL et est incompatible avec cette configuration de bucket. L’accès reste contrôlé par les politiques du bucket et d’IAM : omettre l’en-tête ACL ne rend donc pas privé un bucket public. Définissez bucket_region sur la région AWS réelle du bucket pour éviter une recherche GetBucketLocation et retirer s3:GetBucketLocation de la politique IAM associée aux informations d’identification. Vérifiez l’accès S3 effectif indépendamment du paramètre du Robot.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "stored": {
      "use": ":original",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "bucket-default",
      "path": "uploads/${unique_prefix}/${file.url_name}"
    }
  }
}

Recevoir, valider, optimiser et exporter le fichier téléversé

Utilisez un Template d’image enregistré pour limiter ce que le code du navigateur peut demander. /upload/handle reçoit le fichier, /file/filter peut rejeter les fichiers dont les propriétés détectées ne respectent pas la politique, /image/resize crée un dérivé WebP fixe et /image/optimize réduit la taille de ce résultat. /s3/store exporte ensuite exactement les Steps désignés par sa valeur use. Configurez-le pour cibler uniquement optimized afin de stocker le dérivé, uniquement accepted_images afin de stocker l’original accepté, ou les deux afin de conserver les deux objets. preserve_meta_data est volontairement laissé à sa valeur par défaut true pour conserver les métadonnées de l’image, telles que les informations sur les droits d’auteur du photographe, au prix d’une légère augmentation de taille, même avec la priorité compression-ratio. Conserver les métadonnées peut aussi préserver des données sensibles de localisation GPS ; supprimez-les lorsque cela entre en conflit avec la politique de confidentialité prévue.

Uppy est la couche de téléversement dans le navigateur, pas la frontière d’autorisation. Laissez le plugin Transloadit demander au serveur applicatif des paramètres d’Assembly signés à courte durée de validité. Gardez allow_steps_override désactivé lorsque le navigateur ne doit pas remplacer les Steps enregistrés ni sélectionner une autre destination. Réutilisez la configuration du bucket privé, acl: "bucket-default" et la région AWS réelle du bucket définies dans l’exemple de téléversement seul. ${file.id} et ${unique_prefix} sont uniques pour chaque fichier exporté ; cet exemple d’image utilise ${file.id}, qui ne contient aucune barre oblique, afin que le segment central du chemin reste un seul composant. Il fournit ainsi des clés images/${file.id}/${file.url_name} prévisibles que le Smart CDN peut référencer, tandis que les exemples de téléversement et de vidéo utilisent ${unique_prefix} comme répertoire pour éviter les collisions. Comme ${file.id} est unique pour chaque fichier exporté, accepted_images et optimized correspondent à des clés différentes sous images/ ; le modèle de chemin partagé n’entraîne aucun écrasement. Enregistrez donc chaque clé exportée séparément dans l’état de l’application. Ne considérez le téléversement comme terminé pour le produit qu’après la réconciliation, par l’application, du résultat de l’Assembly et des clés S3 durables.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/jpeg|image/png|image/gif|image/webp|image/avif)$"]],
      "error_on_decline": true
    },
    "resized": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600,
      "format": "webp"
    },
    "optimized": {
      "use": "resized",
      "robot": "/image/optimize",
      "priority": "compression-ratio",
      "preserve_meta_data": true
    },
    "stored": {
      "use": ["accepted_images", "optimized"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "bucket-default",
      "path": "images/${file.id}/${file.url_name}"
    }
  }
}

Encoder une vidéo avant de la stocker dans S3

Utilisez un Template réservé aux vidéos lorsque l’objet S3 durable doit être une variante de lecture plutôt que la source téléversée. /video/encode lit :original et applique un préréglage testé. web/mp4/720p est un point de départ concret pour du MP4 1280×720, pas une recommandation universelle ; validez les dimensions de la source, la fréquence d’images, l’audio, les sous-titres, la qualité, la prise en charge par les appareils, le temps de traitement et le coût au regard des exigences de lecture du produit.

L’exemple exporte le Step encoded et exclut la source de cette opération de stockage. Ajoutez un second Step /s3/store lorsque la source doit rester disponible pour un réencodage de meilleure qualité, un audit ou une migration. L’encodage peut se poursuivre au-delà de la durée d’une requête applicative ; réconciliez donc l’Assembly Status ou un callback de fin vérifié avant de considérer la clé S3 comme publiable.

{
  "allow_steps_override": false,
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/720p"
    },
    "stored": {
      "use": "encoded",
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "bucket_region": "us-east-1",
      "acl": "bucket-default",
      "path": "videos/${unique_prefix}/${file.url_name}"
    }
  }
}

Transformer un original S3 à la demande via le Smart CDN

Une intégration du Smart CDN commence elle aussi par un Template enregistré. /s3/import résout le chemin d’entrée à l’aide d’ensembles d’informations d’identification de Template à portée limitée, /image/resize lit la valeur ${fields.w} fournie par l’URL et la valeur ${browser.wanted_image_format} négociée pour la requête, et /file/serve sélectionne la réponse. Un nœud périphérique du Smart CDN peut fournir un en-tête x-tl-image-format fiable et prénormalisé au lieu d’analyser à nouveau l’en-tête Accept du client. Référencez ${browser.wanted_image_format} dans les Instructions pour obtenir la valeur négociée avif, webp ou jpg.

Une URL telle que https://my-workspace.tlcdn.com/responsive-image/images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg?w=640 fournit images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg comme valeur implicite de ${fields.input} — le chemin après le nom du Template, sans barre oblique initiale — et 640 comme valeur de ${fields.w}. Cette entrée est la clé images/${file.id}/${file.url_name} enregistrée pour l’original durable accepted_images, que /s3/import lit pour le redimensionnement à la demande. Le dérivé optimisé est un objet distinct sous son propre préfixe ${file.id}. Comme les deux résultats ne partagent pas de répertoire, enregistrez chaque clé exportée dans l’état de l’application au lieu de déduire une clé à partir de l’autre ou de l’URL de la requête.

Conservez le préfixe images/ complet dans l’URL du Smart CDN ; ne l’ajoutez pas à nouveau dans le Template. Les valeurs des paramètres de requête du Smart CDN arrivent sous forme de chaînes de caractères ; la liste des largeurs autorisées les compare donc aux chaînes littérales "320" et "640". Une largeur sans correspondance prend la valeur de repli 1280. Séparer la correspondance des chemins de la liste des transformations autorisées facilite l’audit de l’objet S3 qui peut être lu et de la variante qui peut être demandée.

N’interpolez pas de chemin, de largeur, de qualité ou de format sans restriction au seul motif que ces valeurs peuvent être transmises dans un champ. Activez « Exiger une signature valide » sur ce Template enregistré du Smart CDN avant d’exposer son URL. Limitez l’ensemble d’informations d’identification S3 au préfixe prévu, faites autoriser l’accès par l’application de confiance et faites-lui rechercher la clé exportée dans l’enregistrement du fichier, puis signez une URL contenant cette clé exacte. La validation obligatoire des signatures est nécessaire pour rejeter les requêtes non signées visant d’autres objets sous ce préfixe. Le flux de travail exécuté au moment de la requête sélectionne ce Template enregistré via son URL Smart CDN au lieu d’accepter des Assembly Instructions soumises par le navigateur. Cet exemple n’utilise donc pas le paramètre allow_steps_override employé lors du téléversement. Utilisez la région AWS réelle du bucket, comme dans l’exemple consacré uniquement au téléversement. Validez les valeurs de transformation ou définissez leur correspondance dans le Template. Les consultations simples telles que ${fields.input} sont gratuites, tandis que les comparaisons, les opérations arithmétiques et les expressions ternaires relèvent de l’évaluation dynamique complexe : les expressions ternaires de largeur et de format de cet exemple invoquent /script/run et sont facturées chaque fois que le résultat est absent du cache. L’expression de format fait correspondre la valeur de repli jpg à null. Ainsi, les requêtes sans préférence pour un format moderne conservent le format d’origine au lieu de supprimer la transparence ou l’animation par un réencodage inutile. Consultez l’entrée ${browser.wanted_image_format} dans la référence des Assembly Variables. Mesurez séparément la première transformation sans cache et la diffusion ultérieure depuis le cache.

Créez un ensemble distinct d’informations d’identification de Template nommé my_s3_image_read_credentials pour une identité AWS dédiée disposant d’un accès en lecture seule aux objets, limité au préfixe images/ du bucket. Conservez my_s3_credentials pour les exports lors du téléversement. Les consignes relatives aux autorisations de /s3/import EN (English) exigent également s3:ListBucket sur le bucket lui-même. Définissez bucket_region sur la région AWS réelle du bucket ; cela évite la recherche de localisation et vous permet d’omettre s3:GetBucketLocation.

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "my_s3_image_read_credentials",
      "bucket_region": "us-east-1",
      "path": "${fields.input}"
    },
    "resized": {
      "use": "imported",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": "${fields.w === '320' ? 320 : fields.w === '640' ? 640 : 1280}",
      "format": "${browser.wanted_image_format === 'jpg' ? null : browser.wanted_image_format}"
    },
    "served": {
      "use": "resized",
      "robot": "/file/serve",
      "cache_duration": 604800
    }
  }
}

Décider quoi stocker durablement et quoi générer à la demande

Conserver un original dans S3 fournit une source stable pour les traitements ultérieurs, sans imposer de stocker chaque rendu adapté aux différentes tailles d’écran. Exportez les sorties de référence dont le produit a besoin indépendamment d’un cache : un master approuvé, une image de fiche produit sur une place de marché, un fichier destiné à l’impression ou un dérivé immuable d’une version publiée. Laissez le Smart CDN créer des variantes de présentation aux limites définies, dont les dimensions dépendent de l’appareil à l’origine de la requête ou de la mise en page.

À l’inverse, ne vous reposez pas uniquement sur un traitement à la demande lorsque la première requête ne peut pas tolérer la latence du traitement, qu’un responsable éditorial doit approuver les pixels exacts ou que les systèmes en aval exigent un objet durable avant publication. Dans ce cas, créez et exportez le dérivé dans l’Assembly exécutée lors du téléversement. Une même application peut utiliser les deux approches pour différentes catégories de sorties sans changer le système qui reste propriétaire de la source.

Protéger l’application, le bucket et les possibilités de transformation exposées

Créez des ensembles distincts d’informations d’identification de Template selon le principe du moindre privilège lorsque les exports lors du téléversement et les imports du Smart CDN nécessitent des actions AWS ou des préfixes différents. Gardez les clés AWS brutes, l’Auth Secret de Transloadit et les Instructions sans restriction hors des bundles destinés au navigateur. Le serveur de l’application devrait autoriser l’utilisateur, sélectionner le Template et ne délivrer que les paramètres de téléversement à courte durée de validité ou l’URL signée du Smart CDN adaptés au fichier concerné.

Un téléversement réussi ou une signature valide ne vaut pas approbation de publication. Validez le type MIME détecté et la taille dans l’Assembly, associez les callbacks de manière idempotente au tenant et à l’Assembly attendus, et n’exposez un résultat qu’à partir du moment où l’objet durable et l’enregistrement de l’application concordent. Pour le Smart CDN, concevez conjointement la gestion des versions des sources, l’expiration des URL, la durée de vie du cache et la suppression, afin que le remplacement d’une clé S3 ne puisse pas laisser active une adresse de dérivé non souhaitée.

Comparer avec un pipeline AWS natif

Une architecture native peut téléverser via une URL présignée S3, réagir aux événements de création d’objets, traiter les fichiers avec Lambda ou un autre service de calcul, stocker les dérivés et les diffuser via un CDN. Elle peut être bien adaptée lorsque la charge de travail reste dans les limites prises en charge par l’environnement d’exécution et que l’équipe souhaite gérer elle-même les autorisations, les nouvelles tentatives, les files d’attente, les codecs, la concurrence, l’observabilité et la reprise après incident.

Comparez des chaînes complètes en production plutôt qu’un seul redimensionnement réussi. Testez les téléversements interrompus, les sources volumineuses, les images mal formées, l’orientation et la couleur, les événements dupliqués, les exports partiels, les pics de concurrence, les transformations à froid, l’invalidation du cache, la latence régionale et la suppression. Incluez le temps de développement et d’exploitation en plus des frais de téléversement, de traitement, de stockage, de requêtes et de transfert sortant. Le choix déterminant porte sur les responsabilités opérationnelles que l’équipe souhaite assumer.