Migrer d’Uploadcare vers Transloadit

Uploadcare propose des API de téléversement, de gestion et d’URL⁠, notamment la diffusion par CDN et les groupes de fichiers⁠. Transloadit sépare ces fonctions en Robots de téléversement/importation, Robots de traitement, Robots d’exportation et diffusion par CDN facultative. Inventoriez les opérations que vous utilisez et associez les traitements pris en charge à des Steps dans un Template Transloadit ; cette approche ne remplace pas à l’identique toutes les fonctionnalités d’Uploadcare.

Ce guide transfère les téléversements et les traitements vers des Templates et exporte les fichiers vers votre propre stockage. Il ne met pas en œuvre les importations DAM hébergées de Transloadit, la migration gérée des dossiers et métadonnées, la bascule de la diffusion tlcdn.com, les simulations de migration et manifestes, les rôles de la médiathèque, les sélecteurs de ressources ou les intégrations aux CMS et éditeurs. Ces éléments nécessitent un plan de migration DAM distinct.

Correspondance des concepts pour la migration

Utilisez les dépendances entre Steps pour acheminer les fichiers entre les traitements, et non pour remplacer les enregistrements persistants de groupes de fichiers. Signez les URL du Smart CDN sur votre backend et utilisez un Template compatible distinct pour la diffusion à la demande.

Décisions de transformation. Inventoriez les chaînes complètes d’opérations d’URL, les préréglages de l’application, les coordonnées de recadrage, l’orientation, les dimensions, la qualité et le format. L’option format/auto⁠ d’Uploadcare sélectionne les formats selon les capacités du navigateur ; l’avatar WebP au format fixe ci-dessous ne reproduit pas cette négociation. Comparez les résultats sur des images représentatives, notamment avec transparence et animation. Les conversions vidéo nécessitent leurs propres Templates ; aucun des deux exemples ci-dessous ne migre le streaming vidéo, la conversion de documents, toutes les opérations d’URL ou les plugins personnalisés de l’outil de téléversement.

La modération est un flux de travail distinct. La modération des images inappropriées⁠ d’Uploadcare peut analyser les images lors du téléversement ou via un module complémentaire REST asynchrone, avec les résultats dans appdata. Conservez le résultat et la politique de modération, notamment les seuils et les décisions de suppression ou d’examen, dans votre inventaire de migration. Ces exemples optimisent les fichiers ou en créent un aperçu ; ils ne reproduisent pas ce contrôle de modération. Choisissez et validez une solution de remplacement avant de publier des contenus UGC, et conservez le contrôle existant jusqu’à ce qu’elle soit prête. Le filtrage MIME, l’analyse antimalware et la détection de contenus inappropriés répondent à des problèmes différents.

Remplacer le widget de téléversement

Pour les téléversements depuis le navigateur, utilisez Uppy avec le plugin Transloadit. Uppy vous fournit un sélecteur de fichiers, une interface de glisser-déposer, des téléversements avec reprise, des sources distantes et une intégration directe à Transloadit.

Un flux Uploadcare classique où les utilisateurs téléversent une image et reçoivent des URL CDN de versions transformées devient :

1. Le navigateur téléverse les fichiers via Uppy et référence un Template Transloadit enregistré.
2. Le Template crée toutes les variantes dont votre application a besoin.
3. Transloadit envoie une notification à votre backend avec les URL des résultats.
4. Votre backend enregistre ces URL dans votre base de données.

Configurez un notify_url dans la requête d’Assembly signée et vérifiez les signatures des notifications reçues. Pour attendre la fin du traitement côté navigateur, activez l’option waitForEncoding d’Uppy ; par défaut, seul le téléversement est attendu.

Réécrivez les fonctions de rappel qui attendent des UUID Uploadcare, des identifiants de groupe ou des URL d’opérations CDN. Conservez votre propre identifiant de ressource et associez-le à l’Assembly terminée et aux fichiers exportés. Testez les sources locales et distantes, la reprise, l’annulation, la validation et les échecs ; remplacer l’interface de téléversement ne remplace pas un navigateur de ressources ou une intégration CMS existants.

Les webhooks⁠ d’Uploadcare couvrent les événements de téléversement, d’informations sur les fichiers, de stockage et de suppression. Leur secret de signature facultatif produit un en-tête X-Uc-Signature, et les envois qui échouent sont retentés. Associez la fin du traitement aux Assembly Notifications, gérez les événements de catalogue et de suppression dans votre application, et utilisez la vérification des notifications propre à Transloadit. Rendez les mises à jour idempotentes par identifiant d’Assembly et exigez une exportation réussie avant la publication. Testez le comportement des nouvelles tentatives et de la réconciliation plutôt que de reprendre l’ancienne charge utile des événements ou le calendrier des nouvelles tentatives.

Décisions de sécurité. Les téléversements signés⁠ d’Uploadcare autorisent l’ingestion ; la diffusion signée⁠ restreint séparément l’accès via un sous-domaine CDN sécurisé ou un domaine personnalisé configuré. Inventoriez les chemins publics et privés, l’expiration des jetons et les variantes autorisées. Utilisez des requêtes Transloadit signées par le backend pour les Templates et champs autorisés, puis imposez l’autorisation de téléchargement via votre bucket/CDN. Une requête d’Assembly signée n’accorde ni ne restreint l’accès à un objet S3 exporté. Ne rendez pas les fichiers privés publics pour simplifier la migration. Si vous utilisez la protection antimalware d’Uploadcare⁠, ajoutez et testez un Step d’analyse antimalware explicite ainsi qu’un contrôle de mise en quarantaine et de publication ; les Templates présentés n’effectuent aucune analyse antimalware des fichiers. La mise en œuvre complète des ACL, l’évaluation de la conformité et le routage régional sortent du cadre des exemples de ce guide.

Exemple de Template

Ce Template reçoit une image téléversée, crée un avatar WebP carré, optimise à la fois l’original et l’avatar, puis stocke les fichiers optimisés sur S3. L’optimisation n’a pas de paramètre de format et, avec progressive désactivé comme ici, renvoie l’original si le fichier optimisé est plus volumineux. Activer progressive permet de conserver un résultat d’optimisation même s’il est plus volumineux :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "avatar": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 512,
      "height": 512,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized_original": {
      "use": ":original",
      "robot": "/image/optimize",
      "result": true
    },
    "optimized_avatar": {
      "use": "avatar",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": ["optimized_original", "optimized_avatar"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "uploads/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Configurez les informations d’identification pour les services tiers pour S3 et configurez votre CDN pour servir la racine du bucket avec un accès en lecture. url_prefix ne crée pas de CDN et n’accorde aucun accès. 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, récupérez l’original dans results.optimized_original et l’avatar dans results.optimized_avatar. Ne conservez durablement que les entrées avec is_temp_url: false : l’exportation met à jour les URL du Step qui a produit les fichiers. Les URL temporaires de Transloadit expirent après 24 heures ; consultez Enregistrer les fichiers de résultat.

Importer les fichiers Uploadcare existants

Inventorier les originaux et les données du catalogue. Énumérez les UUID référencés par votre application et réconciliez-les avec l’inventaire des fichiers de l’API REST⁠ du projet, en suivant la pagination. Les informations sur les fichiers⁠ comprennent original_file_url, original_filename, la taille du fichier, l’état du stockage et les données de traitement. Sélectionnez le téléchargement autorisé de l’original pour chaque fichier ; si original_file_url est absent ou si le fichier a été supprimé, résolvez ce manque avant de migrer son enregistrement. Obtenez de nouvelles URL sources signées sur votre backend lorsque cela est nécessaire.

Conservez les métadonnées arbitraires⁠, les tags⁠ et les données appdata pertinentes dans votre base de données ou dans des enregistrements annexes ; l’importation des octets ne les copie pas. Les groupes de fichiers⁠ sont des collections immuables dont les membres sont indexés, et un membre peut inclure une recette de transformation. Enregistrez séparément l’identifiant du groupe, les UUID ordonnés de ses membres et les recettes. Une Assembly traite les fichiers, mais ne recrée pas cette collection persistante. Conservez les chemins des dossiers, les autres relations entre collections et l’historique des révisions gérés par votre application, en attribuant des clés de stockage distinctes aux révisions ; ces Templates ne découvrent ni n’exportent les révisions historiques ou les relations propres à l’application.

Si votre inventaire contient déjà des URL de téléchargement Uploadcare autorisées, importez-les avec 🤖/http/import :

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

Le Step d’aperçu utilise 🤖/file/preview EN (English) (bêta) ; il peut renvoyer une icône générique du type de fichier lorsqu’aucune miniature du contenu n’est disponible. Sélectionnez des valeurs uploadcare_url autorisées sur votre backend. L’importation d’une URL CDN transformée copie cette version, qui n’est pas nécessairement l’original. Vous pouvez importer uniquement les fichiers référencés ou transmettre un tableau d’URL autorisées à /http/import pour un lot de taille limitée. Conservez une correspondance entre les anciens identifiants et les nouveaux emplacements, et vérifiez l’accès aux fichiers diffusés ainsi que la qualité des résultats avant de basculer les lectures. Ce Template d’importation renvoie les fichiers exportés sous results.imported et results.preview. Les objets S3 privés nécessitent un téléchargement autorisé ou l’utilisation de votre CDN configuré.

Liste de contrôle

Bascule de la diffusion. Enregistrez une correspondance entre chaque UUID et chaque chaîne d’opérations utilisée, d’une part, et leur destination vérifiée, d’autre part. Remplacez les URL dans les enregistrements de l’application, les pages rendues, srcset, le CSS, les e-mails et le contenu des CMS ; ajouter la syntaxe d’opérations d’Uploadcare à un nouveau nom d’hôte de stockage n’applique pas ces opérations. Utilisez des redirections uniquement sur un domaine ou une route d’application que vous contrôlez, avec un mécanisme de résolution des anciens chemins et les règles d’accès prévues. Pour les URL CDN appartenant au fournisseur, mettez à jour les références que vous contrôlez et maintenez l’accès aux sources pendant la période de coexistence. Testez l’autorisation, la mise en cache et les pages réelles avant de rendre les redirections permanentes ou de supprimer les fichiers sources.

Estimation pour la planification. Pour un outil de téléversement, quelques variantes d’images, un inventaire accessible et un bucket/CDN existant, prévoyez plusieurs jours de travail d’ingénierie pour un pilote testé, suivis du temps mesuré pour l’importation des fichiers existants. La diffusion privée, les groupes, la modération, les modifications du CMS et les exportations de révisions et de catalogues peuvent nécessiter plusieurs semaines ou plus. Il s’agit d’une estimation de planification du travail d’ingénierie, et non d’un benchmark de migration mesuré. Mesurez le débit et le coût de l’importation, du traitement et de l’exportation sur un lot représentatif, en incluant les téléchargements depuis la source, la diffusion depuis la destination et la période d’utilisation simultanée des deux services.

1. Inventoriez les originaux, les métadonnées, les tags, l’ordre des groupes et les recettes, les révisions, les règles d’accès, les opérations, les fonctions de rappel de l’outil de téléversement et les résultats de modération. Traitez les fonctionnalités exclues avant la bascule.
2. Versionnez les Instructions du Template dans votre dépôt et testez les variantes et les contrôles requis. Conservez les révisions du Template, les identifiants d’Assembly, les échecs et les correspondances de destinations pour le support.
3. Configurez les informations d’identification, l’accès au stockage/CDN, la signature et le récepteur de notifications. Vérifiez la pérennité de la diffusion et la gestion des doublons et des échecs lors d’un pilote.
4. Définissez des tailles de lots limitées, le niveau de concurrence, les limites de nouvelles tentatives et un budget de migration. Confirmez les régions de traitement et de stockage, la conservation des données et les exigences de conformité avant de déplacer les données.
5. Basculez les nouveaux téléversements derrière un indicateur de fonctionnalité, importez les fichiers existants par lots de taille limitée et réconciliez les exportations partielles avant les nouvelles tentatives. Comparez les originaux, les fichiers dérivés, les décomptes du catalogue et l’accès privé.
6. Mettez à jour les lectures et les références de diffusion par cohortes, en conservant la correspondance avec les sources pour permettre un retour arrière. Réconciliez les dernières modifications de la source et maintenez l’ancienne diffusion disponible jusqu’à l’expiration de la période de retour arrière et des durées de vie des caches.