Migrer de Filestack vers Transloadit

Filestack propose la sélection, le téléversement et le stockage de fichiers, ainsi que des transformations via CDN⁠ et des flux de travail asynchrones⁠. Avec Transloadit, Uppy gère la sélection dans le navigateur et les Robots assurent le traitement des fichiers. Définissez un flux de travail pris en charge dans un Template, puis utilisez un SDK, Uppy ou l’API REST pour créer des Assemblies. Vérifiez individuellement les tâches utilisées par votre application ; la correspondance ci-dessous ne promet pas une équivalence complète des fonctionnalités.

Ce guide couvre le traitement et l’exportation de fichiers vers un stockage que vous contrôlez. Il ne met pas en œuvre une migration vers un DAM hébergé par Transloadit. L’importation dans une bibliothèque multimédia hébergée, la conservation de ses dossiers et métadonnées, la distribution via tlcdn.com, les simulations et manifestes de migration, ainsi que les rôles, widgets et intégrations CMS/éditeur de la bibliothèque multimédia nécessitent un plan de migration séparé. L’inventaire décrit ci-dessous est un registre de migration géré par l’application, et non un outil de migration vers un DAM hébergé.

Tableau de correspondance pour la migration

Les alias de stockage de Filestack rendent un stockage externe existant accessible à son service de traitement sans téléversement via Filestack. Si vous possédez déjà le bucket source, déterminez si les originaux peuvent y rester pendant que vous traitez et exportez de nouveaux fichiers dérivés. Pour le stockage géré par Filestack, téléchargez les originaux auxquels vous êtes autorisé à accéder via son CDN⁠ avant de résilier le compte. Ce guide ne fournit aucun script d’exportation en masse du compte ni de découverte des ressources.

Conserver le catalogue séparément. Avant de copier les octets, consignez votre identifiant de ressource, la référence Filestack, l’URL de téléchargement de l’original, l’emplacement de stockage/conteneur/chemin, le nom du fichier, le type MIME, la taille, la somme de contrôle et les fichiers dérivés requis. Le point de terminaison de métadonnées⁠ de Filestack peut renvoyer des caractéristiques du fichier, des informations de stockage et des empreintes ; il génère ces informations à la demande. Conservez l’inventaire des sources et la correspondance des Assemblies/exportations terminées dans votre propre base de données.

Les étiquettes de téléversement du sélecteur⁠ de Filestack sont renvoyées dans les réponses de téléversement et les webhooks. Son DAM⁠ permet aussi aux utilisateurs de modifier les étiquettes et descriptions des ressources. Conservez ces données séparément des métadonnées des fichiers ; les Templates ci-dessous copient et traitent les octets, pas les étiquettes ni les descriptions du catalogue. Utilisez les chemins de stockage consignés pour déterminer comment les clés des objets de destination conserveront les dossiers ; ces exemples génèrent de nouveaux chemins. Inventoriez les collections et les relations entre révisions utilisées par votre application, y compris leur ordre et leurs permissions. L’opération d’écrasement⁠ de Filestack remplace le fichier associé à une référence : un téléchargement n’est donc pas une exportation de l’historique des versions. Ce guide n’exporte ni l’appartenance aux collections ni les anciennes révisions ; si vous en avez besoin, récupérez-les depuis votre application ou vos archives existantes avant la bascule.

Construire un Template pour chaque flux de travail

Adapter les recettes de transformation. Le moteur de traitement⁠ de Filestack accepte des tâches dans les URL CDN, tandis que ses flux de travail définissent les tâches et la logique conditionnelle. Inventoriez la chaîne complète de tâches, les paramètres, les préréglages nommés de l’application, les identifiants des flux de travail et les conditions utilisés par chaque vue de l’application. Reconstruisez les recettes requises sous forme de Templates, générez les fichiers dérivés et comparez des images et documents représentatifs pour vérifier le recadrage, le rapport d’aspect, l’orientation, la sélection des pages, la qualité et le format. Un Robot de création de vignettes ne remplace pas le Filestack Document Viewer⁠ interactif ; choisissez une visionneuse distincte si votre application en a besoin. Les exemples ci-dessous couvrent les aperçus d’images/PDF et un aperçu générique de fichier ; ils ne reproduisent pas toutes les tâches de transformation ou d’analyse intelligente de Filestack.

Ce Template vérifie le type MIME détecté, crée une vignette d’image ou de la première page d’un PDF, et stocke les originaux acceptés et les aperçus. Les autres types MIME arrêtent l’Assembly avec une erreur. Il s’agit d’un filtrage par type, et non d’une analyse de logiciels malveillants ; ajoutez /file/virusscan si votre flux de travail l’exige :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/[^/]+|application/pdf)$"]],
      "error_on_decline": true
    },
    "images": {
      "use": "accepted_files",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^image/"]]
    },
    "pdfs": {
      "use": "accepted_files",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "=", "application/pdf"]]
    },
    "image_thumb": {
      "use": "images",
      "robot": "/image/resize",
      "width": 600,
      "height": 600,
      "resize_strategy": "fit",
      "format": "webp",
      "result": true
    },
    "document_thumb": {
      "use": "pdfs",
      "robot": "/document/thumbs",
      "format": "jpg",
      "page": 1,
      "width": 600,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_files", "image_thumb", "document_thumb"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "filestack-import/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Les deux filtres de routage utilisent les types MIME pour orienter les images et les PDF vers des branches d’aperçu distinctes. Les originaux refusés n’entrent jamais dans le Step d’exportation. Une Assembly n’est pas une transaction : les fichiers acceptés déjà exportés ne sont pas annulés si un autre fichier échoue. Ignorer les erreurs masque les échecs ; cela ne remplace ni le routage ni la validation.

Suivez les objets de stockage écrits par chaque tentative de migration des données existantes. Avant de relancer une Assembly ayant échoué, rapprochez ou supprimez ses exportations partielles pour éviter que les nouvelles tentatives ne laissent des objets en double ou orphelins. Ne publiez pas les tentatives ayant échoué dans votre application, même si certains fichiers ont été exportés avec succès.

Configurez votre CDN pour lire la racine du bucket ; url_prefix modifie uniquement les URL renvoyées. acl: "bucket-default" EN (English) n’envoie aucune ACL d’objet ; configurez l’accès via la politique de votre bucket et l’accès à l’origine du CDN. Après ASSEMBLY_COMPLETED, lisez les originaux acceptés dans results.accepted_files et les aperçus dans results.image_thumb et results.document_thumb. L’exportation ajoute ou met à jour les entrées sous les Steps nommés dans son paramètre use, sauf si le Step concerné définit explicitement result: false. Enregistrez durablement uniquement les entrées ayant is_temp_url: false. Les URL temporaires de Transloadit expirent après 24 heures ; consultez Enregistrer les fichiers de résultat.

Remplacer la sélection de fichiers

Pour les intégrations dans le navigateur, remplacez le sélecteur Filestack par Uppy. Uppy peut sélectionner des fichiers locaux, gérer les téléversements par glisser-déposer et se connecter à des sources distantes. Le plugin Transloadit envoie les fichiers à une Assembly à l’aide de votre Template. Activez waitForEncoding pour recevoir les résultats du traitement terminé dans le navigateur, ou définissez notify_url dans votre requête d’Assembly signée et traitez les Assembly Notifications sur votre backend. Vérifiez les signatures des notifications et exigez une exécution terminée avec succès avant de mettre à jour votre base de données.

La réponse du sélecteur⁠ de Filestack contient des références de fichiers, des URL et des métadonnées de téléversement ; onUploadDone signale les fichiers téléversés et ceux dont le téléversement a échoué. Réécrivez les gestionnaires qui attendent cette structure de réponse, et testez l’annulation, les nouvelles tentatives, les types/tailles de fichiers autorisés, l’accessibilité et chaque flux d’autorisation des sources distantes. Conservez les étiquettes du catalogue sur votre backend et associez-les à votre identifiant de ressource, plutôt que de supposer que les métadonnées du sélecteur sont conservées lors de l’exportation.

Remplacer l’automatisation et la sécurité de manière réfléchie. Les webhooks⁠ de Filestack ont des charges utiles propres à chaque événement et utilisent les en-têtes FS-Timestamp et FS-Signature pour la vérification. Les résultats des tâches de ses flux de travail ne constituent pas une charge utile d’Assembly Status. Implémentez le récepteur Transloadit selon son propre contrat documenté et son schéma de signature. Rendez les mises à jour de la base de données idempotentes, conservez l’identifiant d’Assembly et rapprochez les exportations partielles avant de relancer le traitement. Distinguez la fin du téléversement de la réussite du traitement et de l’exportation avant de publier une ressource.

Les politiques de sécurité⁠ de Filestack utilisent des politiques Base64URL signées avec HMAC-SHA256 et peuvent restreindre l’expiration, les appels, les références, les chemins/conteneurs de téléversement et la taille. L’authentification du téléversement et de la distribution est configurable ; inventoriez ce que votre application impose réellement. Recréez l’autorisation de téléversement à l’aide de l’authentification Transloadit sur votre backend, et configurez l’autorisation de téléchargement avec votre stockage/CDN. Les politiques et signatures Filestack existantes n’autorisent pas l’accès au service de remplacement. Ne rendez jamais publiques des exportations privées dans le seul but de remplacer une URL source signée. Le paramètre d’accès au téléversement S3⁠ de Filestack contrôle l’accès aux objets stockés ; examinez la politique du bucket de destination, l’accès à l’origine du CDN et tout schéma de téléchargement signé séparément de l’authentification des Assemblies. Les exemples d’exportation définissent acl: "bucket-default" ; vérifiez la politique de destination avant la migration.

La détection de virus⁠ de Filestack s’exécute de manière asynchrone via des flux de travail après le téléversement vers le stockage. Si vous l’utilisez, concevez et testez le contrôle d’analyse antivirus et de mise en quarantaine qui la remplacera avant de publier les originaux ou les aperçus. Ni le filtrage MIME ni un téléversement réussi ne prouvent qu’un fichier est sûr.

Prendre en compte les outils des agents. Le Filestack Claude Plugin⁠ expose des outils de téléversement, de transformation, de signature des politiques, d’exécution des flux de travail et de vérification des webhooks. Inventoriez les URL et flux de travail réellement générés ou appelés par ces outils. Reconstruisez les opérations requises avec des définitions de Templates vérifiées et des appels SDK/API ; ce guide ne propose pas de remplacement directement interchangeable du plugin ou de ses modèles d’analyse intelligente. Conservez les révisions des Templates, les identifiants d’Assemblies, les vérifications des résultats et les décisions de nouvelle tentative pour l’assistance et l’inspection. Estimez les coûts de traitement et de stockage pour un lot représentatif, limitez la concurrence et les nouvelles tentatives de la migration des données existantes, et examinez les flux de données régionaux, la conservation et les exigences de conformité avant d’autoriser la migration complète. Ce guide n’établit ni la conformité réglementaire ni une configuration de routage régional.

Importer les URL Filestack existantes

Les URL CDN⁠ de Filestack identifient les fichiers par leur référence. Sélectionnez l’URL de l’original à laquelle vous êtes autorisé à accéder, sans tâches de transformation, et fournissez une politique de lecture ou une signature valide si la sécurité de la source l’exige. Prévoyez une expiration suffisamment lointaine pour le téléchargement en attente, et n’incluez pas les URL sources signées dans les journaux ni les manifestes publics. Si l’URL se résout en une URL HTTPS permettant le téléchargement, migrez le fichier avec 🤖/http/import :

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.filestack_url}"
    },
    "preview": {
      "use": "imported",
      "robot": "/file/preview",
      "result": true
    },
    "exported": {
      "use": ["imported", "preview"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "filestack-backfill/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

Sélectionnez les valeurs de filestack_url autorisées dans l’inventaire des ressources de votre backend. /file/preview est en bêta et utilise une icône générique du type de fichier lorsqu’il ne peut pas générer une vignette du contenu. Exécutez des tâches de migration des données existantes avec des limites définies ; /http/import accepte aussi un tableau d’URL. Conservez les références et les URL sources jusqu’à ce que l’accès et la qualité de l’exportation terminée aient été vérifiés. Les objets S3 privés nécessitent un téléchargement autorisé ou votre CDN configuré. Le Template d’importation renvoie les fichiers exportés sous results.imported et results.preview.

Remplacer les URL de distribution après vérification. Conservez une correspondance entre chaque ancienne référence accompagnée de sa recette de transformation et sa nouvelle URL exportée. Vérifiez les sommes de contrôle des originaux, l’apparence des fichiers dérivés, les types MIME et l’accès autorisé/public avant de mettre à jour les enregistrements de la base de données, le balisage rendu, le CSS, le contenu du CMS et les réponses de l’API. Régénérez les fichiers dérivés requis au lieu d’ajouter des tâches Filestack au nouveau nom d’hôte du CDN. Conservez les anciens enregistrements et un mécanisme de bascule du chemin de lecture permettant un retour arrière, pendant que les nouveaux téléversements utilisent le nouveau chemin.

Vous pouvez rediriger les URL servies depuis un domaine que vous contrôlez. Si vous utilisez le CNAME personnalisé⁠ de Filestack, ne remplacez son origine qu’une fois que votre couche de distribution peut résoudre les anciens chemins de références/tâches et faire respecter les règles d’accès prévues. Vous ne pouvez pas installer vos redirections sur le domaine partagé cdn.filestackcontent.com de Filestack : remplacez ces liens dans le contenu que vous contrôlez et prévoyez de maintenir l’accès à la source pour les références que vous ne pouvez pas mettre à jour. Testez le comportement du cache et les contrôles d’accès avant de rendre les redirections permanentes.

Liste de contrôle

Estimation pour la planification. Pour un sélecteur, un inventaire de ressources accessible, quelques recettes d’aperçu et un bucket que vous contrôlez, prévoyez plusieurs jours de travail d’ingénierie pour un projet pilote testé. Une migration importante de données existantes, la compatibilité avec un domaine personnalisé, la distribution privée, les visionneuses de documents et les exportations du catalogue/des versions gérés par l’application peuvent prendre des semaines ou davantage. Il s’agit d’estimations de planification, et non de mesures de performance de migration ; chronométrez un lot représentatif et prenez en compte les limites de transfert, le coût de traitement, la validation et le retour arrière.

1. Inventoriez les références, les chemins de stockage, les étiquettes/descriptions, les versions, les fonctions de rappel du sélecteur, les règles de sécurité, les recettes de transformation, les tâches des flux de travail et l’utilisation des outils d’agents. Résolvez les questions liées à toute fonctionnalité exclue avant la bascule.
2. Choisissez les clés des objets de destination, le stockage du catalogue, l’autorisation de téléchargement, le CDN et la stratégie pour les anciennes URL. Configurez les informations d’identification pour les services tiers avec les accès nécessaires.
3. Construisez et vérifiez les Templates avec des images et PDF représentatifs, des fichiers non pris en charge et des échecs. Incluez un contrôle d’analyse antivirus et de mise en quarantaine si nécessaire.
4. Remplacez le sélecteur et le récepteur de webhooks dans un projet pilote. Vérifiez la gestion de la fin d’exécution, les contrôles des signatures, les nouvelles tentatives, l’idempotence et l’accès aux téléchargements privés.
5. Effectuez une migration des données existantes avec des limites définies ; consignez les exportations terminées et rapprochez les tentatives partielles. Comparez les sommes de contrôle des originaux et la qualité des fichiers dérivés avant de changer le chemin de lecture d’une ressource.
6. Basculez les nouveaux téléversements, rapprochez les derniers changements de la source, puis migrez les lectures par groupes. Surveillez les erreurs, les coûts et le trafic des anciennes URL ; conservez un chemin de retour arrière et l’accès à la source jusqu’à la validation finale.