Guide des API de téléversement de fichiers : architecture, sécurité et choix du fournisseur

Définir la tâche de téléversement avant de choisir un widget

Un téléversement en production commence avant le transfert du premier octet. L’application identifie l’utilisateur, décide quelle opération est autorisée, précise le nombre et la taille des fichiers acceptables et crée un enregistrement qui peut persister après la fermeture d’un onglet du navigateur. Le transfert n’est qu’une étape. La validation, le traitement, l’export, la notification et la réconciliation des états déterminent si le produit peut ensuite utiliser le fichier en toute sécurité.

Rédigez un contrat d’achèvement en termes fonctionnels. « La requête a renvoyé 200 » est un critère insuffisant ; « l’original et les dérivés requis sont stockés pour ce tenant, l’enregistrement de la ressource indique leurs versions et un callback répété ne change rien » est vérifiable par des tests. Consignez les défaillances après lesquelles les utilisateurs peuvent réessayer, celles qui nécessitent un nouveau téléversement et celles qui laissent un état visible par un opérateur pour permettre la récupération.

Choisir l’un des quatre circuits explicites pour les octets

Avec un relais applicatif, le navigateur envoie le fichier à votre serveur, qui le transmet ou le stocke. Cette approche est facile à comprendre et donne à l’application un contrôle immédiat, mais chaque octet consomme de la bande passante entrante, de la mémoire ou de l’espace disque temporaire, du temps de connexion et de la bande passante sortante. Elle convient aux petits fichiers peu fréquents lorsque le serveur existant peut faire respecter les limites et transférer les données en flux de manière sûre, sans mettre en mémoire tampon l’intégralité des corps de requête.

« Directement vers le cloud » est ambigu : nommez donc la destination. Un navigateur peut téléverser directement vers un stockage objet avec des informations d’identification de courte durée, téléverser directement vers un service de traitement tel que Transloadit, ou demander à un service d’importer le contenu d’une URL distante existante. Le stockage direct minimise les intermédiaires lorsque la persistance est la seule tâche à accomplir. Le traitement direct maintient l’application hors du circuit des données, tandis qu’un flux de travail valide, transforme et exporte les fichiers vers un stockage dont vous êtes propriétaire.

Concevoir la reprise des transferts séparément des nouvelles tentatives

Une nouvelle tentative recommence une opération ; un transfert avec reprise poursuit un téléversement existant à partir d’une position en octets confirmée par le serveur. Avec tus, le client conserve l’URL de téléversement, demande Upload-Offset au serveur et n’envoie que les octets restants. Conservez cette URL de manière persistante en dehors de l’état transitoire du composant si la reprise doit être possible après une actualisation ou un plantage, et calculez soigneusement les empreintes des fichiers afin que le fichier local d’un utilisateur ne soit jamais associé à une autre ressource de téléversement.

La reprise des transferts ne rend ni le délai illimité ni le traitement idempotent. Une Assembly Transloadit dispose toujours de huit heures à compter de sa création pour terminer le téléversement, et la création d’une Assembly de remplacement peut entraîner une répétition du traitement si l’application ne réconcilie pas l’état associé à l’ancien identifiant. Définissez comment le client gère les pauses, les périodes hors ligne, les ressources expirées, les fichiers modifiés, les téléversements abandonnés et la perte d’une réponse d’achèvement après l’acceptation des derniers octets par le serveur.

Autoriser l’opération prévue côté serveur et se méfier des octets

Le code du navigateur peut contenir une Auth Key publique, mais il ne doit jamais contenir l’Auth Secret Transloadit ni des informations d’identification permanentes pour le stockage. Authentifiez l’utilisateur dans votre application, sélectionnez un Template enregistré côté serveur et renvoyez des paramètres signés de courte durée avec une valeur unique pour nonce. Définissez allow_steps_override sur false lorsque le navigateur n’a aucune raison légitime de remplacer des Steps, car un graphe de Steps choisi par le client pourrait sinon modifier le comportement du traitement ou de l’export.

Une signature valide prouve que la charge utile des paramètres a été autorisée ; elle ne prouve pas que les octets téléversés correspondent à un nom de fichier, à une extension, à un type MIME déclaré, à un tenant ou à une politique de modération. Limitez les corps de requête avant les opérations coûteuses, inspectez les propriétés observées des fichiers, rejetez les contenus non pris en charge, effectuez une analyse de sécurité lorsque le modèle de menace l’exige et maintenez les résultats non fiables hors du stockage public jusqu’à ce que le flux de travail atteigne un état approuvé.

Séparer le stockage durable du traitement des téléversements

Un point de terminaison de téléversement n’est pas automatiquement un système de référence. Déterminez quel bucket ou quelle base de données de ressources fait autorité pour l’original, comment les fichiers dérivés lui sont rattachés, quels identifiants subsistent après un renommage et qui supprime chaque copie. Transloadit conserve les résultats temporaires pendant au moins 24 heures, tandis que leurs URL d’accès peuvent expirer après quelques heures. Exportez les fichiers qui doivent être conservés durablement. Les URL temporaires sont réservées à la récupération à court terme, pas à l’intégration de ressources ni à leur diffusion répétée dans le produit.

Intégrez l’export à l’Assembly lorsque la réussite du flux de travail exige à la fois le traitement et la conservation durable. Un Robot d’export peut utiliser des ensembles d’informations d’identification de Template enregistrés pour écrire les résultats vers la destination choisie dans le cadre du flux de travail. Vous pouvez aussi, en premier lieu, téléverser directement vers un stockage que vous contrôlez, puis déclencher le traitement à partir d’un événement contrôlé. Cette approche permet d’obtenir rapidement une copie durable, mais ajoute de l’orchestration et un transfert supplémentaire vers le système de traitement.

Choisir entre développement et achat selon le périmètre de responsabilité

Développez le circuit de transfert lorsque les besoins sont limités et que l’équipe est prête à prendre en charge l’ensemble du cycle de vie. Un petit formulaire authentifié qui transfère de petits fichiers en continu vers un seul bucket existant ne justifie pas forcément une plateforme supplémentaire. L’estimation doit néanmoins inclure l’analyse multipart, la contre-pression, l’application des limites de taille, la possibilité de reprise ou son absence délibérée, le nettoyage, les mesures contre les abus, l’observabilité, les mises à niveau et la prise en charge des défaillances qui surviennent en dehors de la durée de vie de la requête.

Un service géré devient plus intéressant lorsque le flux de travail combine des réseaux peu fiables, des fichiers volumineux, une expérience utilisateur dans le navigateur, des sources distantes, l’inspection de médias, des transformations ou plusieurs destinations de stockage. L’achat ne vous décharge pas de la responsabilité de l’application : les vérifications des tenants, l’autorisation, les enregistrements des ressources, la conservation, la publication et la gestion des incidents restent à votre charge. Une architecture hybride est souvent la plus adaptée, avec un stockage et un état métier sous votre contrôle autour d’une couche gérée de transfert et de traitement.

Comparer les fournisseurs à l’aide de tests de défaillance plutôt qu’en comptant les fonctionnalités

Créez une grille d’évaluation à partir de la charge de travail réelle du produit. Comparez les clients web et mobiles, la prise en charge des protocoles ouverts, la taille maximale des fichiers, le comportement en cas d’opérations simultanées, la répartition géographique des points de terminaison, les imports distants, l’étendue des traitements, les destinations de stockage, l’isolation des informations d’identification, la vérification des webhooks, la conservation des états, l’assistance et les possibilités de sortie. Classez chaque fonctionnalité comme obligatoire, facultative ou sans pertinence avant de consulter les pages des fournisseurs.

Soumettez les mêmes données de test à chaque candidat sérieux. Interrompez un téléversement volumineux, rechargez la page, envoyez un événement de fin dupliqué, révoquez les informations d’identification pour le stockage, refusez un fichier après réception, dépassez une limite et simulez la perte de la réponse finale. Mesurez la reprise telle que la perçoit l’utilisateur, les octets retransmis, le délai d’obtention d’une sortie durable, les éléments de diagnostic disponibles pour l’opérateur et le nettoyage. Un sélecteur de fichiers soigné renseigne peu sur ces caractéristiques en production.

Mettre en œuvre un téléversement signé avec Uppy et Transloadit

L’exemple côté navigateur laisse Uppy gérer la sélection et le transfert tus, tandis que le plugin Transloadit demande les paramètres d’Assembly à votre application. Le point de terminaison du serveur doit authentifier l’utilisateur actuel avant de renvoyer l’objet provenant de calcSignature. Il devrait choisir lui-même le Template au lieu d’accepter des Steps arbitraires ou une destination de stockage fournie par l’appelant, et limiter le débit des demandes d’autorisation indépendamment du trafic de téléversement.

Avant d’utiliser cet exemple, activez « Exiger une signature valide » dans les Paramètres du Workspace, enregistrez le Template ci-dessous et renseignez son ID dans TRANSLOADIT_UPLOAD_TEMPLATE_ID côté serveur. Enregistrez l’accès AWS à votre propre bucket privé sous forme d’un ensemble d’informations d’identification de Template nommé my_s3_credentials. L’Auth Key peut parvenir au navigateur ; l’Auth Secret et les informations d’identification AWS ne doivent pas y parvenir. Le point de terminaison de signature doit renvoyer Cache-Control: no-store afin que chaque opération autorisée reçoive de nouveaux paramètres.

Installez @uppy/core, @uppy/dashboard et @uppy/transloadit côté client, ainsi que le SDK @transloadit/node sur le serveur. Montez l’exemple côté navigateur lorsqu’un élément tel que <div id="photo-upload"></div> existe déjà. Implémentez /api/transloadit-params dans votre framework avec une authentification par session et une autorisation de téléversement avant d’appeler la fonction utilitaire de signature. Rejetez les requêtes non authentifiées ou non autorisées ; la fonction utilitaire elle-même n’est pas un point de terminaison d’authentification.

La politique de fichiers de l’exemple autorise une seule image JPEG, PNG ou WebP d’au plus 9 MiB. Le paramètre maxFileSize d’Uppy fournit un retour immédiat sur la taille du fichier en octets, et le filtre côté serveur du Template verrouillé impose cette limite de 9 MiB par fichier. Le paramètre signé auth.max_size fixe un budget global de requêtes de 10 MiB, comprenant les octets de la requête initiale d’Assembly et les téléversements avec possibilité de reprise ; auth.max_number_of_files limite l’Assembly à un seul fichier. Cela laisse, à titre d’exemple, une marge de 1 MiB pour les données supplémentaires des requêtes. Leur volume varie, de sorte qu’un rejet par le serveur reste la décision faisant autorité ; l’acceptation par le navigateur ne garantit pas la création de l’Assembly. waitForEncoding: true attend la fin de l’Assembly, export compris, au lieu de considérer la fin du transfert comme la fin du flux de travail.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

// Mount this once after <div id="photo-upload"></div> exists in your page.
const uppy = new Uppy({
  restrictions: {
    maxNumberOfFiles: 1,
    maxFileSize: 9 * 1024 * 1024,
    allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
  },
}).use(Dashboard, { inline: true, target: '#photo-upload' }).use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
      cache: 'no-store',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
  retryDelays: [0, 1000, 3000, 5000, 10000],
})

uppy.on('transloadit:assembly-created', (assembly) => {
  // Associate this ID with the server-side operation before the user leaves the page.
  console.log('Assembly started:', assembly.assembly_id)
})

uppy.on('transloadit:complete', (assembly) => {
  // Record completion against the ID persisted at transloadit:assembly-created.
  console.log('Processing completed. Assembly:', assembly.assembly_id)
})

uppy.on('transloadit:assembly-error', () => {
  // Show this through the application’s accessible status UI, not raw API errors or URLs.
  console.error('Processing failed. Check the Assembly in your workspace.')
})

uppy.on('upload-error', () => {
  // Transloadit API signature rejections and Assembly errors also reach this event.
  // Failures thrown by assemblyOptions() use Uppy’s general error event instead.
  // Deduplicate application notices.
  console.error('The upload workflow failed. Check its status before retrying.')
})

import { randomUUID } from 'node:crypto'
import { Transloadit } from '@transloadit/node'

function requiredEnvironmentValue(name: string): string {
  const value = process.env[name]
  if (value == null) throw new Error(`Missing environment variable: ${name}`)
  return value
}

const transloadit = new Transloadit({
  authKey: requiredEnvironmentValue('TRANSLOADIT_KEY'),
  authSecret: requiredEnvironmentValue('TRANSLOADIT_SECRET'),
})

export function createAuthorizedUploadParameters(): { params: string; signature: string } {
  // Call this only after the server has authenticated the request and authorized the operation.
  const params = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      max_size: 10 * 1024 * 1024,
      max_number_of_files: 1,
    },
    nonce: randomUUID(),
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  }
  return transloadit.calcSignature(params)
}

Relier la réception, la validation, le traitement et l’export

Une seule Assembly relie le parcours complet : téléversement authentifié avec Uppy → validation avec /file/filter → traitement avec /image/resize → export avec /s3/store vers un bucket appartenant au client. Son Template enregistré fournit le flux de travail, et chaque dépendance use détermine quels fichiers atteignent le Step suivant. Uppy fournit l’expérience de téléversement ; Transloadit exécute le flux de travail géré, et non votre serveur d’application.

Le filtre vérifie le type MIME détecté et rejette les fichiers de plus de 9 MiB, puis transmet uniquement les images acceptées aux Steps d’aperçu et d’export. error_on_decline: true transforme un rejet en erreur d’Assembly. Les vérifications du type MIME et de la taille ne constituent ni une analyse antimalware ni une modération de contenu ; ajoutez ces Steps avant le traitement et l’export lorsque votre politique l’exige.

Utilisez un bucket S3 privé avec Block Public Access activé et des ensembles d’informations d’identification de Template aux autorisations correctement délimitées. acl: "bucket-default" omet l’ACL de l’objet et s’appuie sur la politique d’accès du bucket ; ce réglage ne rend pas privé un bucket public. L’export stocke l’original accepté et un aperçu limité à 1600 × 1600 pixels dans des chemins propres à l’Assembly et au fichier. Aucun des deux exports ne lit directement les données non filtrées de :original.

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/(jpeg|png|webp)$"]
      ],
      "declines": [["${file.size}", ">", 9437184]],
      "error_on_decline": true
    },
    "preview": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600
    },
    "exported": {
      "use": ["accepted_images", "preview"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "acl": "bucket-default",
      "path": "uploads/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}

Tester une vidéo volumineuse du téléversement interrompu à l’export privé

Pour un flux de travail vidéo, créez un ensemble d’informations d’identification de Template nommé large-upload-output à l’aide d’informations d’identification IAM dont l’autorisation s3:PutObject est limitée au préfixe privé upload-tests/. Suivez la configuration IAM de /s3/store EN (English) pour les autorisations s3:ListBucket et s3:GetBucketLocation au niveau du bucket ; la recherche de l’emplacement est inutile lorsque l’ensemble d’informations d’identification de Template fournit bucket_region. Remplacez YOUR_AUTH_KEY par l’Auth Key du Workspace (et non son Auth Secret), enregistrez le Template ci-dessous et exigez Signature Authentication sur ce Template. Utilisez un bucket privé avec Block Public Access activé et Object Ownership défini sur Bucket owner enforced. Le réglage acl: "bucket-default" omet l’ACL de l’objet ; l’accès reste contrôlé par les politiques de votre bucket et vos politiques IAM. Pour le test, définissez TRANSLOADIT_UPLOAD_TEMPLATE_ID du point de terminaison de signature authentifié sur l’identifiant de ce Template vidéo enregistré. Réutilisez l’intégration Uppy ci-dessus avec un fichier sélectionné par l’utilisateur et une seule instance Uppy. Cette politique illustrative autorise une seule vidéo contenant jusqu’à 254 MiB de données de fichier, dans la limite globale de 256 MiB fixée par le Template pour l’ensemble des requêtes de l’Assembly. auth.max_size inclut les octets de la requête initiale de l’Assembly ainsi que tous les octets des téléversements avec reprise. Le filtre de confiance du Template rejette les fichiers de plus de 254 MiB, laissant une marge illustrative de 2 MiB pour les données supplémentaires de la requête. Pour ce test vidéo, remplacez la restriction aux seules images par allowedFileTypes: ["video/*"], définissez maxFileSize: 254 * 1024 * 1024 dans restrictions du cœur d’Uppy et définissez la valeur signée de auth.max_size sur 256 * 1024 * 1024 ; conservez les deux limites du nombre de fichiers à 1 (maxNumberOfFiles et auth.max_number_of_files). Le volume des données supplémentaires de la requête varie : le rejet côté serveur fait donc autorité ; l’acceptation par le navigateur ne garantit pas la création d’une Assembly. Vérifiez les limites de téléversement de votre Workspace et les formats source pris en charge avant le test. Le Template détecte une famille MIME vidéo, crée une variante MP4 aux dimensions limitées et exporte cette variante ainsi que l’original accepté. Il ne s’agit pas d’une politique complète de protection contre les logiciels malveillants ou les contenus dangereux.

La fin du transfert ne marque pas la fin de l’opération. Avec waitForEncoding: true, le navigateur attend le traitement, mais votre application a toujours besoin d’un identifiant d’Assembly conservé durablement et de notifications vérifiées ou d’une consultation de l’Assembly Status si l’onglet disparaît. Un échec d’export ne doit pas entraîner le marquage du fichier comme prêt. Confirmez ASSEMBLY_COMPLETED, la variante requise et les deux objets S3 privés ; comparez la somme de contrôle de l’original exporté à celle du fichier d’entrée avant d’enregistrer la réussite. Ces objets privés ne constituent pas automatiquement des URL de lecture publiques.

Effectuez trois essais témoins en ligne et trois essais avec interruption en utilisant la même vidéo de 100–200 MiB dont vous êtes propriétaire. Consignez la taille exacte du fichier en octets et son empreinte SHA-256, sa durée et ses codecs, les versions du navigateur et des paquets, le Template, la région, la formule et la configuration réseau. Dans Chrome DevTools, appliquez un profil personnalisé de limitation du débit et consignez ses paramètres, passez sur Offline lorsque le téléversement approche de 25 %, pour une durée de 10 secondes, puis rétablissez le profil sans recharger la page. Pour les défaillances réseau signalées lorsque le navigateur est hors ligne et qu’il reste des tentatives, le plugin tus d’Uppy installé suspend sa file d’attente jusqu’à un événement online. Chaque nouvelle tentative est tout de même décomptée ; la progression du téléversement peut réinitialiser le compteur. La somme de retryDelays n’est pas une durée limite hors ligne. Vérifiez qu’une requête HEAD indique la valeur Upload-Offset enregistrée et que les requêtes PATCH suivantes poursuivent le transfert sur la même ressource tus. Ce test simule une interruption dans le navigateur, et non un basculement du serveur ou toutes les conditions réseau.

Mesurez le temps écoulé entre le début du téléversement et la première Assembly terminée dont les objets exportés ont été vérifiés, et pas seulement jusqu’au dernier octet téléversé. Consignez aussi le temps entre la reconnexion et la fin du traitement, les octets retransmis lorsque cette mesure est observable, les échecs, les Assemblies dupliquées et le nombre brut d’exécutions. Il s’agit d’une procédure de test reproductible, pas d’un résultat de benchmark publié. Des échecs de requêtes répétés peuvent épuiser le nombre limité de nouvelles tentatives, le délai de huit heures pour le téléversement d’une Assembly EN (English) reste applicable, et cet exemple en mémoire ne restaure pas l’état après un rechargement ou la fermeture de l’onglet. Testez séparément l’annulation, l’expiration de l’autorisation, les fichiers dépassant les limites et les informations d’identification révoquées pour l’exportation. Consultez l’API de téléversement avec reprise pour le passage de relais au protocole et la démo vidéo et S3 EN (English) pour un exemple de traitement et d’exportation publique.

{
  "allow_steps_override": false,
  "auth": {
    "key": "YOUR_AUTH_KEY",
    "max_size": 268435456,
    "max_number_of_files": 1
  },
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_video": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^video/"]],
      "declines": [["${file.size}", ">", 266338304]],
      "error_on_decline": true
    },
    "rendition": {
      "use": "accepted_video",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/360p",
      "width": 640,
      "height": 360,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_video", "rendition"],
      "robot": "/s3/store",
      "credentials": "large-upload-output",
      "acl": "bucket-default",
      "path": "upload-tests/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}