Points clés à retenir
- Choisissez le modèle de stockage avant le fournisseur : le stockage objet, le stockage de fichiers collaboratif et les serveurs de transfert de fichiers répondent à des problèmes opérationnels différents.
- Traitez l’importation et l’exportation comme des frontières de confiance distinctes, avec des informations d’identification de Template respectant le principe du moindre privilège, limitées aux chemins et aux actions nécessaires à chaque flux de travail.
- Ne déduisez pas un accès public d’une URL renvoyée ; la politique du bucket, les paramètres de partage, les URL signées et les permissions du serveur déterminent si un résultat peut être récupéré.
Choisir une intégration de stockage est une décision d’architecture, pas une recherche de nom de fournisseur. Les systèmes de stockage objet, les services de fichiers collaboratifs et les serveurs de transfert de fichiers présentent des modèles de permissions, des garanties d’URL, des comportements de listage et des modes de défaillance différents. Ce guide regroupe les destinations prises en charge selon ces différences pour vous permettre de choisir un flux de travail en connaissance de cause plutôt que de copier des exemples presque identiques.
L’essentiel
- Planifiez les importations de dossiers volumineux en fonction du contrat de récursivité et de pagination de chaque Robot plutôt que de supposer que tous les fournisseurs listent les arborescences de la même manière.
- Conservez des identifiants de ressources stables et les identifiants d’Assembly dans votre application, car les noms de fichiers, les dossiers, les liens et les métadonnées du fournisseur peuvent changer indépendamment.
Commencer par le modèle de stockage, pas par le logo du fournisseur
Le stockage objet convient naturellement aux médiathèques appartenant à l’application. Amazon S3, Azure Blob Storage, Backblaze B2, Cloudflare R2, DigitalOcean Spaces, Google Cloud Storage, MEGA S4 Object Storage, MinIO, OpenStack Swift, Supabase Storage, Tigris, Wasabi et Rackspace Cloud Files proposent des destinations organisées en buckets ou en conteneurs via leurs propres Robots Transloadit. Ils diffèrent néanmoins par leurs informations d’identification, leurs champs de point de terminaison ou de région, leurs contrôles d’accès et leurs URL de résultat. Le « stockage objet » décrit donc l’architecture plutôt qu’un format de configuration commun.
Box et Dropbox sont des services de fichiers dans le cloud organisés autour de comptes et de dossiers. Leurs dossiers, leurs liens et leurs systèmes de permissions destinés aux utilisateurs peuvent être utiles lorsque des personnes travaillent directement avec les fichiers exportés. FTP et SFTP ciblent quant à eux les serveurs de transfert de fichiers et les conventions existantes des systèmes de fichiers. Choisissez ces modèles parce qu’un partenaire ou un système hérité les impose, pas parce que leurs chaînes de chemin ressemblent à des clés d’objet.
Stockage objet
Privilégiez ce modèle pour les ressources de l’application accessibles par des clés stables, avec des règles de cycle de vie et une politique de bucket ou de conteneur contrôlée par le fournisseur.
Stockage collaboratif
Privilégiez Box ou Dropbox lorsque les dossiers de compte et les liens gérés par le fournisseur font partie de l’expérience produit requise.
Transfert de fichiers
Privilégiez SFTP ou FTP lorsque le système destinataire est défini par un compte serveur, une arborescence de répertoires et un contrat de transfert établi.
Associer chaque destination à sa paire de Robots Transloadit
Le nom de la destination correspond à un Robot d’importation et à un Robot de stockage : /s3/import et /s3/store, /azure/import et /azure/store, /backblaze/import et /backblaze/store, /box/import et /box/store, /cloudflare/import et /cloudflare/store, /digitalocean/import et /digitalocean/store, et /dropbox/import et /dropbox/store. Le même principe d’association s’applique à /ftp, /google, /mega, /minio, /sftp, /supabase, /swift, /tigris, /wasabi et /cloudfiles, par exemple /sftp/import avec /sftp/store.
Un Robot d’importation crée des fichiers que les Steps suivants peuvent traiter. Un Robot de stockage utilise les résultats sélectionnés d’un Step et les écrit dans la destination. Ce sens de transfert compte lors de la conception des permissions et de l’observabilité : une transformation réussie ne prouve pas que l’exportation a réussi, et une importation réussie ne prouve pas que la source restera disponible après le traitement. Enregistrez l’état final de l’Assembly et inspectez le résultat du Step de stockage dont vous dépendez réellement.
Entrées explicites
La relation use sélectionne les fichiers en amont ; le Robot de stockage n’exporte pas automatiquement tous les résultats de l’Assembly.
Destination explicite
Un Step propre au fournisseur constitue la frontière où les exigences de chemin, d’accès, de métadonnées et d’informations d’identification entrent dans le contrat du flux de travail.
Fin explicite
L’application ne devrait marquer une ressource comme durable qu’après la fin du stockage requis et l’enregistrement de son identité à destination.
Limiter la portée des informations d’identification de stockage et les garder sous le contrôle du serveur
Créez un ensemble d’informations d’identification de Template pour l’accès au fournisseur et référencez-le par son nom depuis un Template enregistré. Le fournisseur détermine toujours ce que cet ensemble permet de faire. Limitez sa portée au strict nécessaire en matière de chemins source et de destination, d’opérations, de buckets, de conteneurs ou de dossiers requis par le flux de travail. Lorsqu’un fournisseur prend en charge des ensembles d’informations d’identification distincts pour la lecture et l’écriture, cette séparation vous donne un périmètre de révocation plus net et réduit les conséquences d’un Template erroné.
N’envoyez pas de clés brutes du fournisseur dans des Assembly Instructions contrôlées par le navigateur et n’utilisez pas de champs client pour sélectionner une destination sans restriction. Le code serveur de confiance devrait autoriser l’utilisateur, choisir un Template vérifié et ne fournir que des champs métier aux valeurs limitées, comme un identifiant de ressource. Si plusieurs locataires ou destinations partagent une même structure de flux de travail, conservez à cette frontière de confiance la correspondance entre chaque locataire et le Template ou l’ensemble d’informations d’identification approuvé.
Moindre privilège
N’accordez les droits de listage et de lecture que là où une importation en a besoin, et le droit d’écriture que là où une exportation est autorisée à créer des objets.
Domaines de confiance distincts
Utilisez des ensembles d’informations d’identification distincts lorsque les accès aux environnements, aux locataires ou aux préfixes source, ou les permissions de destination, doivent pouvoir être révoqués indépendamment.
Sélection de confiance
Excluez les noms de Robots arbitraires, les hôtes des points de terminaison et les choix d’informations d’identification des requêtes contrôlées par un navigateur ou un agent non fiable.
Concevoir délibérément la diffusion publique, privée, signée et par URL personnalisée
Les intégrations de fournisseurs ne partagent pas un vocabulaire commun de contrôle d’accès. Amazon S3 propose à la fois acl et sign_urls_for, tandis que Cloudflare R2 propose sign_urls_for mais aucune option acl. Azure utilise des signatures d’accès partagé. La valeur par défaut du Robot d’Amazon S3 est public-read ; sur un bucket où Block Public Access est activé, cette valeur par défaut peut provoquer un échec avec une erreur de permission au lieu de publier l’objet. Pour une diffusion privée avec S3, utilisez private sur les buckets qui respectent les ACL d’objet, ou utilisez bucket-default lorsque les ACL sont désactivées ou que Block Public Access est activé. La valeur bucket-default omet l’en-tête ACL généré. Lorsque headers ne fournit lui non plus aucun en-tête ACL ou d’octroi de droits, la requête n’a pas besoin de s3:PutObjectAcl ; les en-têtes ACL ou d’octroi de droits fournis dans headers restent appliqués et nécessitent cette permission. Le Robot de stockage Wasabi utilise par défaut private lorsque acl n’est pas défini ; ne définissez explicitement public-read que pour une diffusion publique avec Wasabi. Wasabi ne prend pas en charge bucket-default. Box et Dropbox peuvent créer des liens de partage propres au fournisseur. Les autres destinations dépendent principalement de la configuration du bucket, du conteneur, du dossier ou du serveur en dehors du Step de l’Assembly.
Traitez les permissions et la génération d’adresses comme des questions distinctes. Un préfixe d’URL ou un modèle d’URL peut faire pointer un résultat vers un nom d’hôte de CDN ou d’application, mais réécrire une adresse ne configure pas l’origine, n’accorde pas de droit de lecture et ne copie pas le fichier. À l’inverse, un objet privé peut avoir une URL syntaxiquement valide qui renvoie à juste titre une erreur d’autorisation. Vérifiez le chemin exact emprunté par le consommateur, le comportement à l’expiration et les modalités de révocation pour le fournisseur sélectionné.
Objets publics
N’utilisez la politique du fournisseur ou une ACL explicite qu’après avoir déterminé si la récupération anonyme fait réellement partie du contrat du produit.
Accès signé
Pour un accès contrôlé, testez l’expiration des signatures, le décalage des horloges, les réponses en cache et ce qui se passe après le remplacement ou la suppression d’un objet.
URL personnalisées
Traitez les noms d’hôte CDN et les modèles d’URL personnalisés comme une configuration de routage qui doit correspondre aux autorisations de lecture réelles du fournisseur.
Construire un Step d’exportation clair avant d’ajouter des variantes par fournisseur
Un flux de travail de stockage doit rendre la circulation des données évidente. Le Template suivant reçoit un téléversement, crée un dérivé WebP aux dimensions limitées et exporte uniquement ce dérivé vers Cloudflare R2. Le nom de l’ensemble d’informations d’identification est résolu au sein du compte Transloadit, tandis que le chemin utilise les Assembly Variables pour éviter les clés d’objet du fournisseur choisies côté client. Un Template de production devrait ajouter la validation, les règles de nommage, les métadonnées et la politique d’écrasement requises par l’application.
La même structure de graphe peut servir de base pour une autre destination, mais la configuration du Step propre au fournisseur n’est pas interchangeable. Ne remplacez le Robot de stockage qu’après avoir lu son schéma et décidé du fonctionnement des informations d’identification, de la sélection du bucket ou du dossier, de l’accès, des URL et des collisions. Conservez des Templates distincts et vérifiés lorsque les différences sont importantes sur le plan opérationnel, même si leurs Steps de transformation restent identiques.
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"optimized": {
"use": ":original",
"robot": "/image/resize",
"resize_strategy": "fit",
"width": 1600,
"height": 1600,
"format": "webp"
},
"exported": {
"use": "optimized",
"robot": "/cloudflare/store",
"credentials": "my-r2-credentials",
"path": "media/${assembly.id}/${file.id}.${file.ext}"
}
}
}Traiter les importations de dossiers comme un travail d’inventaire avec prise en charge de la reprise
L’importation d’un seul fichier peut masquer la partie difficile d’une migration. Les fournisseurs diffèrent par la représentation des dossiers ou des préfixes, le caractère récursif du parcours par défaut ou sur activation explicite, le nombre d’entrées renvoyées par page et la valeur de continuation utilisée pour demander la page suivante. Lisez le schéma du Robot d’importation choisi et testez un jeu de données imbriquées dépassant une page avant de vous y fier pour une reprise de données historiques.
Enregistrez durablement l’intention de migration et sa progression dans votre propre système. Consignez l’identité de la source, la page ou le lot en cours, l’identité attendue à destination, l’identifiant de l’Assembly et le résultat final. Effectuez les nouvelles tentatives de façon idempotente et rapprochez les décomptes plutôt que de supposer qu’un nouveau listage d’une racine en croissance continue permettra de repérer à peu de frais tous les objets manqués. Pour une ingestion continue, préférez des événements persistants ou un manifeste adossé à une base de données aux parcours complets et répétés du bucket.
Jeux de données de test représentatifs
Testez des dossiers vides, des noms imbriqués, des caractères inhabituels, des noms de base identiques et un listage qui franchit au moins une limite de page.
Points de reprise persistants
Stockez la progression en dehors du processus pour qu’un redémarrage du processus de travail n’impose pas un nouveau listage complet et ne saute pas silencieusement la page en cours.
Réconciliation
Comparez les enregistrements source attendus aux enregistrements finalisés à destination et signalez explicitement les objets manquants, dupliqués ou remplacés par une version plus récente.
Valider la reprise après échec et les responsabilités liées au cycle de vie
Testez des informations d’identification incorrectes, une source manquante, un point de terminaison indisponible, un chemin de destination dont l’accès est refusé, une collision de noms, une signature expirée et une exportation partielle de plusieurs fichiers. L’envoi des notifications peut être retenté ; le traitement de la fin des opérations doit donc être idempotent. Conservez l’identifiant de l’Assembly avec la ressource de l’application et déterminez quels états finaux permettent une nouvelle tentative automatique, nécessitent un examen par un opérateur ou doivent laisser la source intacte.
Le stockage de destination des exportations et le stockage temporaire de Transloadit relèvent de responsables et de cycles de vie différents. Le résultat d’une Assembly terminée n’est pas une sauvegarde, et la suppression d’un enregistrement de l’application ne supprime pas automatiquement les copies chez chaque fournisseur, dans chaque cache ou à chaque emplacement de traitement temporaire. Documentez la conservation, le remplacement et la suppression de la source, du dérivé, des métadonnées du résultat et de l’adresse publique, puis testez ces opérations avec autant de soin que le scénario nominal initial.
Finalisation sans doublons
Utilisez une règle d’idempotence au niveau de l’application pour qu’un rappel répété ou une nouvelle tentative ne crée pas involontairement une seconde ressource persistante.
Observabilité par Step
Surveillez séparément l’importation, la transformation et l’exportation pour qu’un Step réussi en amont ne puisse pas masquer l’échec d’un transfert vers un stockage durable.
Contrat de cycle de vie
Consignez quel système supprime chaque source, résultat temporaire, dérivé, réponse en cache et enregistrement de l’application, ainsi que le moment de chaque suppression.
Détails techniques à connaître
- Les destinations prises en charge utilisent des Robots d’importation et de stockage associés par paires, notamment Amazon S3, Azure Blob Storage, Backblaze B2, Box, Cloudflare R2, DigitalOcean Spaces, Dropbox, FTP, Google Cloud Storage, MEGA S4 Object Storage, MinIO, SFTP, Supabase Storage, OpenStack Swift, Tigris, Wasabi et Rackspace Cloud Files.
- Un Step de stockage exporte uniquement les résultats sélectionnés par sa valeur
use, de sorte que l’exportation d’un original, d’un dérivé ou de leur combinaison est déterminée par le graphe de l’Assembly plutôt que par le fournisseur de destination. - Les ensembles d’informations d’identification de Template sont des enregistrements au niveau du compte, référencés par leur nom. Ils permettent de garder les clés du fournisseur hors des bundles destinés au navigateur et des Assembly Instructions, tout en exigeant que la portée de l’ensemble d’informations d’identification soit limitée chez le fournisseur.
- Les contrôles d’accès sont propres à chaque fournisseur : Amazon S3 expose à la fois
acletsign_urls_for, Cloudflare R2 exposesign_urls_formais aucune optionacl, Azure peut produire des signatures d’accès partagé, et Box ou Dropbox peuvent créer des liens de partage. - Un préfixe d’URL ou un modèle d’URL personnalisé modifie l’adresse indiquée dans un résultat d’Assembly ; à lui seul, il n’accorde aucun accès, ne configure pas de CDN, ne téléverse pas une autre copie et ne prouve pas que l’objet est publiquement accessible en lecture.
- Les Robots d’importation diffèrent par le parcours des répertoires, le listage récursif, la taille des pages et le comportement des jetons de continuation. Une migration en masse doit donc suivre le schéma du Robot choisi et enregistrer durablement sa progression en dehors d’une simple boucle en mémoire.
- FTP et SFTP stockent les fichiers dans le système de fichiers d’un serveur plutôt que dans un espace de noms de stockage objet ; SFTP prend en charge l’authentification par clé et la configuration du mode des fichiers, tandis que FTP repose sur son propre transport et son propre modèle d’autorisations du serveur.
- Les résultats temporaires d’Assembly ne constituent pas un stockage durable pour l’application. Tout résultat devant subsister au-delà de la période de conservation temporaire devrait donc être exporté et faire l’objet d’une réconciliation avec le système de référence de l’application.
Une approche pratique
- 1
Classez la destination selon le modèle de stockage, la région requise, le périmètre de propriété et le chemin de récupération attendu.
- 2
Créez des informations d’identification de Template respectant le principe du moindre privilège et testez séparément les permissions d’importation et de stockage.
- 3
Vérifiez, avec des fichiers représentatifs, le comportement des objets privés, publics, remplacés et supprimés, ainsi que celui des accès signés et expirés.
- 4
Testez la pagination, les importations récursives, les nouvelles tentatives, les exportations dupliquées et les échecs partiels avant de migrer le trafic de production.
Quand Transloadit est utile
Utilisez un Robot natif d’importation ou de stockage de Transloadit lorsqu’un flux de travail doit déplacer des fichiers entre le traitement et un service de stockage pris en charge sans que votre application serve d’intermédiaire pour les octets. Choisissez d’abord la destination en fonction des exigences opérationnelles, puis configurez explicitement ses informations d’identification et son comportement d’accès.
Périmètre architectural
Transloadit importe les fichiers, les traite et exporte les résultats sélectionnés via le Robot configuré. La destination reste responsable du stockage durable, de la politique du bucket ou du dossier, du cycle de vie des objets, de la réplication et de la diffusion. Votre application reste responsable de l’autorisation des utilisateurs, des enregistrements des ressources, des décisions de publication et de la suppression de toutes les copies.
Questions fréquentes
Une URL de résultat signifie-t-elle que le fichier exporté est public ?
Non. L’adresse dans un résultat d’Assembly indique l’emplacement de l’objet selon le fournisseur ou la correspondance d’URL configurée. La possibilité pour un client de le récupérer dépend toujours de la politique du bucket, d’une liste de contrôle d’accès (ACL) de l’objet, d’un lien de partage du fournisseur, d’une signature valide ou des permissions du système de fichiers et du serveur web. Testez l’accès depuis un client non authentifié plutôt que de considérer la présence de url ou de ssl_url comme une vérification des permissions.
Les importations et les exportations devraient-elles partager un même ensemble d’informations d’identification ?
Généralement non. N’accordez à un ensemble d’informations d’identification d’importation que les droits de lecture et de listage sur le préfixe source nécessaire, et à un ensemble d’informations d’identification d’exportation que le droit d’écriture sur son préfixe de destination. Des ensembles distincts limitent les conséquences d’une fuite ou d’une mauvaise configuration des informations d’identification et facilitent l’interprétation des journaux d’audit côté fournisseur. Un ensemble unique doté de droits plus larges peut être pratique, mais cette commodité ne prouve pas que les deux sens de transfert nécessitent les mêmes permissions.
Quand devrais-je utiliser SFTP ou FTP plutôt que le stockage objet ?
Utilisez une intégration native lorsqu’elle correspond au fournisseur et que le flux de travail devrait éviter de faire transiter les octets des fichiers par les serveurs de l’application. Choisissez SFTP lorsqu’un contrat existant avec un partenaire impose le transfert de fichiers par SSH ou un système de fichiers sur serveur. Utilisez FTP uniquement pour assurer la compatibilité avec un point de terminaison qui ne peut pas proposer une voie plus sécurisée prise en charge, puis restreignez le compte, le chemin de destination et l’exposition réseau autant que le serveur le permet.
Comment mon application devrait-elle suivre les fichiers chez différents fournisseurs ?
Stockez l’identifiant d’Assembly, l’identifiant de ressource indépendant du fournisseur, la clé ou le chemin de destination et la version prévue dans votre base de données. Traitez les notifications comme des événements susceptibles d’être renvoyés et rendez le traitement de fin idempotent. Pour une importation volumineuse, enregistrez durablement la progression par page ou par lot et rapprochez les ressources attendues des exportations terminées. Les noms de dossiers et les URL de partage du fournisseur sont des données de présentation utiles, mais constituent des identifiants principaux fragiles.
Puis-je changer de fournisseur en modifiant uniquement le nom du Robot ?
Pas de manière sûre sans examiner le contrat. Le graphe de l’Assembly peut rester similaire, mais les informations d’identification, les champs de bucket ou de conteneur, les règles de chemin, les paramètres d’accès, les champs d’URL de résultat, la récursivité et la pagination peuvent différer. Créez un adaptateur de fournisseur dans le code de confiance de l’application ou maintenez des Templates vérifiés pour chaque destination. Ne permettez pas à un navigateur de sélectionner un Robot arbitraire ni d’injecter des informations d’identification de stockage dans des Instructions par ailleurs fiables.