Migration von Cloudinary zu Transloadit

Cloudinary unterstützt Upload-Voreinstellungen⁠, Transformations-URLs⁠ und eine Asset-Bibliothek⁠. Transloadit zentriert die Verarbeitung um Assembly Instructions: explizite Workflows, die Robots zum Hochladen, Importieren, Transformieren, Optimieren, Speichern und Ausliefern von Dateien ausführen.

Transloadit bietet gehostete Dateien über Transloadit Storage EN (English) (derzeit in der Betaphase). Wenn Sie Transloadit Storage nutzen, ist ein eigener Storage-Bucket optional. Die File Library (Vorschauversion) bietet Digital Asset Management, mit dem Sie Dateien in Transloadit Storage visuell durchstöbern, organisieren, in der Vorschau ansehen und herunterladen können. Der Zugriff auf die File Library wird pro Workspace freigeschaltet; fragen Sie uns nach der Verfügbarkeit dieser Funktion.

Diese Anleitung zeigt den Weg mit eigenem Speicher: Sie migriert Uploads und Verarbeitung in Templates und exportiert Assets in Ihren Bucket. Führen Sie den Asset-Katalog Ihrer Anwendung neben diesem Speicher weiter. Die Migration vorhandener DAM-Ordner und Metadaten, die Umstellung der produktiven Auslieferung auf Smart-CDN-URLs unter tlcdn.com sowie der Ersatz von Freigabe-Workflows, Rechteverwaltung, Asset-Pickern oder CMS-Integrationen erfordern einen eigenen Migrationsplan. Dass die File Library verfügbar ist, bedeutet nicht, dass sie jede Cloudinary-DAM-Funktion eins zu eins abdeckt.

Migrationsübersicht

Entscheidungen vor der Migration. Diese Tabelle ordnet Aufgaben zu, keine austauschbaren APIs. Bilden Sie Voreinstellungsvalidierung, Benennung und Zugriffsregeln in Ihrem Backend nach. Die automatische Format- und Qualitätsauswahl⁠ und der schwerpunktbasierte Zuschnitt⁠ von Cloudinary erfordern Ausgabevergleiche; der feste WebP-Zuschnitt unten reproduziert das Verhalten von f_auto, q_auto oder g_auto nicht. Erfassen Sie benannte Transformationen, Overlays, KI-Effekte und Add-ons separat und entscheiden Sie, welche Sie neu aufbauen, beibehalten oder weglassen. Diese Anleitung bietet keine Entsprechungen für diese Effekte.

Mit dem Workflow beginnen, nicht mit der URL

Cloudinary-Transformations-URLs⁠ kodieren Verarbeitungsparameter im Auslieferungspfad. Bei Transloadit legen Sie die benötigten Verarbeitungs-Steps in ein Template und rufen es aus Ihrer App auf. Pflegen Sie Template-Definitionen in der Versionskontrolle neben Ihrem Anwendungscode und Ihren Regressions-Assets.

Dieses Template erzeugt beispielsweise einen festen 1600 × 900 WebP-Zuschnitt und optimiert diese Ausgabe. Vergleichen Sie deren Erscheinungsbild und Dateigröße mit der Cloudinary-Variante, die Sie ersetzen:

{
  "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"
    }
  }
}

Ersetzen Sie YOUR_AWS_CREDENTIALS durch gespeicherte Zugangsdaten von Drittanbietern. Dieses Beispiel setzt voraus, dass Ihr CDN das Stammverzeichnis des Buckets ausliefert und Leserechte für dessen Objekte hat; url_prefix ändert nur zurückgegebene URLs, nicht die CDN-Konfiguration oder Zugriffsberechtigungen. acl: "bucket-default" sendet keine Objekt-ACL; konfigurieren Sie den Zugriff über Ihre Bucket-Richtlinie und den CDN-Origin-Access.

Ihr Backend erstellt eine signierte Assembly-Anfrage mit dem gespeicherten template_id und einem notify_url für Assembly Notifications. Prüfen Sie die Signatur der Notification und verlangen Sie ASSEMBLY_COMPLETED, bevor Sie Anwendungsdatensätze umstellen. In diesem Beispiel lesen Sie die exportierten Dateien aus results.optimized: Der Speicher-Step aktualisiert die URLs des erzeugenden Steps. Speichern Sie dauerhaft nur Ergebnisse mit is_temp_url: false; temporäre Transloadit-URLs laufen nach 24 Stunden ab und sind keine Auslieferungs-URLs. Siehe Ergebnisdateien speichern.

Dynamische Bild-URLs ersetzen

Wenn Ihre App auf dynamische Transformations-URLs angewiesen ist, gibt es zwei gängige Migrationswege:

1. Ein Template pro Transformationsfamilie verwenden und eine Assembly auslösen, wenn das Asset erstellt oder geändert wird.
2. Smart CDN mit signierten URLs für On-Demand-Transformationen verwenden, die am Edge zwischengespeichert werden sollen.

Für stark frequentierte Seiten sollten Sie bevorzugt kanonische Varianten im Voraus erzeugen und speichern. Bei sehr großen Asset-Bibliotheken mit selten abgerufenen Inhalten kann Smart CDN den Vorverarbeitungsaufwand reduzieren.

Smart CDN benötigt ein separates Template, das nur aus kompatiblen Robots besteht, mit einem Antwortzweig, der mit /file/serve endet. Importieren Sie beispielsweise ein Bild, ändern Sie seine Größe und liefern Sie diese Ausgabe aus. /video/encode und /video/adaptive sind nicht Smart-CDN-kompatibel; erzeugen Sie signierte Smart-CDN-URLs auf Ihrem Backend.

Auslieferungsreferenzen ersetzen. Führen Sie eine Zuordnung von jeder ursprünglichen und verwendeten Varianten-URL zu ihrem verifizierten Ziel, einschließlich Referenzen in Datenbankeinträgen, srcset, CSS, E-Mail-Vorlagen und CMS-Inhalten. Cloudinary-Auslieferungs-URLs⁠ kodieren den Cloud-Namen, Ressourcen- und Auslieferungstyp sowie die öffentliche ID, mit optionalen Transformations- und Versionskomponenten; eine reine Änderung des Hostnamens kann diese Pfade nicht übersetzen. Ersetzen Sie eingebettete res.cloudinary.com-Referenzen in Ihrer Anwendung. Richten Sie Weiterleitungen auf einer Anwendungsroute oder einem Media-Hostnamen ein, den Sie kontrollieren, bewahren Sie die Autorisierung für eingeschränkte Medien, und behalten Sie den Quelldienst bei, solange alte Links ihn noch benötigen.

Vorhandene Cloudinary-Assets importieren

Erstellen Sie zuerst das Inventar. Verwenden Sie die Admin-API⁠ von Cloudinary, um die in Ihrem Account verwendeten Ressourcen- und Auslieferungstypen aufzulisten, folgen Sie next_cursor über alle Seiten hinweg und fordern Sie tags, context und metadata explizit an. Wenn Sie die Antwort mit fields einschränken, schließen Sie diese Felder dort ebenfalls ein. Beachten Sie das Admin-API-Ratenlimit des Accounts. Erfassen Sie asset_id, public_id, Typ, Version, Quell-URL, Byte-Größe und die Zielzuordnung in Ihrem eigenen Manifest. Fügen Sie auch anwendungsinterne Asset-Datensätze hinzu, die das Cloudinary-Inventar nicht liefern kann.

Organisation separat bewahren. Das Herunterladen einer Datei überträgt nicht deren Asset-Katalog:

Bauen Sie Katalogbeziehungen und Berechtigungen in Ihrer Anwendung neu auf. Das Import-Template unten kopiert das ausgewählte Binärobjekt und ein Thumbnail; es erstellt keinen Hosted-DAM-Katalog und migriert keine Metadaten, Sammlungen oder Versionsverläufe. Die Versionskomponente einer Auslieferungs-URL⁠ steuert die CDN-Cache-Aktualisierung; verwenden Sie den Backup-Download-Mechanismus, um bewahrte frühere Dateien zu exportieren.

Wenn das ausgewählte Medium über eine autorisierte HTTPS-URL verfügbar ist, verwenden Sie 🤖/http/import statt es erneut hochzuladen:

{
  "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"
    }
  }
}

Übergeben Sie eine autorisierte Quell-URL als Assembly-Feld cloudinary_url, ausgewählt von Ihrem Backend aus Ihrem Asset-Inventar. Eine transformierte Cloudinary-URL⁠ importiert diese Variante; wählen Sie das Original bewusst, wenn Sie es benötigen. Für eingeschränkte Assets⁠ erzeugen Sie den passenden autorisierten Download auf Ihrem Backend und lassen Sie genug Zeit für den Import. Bewahren Sie die alte Asset-ID und URL, bis der abgeschlossene Export über Ihren vorgesehenen Auslieferungsweg erreichbar ist und dessen Abmessungen und Qualität Ihren Anforderungen entsprechen. Dieses Import-Template gibt exportierte Dateien unter results.imported und results.thumbnail zurück. Ein privates S3-Objekt benötigt weiterhin einen autorisierten Download oder Ihr konfiguriertes CDN.

Upload-Widget und Automatisierung. Ersetzen Sie das Cloudinary-Upload-Widget⁠ durch Uppy und folgen Sie der Anleitung zur serversignierten Integration⁠. Aktualisieren Sie Callbacks, um verifizierte Assembly-Ergebnisse dauerhaft zu speichern. Ein Cloudinary-Media-Library-Picker⁠ wählt vorhandene DAM-Assets aus; das Ersetzen dieses Pickers und seiner CMS-Integration erfordert einen separaten Asset-Browser und -Katalog, über den Ersatz der Upload-UI hinaus.

Die Benachrichtigungen⁠ von Cloudinary decken mehrere Asset-Ereignisse ab, einschließlich separater Benachrichtigungen für Eager-Transformationen. Bilden Sie den Abschluss der Verarbeitung auf Assembly Notifications ab und behandeln Sie Umbenennungs-, Löschungs-, Katalog- und Moderationsereignisse in Ihrer Anwendung. Schreiben Sie die Signaturprüfung für das Notification-Format von Transloadit neu, bestätigen Sie erst nach dauerhafter Verarbeitung und deduplizieren Sie Aktualisierungen anhand der Assembly-ID. Testen Sie Fehler und Wiederholungsbehandlung anhand der Webhooks-API-Dokumentation und erfassen Sie fehlgeschlagene Importe im Manifest, bevor Sie sie erneut ausführen.

Sicherheitsentscheidungen. Cloudinary unterstützt signierte und unsignierte Uploads⁠; das Signaturschema ist nicht mit der Transloadit-Authentifizierung austauschbar. Autorisieren Sie Nutzer und signieren Sie auf Ihrem Backend nur zulässige Templates und Felder. Behandeln Sie den Auslieferungszugriff separat: Der private Auslieferungstyp⁠ von Cloudinary schützt Originale, erlaubt aber standardmäßig abgeleitete Assets, während der authentifizierte Typ beide schützt. Bilden Sie die vorgesehene Richtlinie in Ihrem Bucket und CDN nach; ein signierter Upload oder eine signierte Verarbeitungs-URL ist keine ACL für ein exportiertes Objekt.

Wenn Sie das Perception-Point-Malware-Erkennungs-Add-on⁠ von Cloudinary verwenden, planen Sie Scanning und Quarantäne vor der öffentlichen Auslieferung in der Ersatzpipeline ein. Keines der hier gezeigten Beispiele aktiviert einen Malware-Scan oder eine Inhaltsmoderation. Diese Anleitung konfiguriert kein Quarantänesystem, keine Inhaltsmoderationsrichtlinie, kein DRM und keine vollständige Zugriffskontrollimplementierung.

Agenten und wiederholbare Ausführung. Die Agent-Tools und MCP-Server⁠ von Cloudinary stellen KI-Clients Asset-, Transformations-, Analyse- und Umgebungsoperationen zur Verfügung. Erfassen Sie alle Agenten, die diese Tools aufrufen, als Anwendungsabhängigkeiten. Lassen Sie Agenten versionierte Template Instructions vorschlagen, und überprüfen und führen Sie dann den gespeicherten Workflow mit begrenzten Eingaben und Ausgabevarianten aus. Bewahren Sie Assembly-IDs, Fehlergründe und Zielzuordnungen für Support und Wiederholung auf; ein Agent allein migriert nicht den Asset-Katalog und garantiert keine identischen Pixel. Diese Anleitung portiert keine einzelnen MCP-Tools oder Agenten-Integrationen.

Checkliste

Aufwandsschätzung. Als Planungsrichtwert sollten Sie mehrere Arbeitstage für einen Upload-Pfad, einige feste Transformationen und die öffentliche Auslieferung einplanen, gefolgt von Zeit für die Nacharbeitung. Eine DAM-intensive Anwendung mit Verlauf, benutzerdefinierten Effekten, eingeschränkter Auslieferung und CMS-Integrationen kann Wochen oder mehr erfordern. Dies sind Schätzungen, keine gemessenen Migrationsbenchmarks. Messen Sie einen repräsentativen Stapel, um Übertragungszeit und Verarbeitungskosten zu schätzen; berücksichtigen Sie Kosten für den Quell-Download, Ziel-Speicher-/CDN-Kosten und einen Überlappungszeitraum. Für einen Hosted-DAM-Ersatz benötigen Sie eine separate Schätzung.

1. Assets, Metadaten, verwendete Transformationen, Widget-/Picker-Integrationen und Autorisierungsregeln erfassen.
2. Versionierte Templates und Zugangsdaten von Drittanbietern erstellen; repräsentative Ausgaben vergleichen.
3. Begrenzte Batch-Größen, Parallelität, Wiederholungslimits und ein Migrationsbudget festlegen. Ausführungsregion, Speicherregion, Aufbewahrung und Compliance-Anforderungen mit Ihrem Team bestätigen, bevor Daten verschoben werden.
4. Einen kleinen Pilotlauf durchführen; Abschluss, dauerhafte URLs, Abmessungen, Dateigrößen, Metadatenzuordnungen, privaten Zugriff und Fehlerbehebung prüfen.
5. Neue Uploads hinter einem Feature-Flag umstellen und vorhandene Assets in begrenzten Batches nacharbeiten. Jeden Erfolg und jeden Fehler erfassen, damit Wiederholungen keine nicht erfassten doppelten Assets erzeugen.
6. Auslieferungsreferenzen ersetzen oder Weiterleitungen auf von Ihnen kontrollierter Infrastruktur einrichten; reale Seiten, E-Mail-Links und zwischengespeicherte Inhalte testen.
7. Die Cloudinary-IDs und den Auslieferungspfad für ein Rollback behalten, bis der vereinbarte Überlappungszeitraum endet und das Inventar abgeglichen ist. Erst nach Behebung fehlender Assets und veralteter Links stilllegen.