Lorsque des utilisateurs téléversent des fichiers depuis leur appareil, toute interruption du réseau ou tout problème de serveur peut faire échouer le téléversement, ce qui oblige généralement à retransmettre l’intégralité du fichier. Les téléversements avec reprise peuvent se rétablir de manière transparente après ces interruptions et offrir une expérience utilisateur plus robuste, plus efficace et plus agréable.

Transloadit propose deux approches pour téléverser des fichiers sur nos serveurs :

Les fichiers peuvent être inclus dans la requête POST multipart/form-data lors de la création d’une Assembly. Toute interruption de cette requête fera échouer les téléversements et l’Assembly.
Les fichiers peuvent être téléversés à l’aide du protocole de téléversement avec reprise tus. Les téléversements peuvent se rétablir après des problèmes de réseau ou de serveur, tout en permettant à l’utilisateur de mettre en pause et de reprendre les téléversements comme il le souhaite. tus est un protocole ouvert et gratuit pour les téléversements de fichiers avec reprise via HTTP, avec de nombreuses implémentations clientes open source que vous pouvez utiliser.

Ce document décrit l’API qui sous-tend la seconde approche, avec reprise. Elle se compose de deux phases, décrites dans ce document.

Pour un exemple téléversement → traitement → stockage privé et une procédure de test d’interruption contrôlée, consultez le flux de travail pour les vidéos volumineuses dans le guide de téléversement de fichiers (English). La reprise du transfert ne garantit pas la réussite du traitement ou de l’export. Conservez l’identifiant d’Assembly, vérifiez l’Assembly Status final et contrôlez les résultats stockés avant de publier une ressource. Les paramètres de nouvelle tentative du client et la récupération après un rechargement sont distincts du protocole tus lui-même.

Pour un exemple de client Java, suivez le DevTip sur les transferts de fichiers avec reprise à l’aide de tus-java-client. Les tutoriels sur le téléversement de fichiers (English) couvrent également les formulaires HTML et les interfaces de navigateur personnalisées.

Note

De nombreuses intégrations prêtes à l’emploi, comme le SDK Node ou Uppy, utilisent tus par défaut en arrière-plan pour téléverser les fichiers. Si vous utilisez l’une d’entre elles, vous n’avez pas besoin d’implémenter vous-même les téléversements avec reprise. Cette documentation s’adresse aux personnes qui souhaitent développer des SDK, utiliser des SDK sans intégration tus, ou n’utiliser aucun SDK fourni par Transloadit.

Phase 1 : créer une nouvelle Assembly

Une nouvelle Assembly est créée en envoyant une requête POST multipart/form-data au point de terminaison de création d’Assemblies. Avec les téléversements traditionnels, tous les fichiers seraient inclus comme parties supplémentaires dans cette requête. Pour les téléversements avec reprise, le client n’inclut pas les fichiers dans cette requête, mais indique seulement à l’API Transloadit combien de fichiers doivent être téléversés.

Pour cela, on ajoute le champ num_expected_upload_files à la requête POST multipart. Sa valeur correspond au nombre de fichiers que le client souhaite téléverser pour cette Assembly. Les champs supplémentaires permettant de contrôler les Assembly Instructions, comme params, doivent également être inclus.

L’extrait suivant contient un exemple de requête HTTP. Le client fournit les informations d’authentification et les Assembly Instructions dans le champ params. Le champ num_expected_upload_files indique que le client souhaite téléverser deux fichiers. Cependant, le contenu réel de ces fichiers n’est pas inclus dans cette requête.

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIAWBI8vxocZzsG03

------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="params"

{"auth":{"key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},"steps":{"encode":{"robot":"/image/resize"}}}
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="num_expected_upload_files"

2
------WebKitFormBoundaryIAWBI8vxocZzsG03--

En supposant que la création de l’Assembly réussisse, l’API répond avec la réponse Assembly Status correspondante, qui ressemble à cet extrait d’exemple :

{
    "ok": "ASSEMBLY_UPLOADING",
    "assembly_id": "b841ea401e1a11e7b37d7bda1b503cdd",
    "assembly_ssl_url": "https://api2-freja.transloadit.com/assemblies/b841ea401e1a11e7b37d7bda1b503cdd",
    "websocket_url": "https://api2-freja.transloadit.com/ws20277",
    "tus_url": "https://api2-freja.transloadit.com/resumable/files/",
    "expected_tus_uploads": 2,
    "started_tus_uploads": 0,
    "finished_tus_uploads": 0,
    // …
}

On constate que l’Assembly est à l’état de téléversement et prête à recevoir des téléversements. La réponse inclut la propriété assembly_ssl_url, qui identifie de manière unique cette Assembly. Elle inclut également la propriété tus_url, qui définit le point de terminaison vers lequel les fichiers doivent être téléversés. Les propriétés expected_tus_uploads, started_tus_uploads et finished_tus_uploads indiquent combien de fichiers Transloadit attend pour cette Assembly et combien de téléversements ont été démarrés/terminés.

Phase 2 : téléverser chaque fichier

Une fois l’Assembly créée lors de la première phase, le client peut commencer à téléverser des fichiers vers le serveur de téléversement avec reprise de Transloadit.

Note

Transloadit prend en charge des tailles de fichier allant jusqu’à 200 GB. Si vous avez besoin d’une limite plus élevée pour votre application, veuillez nous contacter.

Transloadit exécute un serveur tus à l’aide du logiciel tusd. Son URL est fournie par la propriété tus_url dans l’Assembly Status, comme décrit lors de la première phase. Ce serveur de téléversement tus respecte la spécification du protocole et permet aux clients tus de téléverser des fichiers. Vous pouvez soit implémenter votre propre client tus en suivant la spécification, soit choisir l’une des implémentations clientes open source dans votre langage de programmation.

Un téléversement via tus se déroule en deux étapes :

Tout d’abord, une ressource de téléversement est créée sur le serveur tus. Le client envoie une requête POST et inclut l’URL d’Assembly, le nom du fichier et la métadonnée fieldname. Le serveur répond avec une URL de téléversement, vers laquelle le client peut téléverser le contenu réel du fichier.
À la réception de l’URL de téléversement, le client envoie une requête PATCH à ce point de terminaison avec le contenu du fichier pour effectuer le téléversement proprement dit. Une fois le fichier entièrement transmis, le serveur tus transmet le fichier de manière transparente à votre Assembly pour traitement, sans nécessiter d’interaction supplémentaire.

Vous trouverez plus de détails sur la sémantique exacte de cette interaction dans la spécification du protocole. Dans la section suivante, nous nous concentrerons sur les aspects pertinents pour l’intégration avec Transloadit.

Création du téléversement

La première étape consiste à créer une ressource de téléversement sur le serveur tus en envoyant une requête POST au point de terminaison indiqué par tus_url. Des métadonnées spéciales doivent être incluses pour associer le téléversement à l’Assembly créée précédemment. Au total, trois valeurs doivent être présentes dans les métadonnées :

assembly_url : l’URL d’Assembly obtenue à partir de la propriété assembly_ssl_url dans l’Assembly Status lors de la première phase
filename : le nom du fichier
fieldname : l’équivalent des noms de champs de saisie dans les formulaires HTML

Toute métadonnée supplémentaire deviendra une variable d’Assembly (English) dans file.user_meta. Vous pouvez l’utiliser pour effectuer des actions dynamiques dans votre Template par fichier, comme alternative à fields, qui est partagé par tous les fichiers d’une Assembly. Si vous devez effectuer un branchement selon le contenu détecté, privilégiez ${file.mime} et faites correspondre des familles MIME comme image/*, video/* ou audio/*. ${file.type} est également disponible en tant que catégorie de fichier générale dans la réponse Assembly Status. Sa valeur est l’une des suivantes : "audio", "document", "image", "office", "pdf", "swf", "video", "xls", ou null lorsqu’aucune catégorie n’a été détectée. Les consommateurs devraient accepter d’autres valeurs de chaîne afin que les futures catégories restent compatibles. La correspondance MIME constitue généralement la vérification la plus précise.

Dans l’exemple de requête ci-dessous, nous téléversons un fichier nommé isaac.png, d’une taille de 10 000 octets, vers l’Assembly dont l’identifiant est b841ea401e1a11e7b37d7bda1b503cdd, avec le nom de champ file-input. Les détails exacts de l’encodage des métadonnées en Base64 sont décrits dans la spécification du protocole.

POST /resumable/files/ HTTP/1.1
Content-Length: 0
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Length: 10000
Upload-Metadata: assembly_url aHR0cHM6Ly9hcGkyLWZyZWphLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzL2I4NDFlYTQwMWUxYTExZTdiMzdkN2JkYTFiNTAzY2Rk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==

Pour une requête correcte, le serveur crée une ressource de téléversement et renvoie son URL de téléversement dans l’en-tête Location. Par exemple :

HTTP/1.1 201 Created
Tus-Resumable: 1.0.0
Location: https://api2-freja.transloadit.com/resumable/files/136058f2ef4dc9de3f5c23ceed591545

Transfert des données

Après la création du téléversement, le client doit téléverser le contenu réel du fichier vers l’URL de téléversement tus, à l’aide d’une requête PATCH :

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Length: 10000
Content-Type: application/offset+octet-stream

[content of file]

Lorsqu’un téléversement tus est terminé, Transloadit le traite automatiquement à l’aide des paramètres que vous avez utilisés pour créer l’Assembly, sans que vous ayez à faire quoi que ce soit de particulier. Tant que tous les téléversements tus ne sont pas terminés, l’Assembly reste à l’état ASSEMBLY_UPLOADING, même si certains fichiers ont déjà été traités.

Ces étapes sont répétées pour chaque fichier que le client souhaite téléverser. Le client peut librement choisir de téléverser ces fichiers en parallèle ou de manière séquentielle, selon les besoins de l’application.

Le nombre de téléversements attendus indique à l’Assembly combien de fichiers doivent terminer leur téléversement ; il ne s’agit pas d’une limite stricte du nombre de ressources de téléversement tus pouvant être créées. Des ressources supplémentaires sont tolérées tant que l’Assembly est en cours de téléversement, afin qu’un client puisse se rétablir lorsqu’une réponse de création de téléversement a été perdue. Les compteurs de progression utilisent le nombre attendu de téléversements présentant la plus grande progression, en excluant les ressources abandonnées. Téléversez uniquement les fichiers prévus et réutilisez chaque URL de téléversement connue lors de la reprise. Dès que l’Assembly quitte l’état ASSEMBLY_UPLOADING, toute nouvelle création de téléversement est rejetée.

Reprise

Si le transfert des données échoue parce que le réseau a été interrompu ou que l’utilisateur a mis le téléversement en pause, le client peut reprendre le téléversement à partir du point où il s’est arrêté.

Tout d’abord, le client envoie une requête HEAD à l’URL de téléversement pour déterminer la quantité de données que le serveur a pu recevoir avant l’interruption :

HEAD /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

La réponse inclut le nombre d’octets reçus dans l’en-tête Upload-Offset. Par exemple, la réponse suivante montre un téléversement pour lequel 3 000 sur 10 000 octets ont été reçus :

HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000

Les 7 000 octets restants peuvent ensuite être téléversés à l’aide d’une autre requête PATCH :

PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

[remaining content of file]

Des informations supplémentaires sur les téléversements avec reprise via tus sont disponibles dans la FAQ de tus.

Téléversements avec reprise

Phase 1 : créer une nouvelle Assembly

Phase 2 : téléverser chaque fichier

Création du téléversement

Transfert des données

Reprise