Migrer de Cloudinary vers Transloadit

Cloudinary prend en charge les préréglages de téléversement⁠, les URL de transformation⁠ et une bibliothèque de ressources⁠. Transloadit organise le traitement autour des Assembly Instructions : des flux de travail explicites qui exécutent des Robots pour téléverser, importer, transformer, optimiser, stocker et diffuser des fichiers.

Ce guide migre les téléversements et le traitement vers des Templates et exporte les ressources vers un stockage qui vous appartient. Conservez le catalogue de ressources de votre application aux côtés de ce stockage. L’importation du DAM hébergé, les dossiers et métadonnées gérés, la diffusion publique via tlcdn.com, les simulations et manifestes de migration, les rôles de la bibliothèque multimédia, les sélecteurs de ressources et les intégrations aux CMS et aux éditeurs nécessitent un plan de migration distinct et sortent du cadre de ce flux de travail.

Correspondances de migration

Décisions avant la migration. Ce tableau met en correspondance des tâches, pas des API interchangeables. Recréez dans votre backend les règles de validation, de nommage et d’accès des préréglages. La sélection automatique du format et de la qualité⁠ et le recadrage fondé sur la gravité⁠ de Cloudinary nécessitent une comparaison des résultats ; le recadrage WebP fixe ci-dessous ne reproduit pas le comportement de f_auto, q_auto ou g_auto. Inventoriez séparément les transformations nommées, les superpositions, les effets d’IA et les modules complémentaires, puis décidez lesquels recréer, conserver ou exclure. Ce guide ne fournit pas d’équivalents pour ces effets.

Commencer par le flux de travail, pas par l’URL

Les URL de transformation de Cloudinary⁠ encodent les paramètres de traitement dans le chemin de diffusion. Dans Transloadit, placez les Steps de traitement requis dans un Template et appelez-le depuis votre application. Conservez les définitions des Templates sous contrôle de version avec le code de votre application et les ressources des tests de régression.

Par exemple, ce Template produit un recadrage WebP fixe de 1600 × 900 et optimise ce résultat. Comparez son apparence et la taille du fichier à la variante Cloudinary que vous remplacez :

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "hero": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 1600,
      "height": 900,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized": {
      "use": "hero",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": "optimized",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "media/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Remplacez YOUR_AWS_CREDENTIALS par un ensemble enregistré d’Informations d’identification pour les services tiers. Cet exemple suppose que votre CDN diffuse les fichiers depuis la racine du bucket et dispose de l’autorisation de lire ses objets ; url_prefix modifie uniquement les URL renvoyées, pas la configuration du CDN ni les autorisations d’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 du CDN à l’origine.

Votre backend crée une requête d’Assembly signée avec le template_id enregistré et une notify_url pour les Assembly Notifications. Vérifiez la signature de la notification et exigez ASSEMBLY_COMPLETED avant de modifier les enregistrements de l’application. Dans cet exemple, lisez les fichiers exportés dans results.optimized : le Step de stockage met à jour les URL du Step qui produit les fichiers. Ne conservez durablement que les résultats avec is_temp_url: false ; les URL temporaires de Transloadit expirent après 24 heures et ne sont pas des URL de diffusion. Consultez Enregistrer les fichiers de résultat.

Remplacer les URL d’images dynamiques

Si votre application repose sur des URL de transformation dynamiques, deux voies de migration sont courantes :

1. Utiliser un Template par famille de transformations, puis déclencher une Assembly lorsque la ressource est créée ou modifiée.
2. Utiliser le Smart CDN avec des URL signées pour les transformations à la demande qui doivent être mises en cache en périphérie du réseau.

Pour les pages à fort trafic, privilégiez la génération et le stockage préalables des variantes canoniques. Pour les très grandes bibliothèques de ressources dont les accès suivent une répartition à longue traîne, le Smart CDN peut réduire le travail de prétraitement.

Le Smart CDN nécessite un Template distinct composé uniquement de Robots compatibles, avec une branche de réponse se terminant par /file/serve. Par exemple, importez une image, redimensionnez-la et diffusez le résultat. /video/encode et /video/adaptive ne sont pas compatibles avec le Smart CDN ; générez les URL signées du Smart CDN dans votre backend.

Remplacer les références de diffusion. Conservez une correspondance entre chaque URL d’origine ou de variante utilisée et sa destination vérifiée, y compris les références dans les enregistrements de base de données, srcset, le CSS, les modèles d’e-mails et le contenu du CMS. Les URL de diffusion de Cloudinary⁠ encodent le nom du cloud, les types de ressource et de diffusion et l’identifiant public, avec des composants facultatifs de transformation et de version ; modifier uniquement le nom d’hôte ne suffit pas à convertir ces chemins. Remplacez les références res.cloudinary.com intégrées à votre application. Placez les redirections sur une route d’application ou un nom d’hôte multimédia que vous contrôlez, préservez les autorisations d’accès aux médias à accès restreint et maintenez le service source tant que les anciens liens en ont encore besoin.

Importer les ressources existantes de Cloudinary

Établir d’abord l’inventaire. Utilisez l’API d’administration⁠ de Cloudinary pour répertorier les types de ressource et de diffusion utilisés par votre compte, suivez next_cursor sur toutes les pages et demandez explicitement tags, context et metadata. Si vous limitez la réponse avec fields, incluez-y aussi ces champs. Respectez la limite de requêtes de l’API d’administration du compte. Consignez asset_id, public_id, le type, la version, l’URL source, la taille en octets et la correspondance de destination dans votre propre manifeste. Incluez les enregistrements de ressources présents uniquement dans l’application, que l’inventaire de Cloudinary ne peut pas fournir.

Préserver l’organisation séparément. Télécharger un fichier ne transfère pas son catalogue de ressources :

Recréez les relations du catalogue et les autorisations dans votre application. Le Template d’importation ci-dessous copie le fichier binaire sélectionné et une miniature ; il ne crée pas de catalogue DAM hébergé et ne migre ni les métadonnées, ni les collections, ni l’historique des versions. Le composant de version d’une URL de diffusion⁠ contrôle l’actualisation du cache du CDN ; utilisez le mécanisme de téléchargement des sauvegardes pour exporter les fichiers antérieurs conservés.

Si le média sélectionné est disponible via une URL HTTPS autorisée, utilisez 🤖/http/import plutôt que de le téléverser à nouveau :

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.cloudinary_url}"
    },
    "thumbnail": {
      "use": "imported",
      "robot": "/image/resize",
      "width": 400,
      "height": 400,
      "resize_strategy": "fillcrop",
      "result": true
    },
    "exported": {
      "use": ["imported", "thumbnail"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "cloudinary-import/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

Transmettez une URL source autorisée dans le champ d’Assembly cloudinary_url, sélectionnée par votre backend dans votre inventaire de ressources. Une URL Cloudinary transformée⁠ importe la variante correspondante ; sélectionnez délibérément l’original lorsque vous en avez besoin. Pour les ressources à accès restreint⁠, générez le téléchargement autorisé approprié dans votre backend et prévoyez suffisamment de temps pour l’importation. Conservez l’ancien identifiant et l’ancienne URL de la ressource jusqu’à ce que l’exportation terminée soit accessible via le chemin de diffusion prévu et que ses dimensions et sa qualité répondent à vos exigences. Ce Template d’importation renvoie les fichiers exportés sous results.imported et results.thumbnail. Un objet S3 privé nécessite toujours un téléchargement autorisé ou votre CDN configuré.

Widget de téléversement et automatisation. Remplacez le widget de téléversement de Cloudinary⁠ par Uppy et suivez le guide d’intégration avec signature côté serveur⁠. Mettez à jour les fonctions de rappel pour conserver durablement les résultats vérifiés des Assemblies. Un sélecteur de la bibliothèque multimédia de Cloudinary⁠ sélectionne des ressources DAM existantes ; remplacer ce sélecteur et son intégration au CMS nécessite un navigateur de ressources et un catalogue distincts, au-delà du remplacement de l’interface de téléversement.

Les notifications⁠ de Cloudinary couvrent plusieurs événements liés aux ressources, notamment des notifications distinctes de transformation anticipée. Faites correspondre la fin du traitement aux Assembly Notifications et gérez les événements de renommage, de suppression, de catalogue et de modération dans votre application. Réécrivez la vérification des signatures pour le format de notification de Transloadit, n’accusez réception qu’après un traitement durable et dédupliquez les mises à jour par identifiant d’Assembly. Testez les échecs et la gestion des nouvelles tentatives à l’aide de la documentation de l’API des webhooks et consignez les importations échouées dans le manifeste avant de les réexécuter.

Décisions de sécurité. Cloudinary prend en charge les téléversements signés et non signés⁠ ; le mécanisme de signature n’est pas interchangeable avec l’authentification de Transloadit. Autorisez les utilisateurs et ne signez que les Templates et les champs autorisés dans votre backend. Traitez séparément l’accès aux fichiers diffusés : le type de diffusion privée de Cloudinary⁠ protège les originaux, mais autorise les ressources dérivées par défaut, tandis que son type authentifié protège les deux. Recréez la politique prévue dans votre bucket et votre CDN ; un téléversement signé ou une URL de traitement signée ne constitue pas une ACL pour un objet exporté.

Si vous utilisez le module complémentaire de détection des logiciels malveillants Perception Point⁠ de Cloudinary, prévoyez une analyse de sécurité et une mise en quarantaine avant la diffusion publique dans le pipeline de remplacement. Aucun des exemples présentés ici n’active l’analyse antimalware ni la modération de contenu. Ce guide ne configure ni système de quarantaine, ni politique de modération de contenu, ni DRM, ni mise en œuvre complète du contrôle d’accès.

Agents et exécution reproductible. Les outils pour agents et serveurs MCP⁠ de Cloudinary exposent aux clients d’IA des opérations sur les ressources, les transformations, l’analyse et l’environnement. Inventoriez tous les agents qui appellent ces outils comme des dépendances de l’application. Faites proposer par les agents des Instructions de Template versionnées, puis examinez et exécutez le flux de travail enregistré avec des entrées et des variantes de sortie limitées. Conservez les identifiants d’Assembly, les motifs d’échec et les correspondances de destination pour l’assistance et la réexécution ; ajouter un agent ne migre pas le catalogue de ressources et ne garantit pas des pixels identiques. Ce guide ne porte pas les outils MCP individuels ni les intégrations d’agents.

Liste de contrôle

Estimation de l’effort. Pour la planification, prévoyez plusieurs jours d’ingénierie pour un parcours de téléversement, quelques transformations fixes et la diffusion publique, puis du temps pour migrer les ressources existantes. Une application fortement axée sur le DAM, avec un historique, des effets personnalisés, une diffusion à accès restreint et des intégrations aux CMS, peut nécessiter des semaines ou davantage. Ce sont des estimations, pas des mesures comparatives de migration. Mesurez un lot représentatif pour estimer la durée du transfert et le coût du traitement ; incluez les frais de téléchargement depuis la source, les coûts du stockage/CDN de destination et une période de coexistence. Le remplacement d’un DAM hébergé nécessite une estimation distincte.

1. Inventorier les ressources, les métadonnées, les transformations utilisées, les intégrations de widgets et de sélecteurs, ainsi que les règles d’autorisation.
2. Créer des Templates versionnés et des ensembles d’informations d’identification pour les services tiers ; comparer des résultats représentatifs.
3. Définir des tailles de lot limitées, le niveau de concurrence, des limites de nouvelles tentatives et un budget de migration. Confirmez avec votre équipe la région d’exécution, la région de stockage, la conservation et les exigences de conformité avant de déplacer des données.
4. Exécuter un petit pilote ; vérifier la fin du traitement, les URL durables, les dimensions, les tailles de fichier, les correspondances de métadonnées, l’accès privé et la récupération après erreur.
5. Basculer les nouveaux téléversements à l’aide d’un indicateur de fonctionnalité et migrer les ressources existantes par lots de taille limitée. Consignez chaque réussite et chaque échec afin que les nouvelles tentatives ne créent pas de ressources en double non suivies.
6. Remplacer les références de diffusion ou ajouter des redirections sur une infrastructure que vous contrôlez ; tester des pages réelles, les liens des e-mails et le contenu mis en cache.
7. Conserver les identifiants Cloudinary et le chemin de diffusion pour permettre un retour en arrière jusqu’à la fin de la période de coexistence convenue et la concordance de l’inventaire. Ne mettez l’ancien service hors service qu’après avoir résolu les ressources manquantes et les anciens liens.