Cloudinary から Transloadit への移行
Cloudinary はアップロードプリセット、変換 URL、アセットライブラリーをサポートしています。Transloadit では、処理の中心となるのが Assembly Instructionsです。アップロード、インポート、変換、最適化、保存、配信を行う Robot を実行する、明示的なワークフローです。
Transloadit は、Transloadit Storageでファイルのホスティングを提供しています(現在ベータ版)。Transloadit Storage を使用する場合、独自のストレージバケットは任意です。File Library(プレビュー版)では、Transloadit Storage 内のファイルの閲覧、整理、プレビュー、ダウンロードを行うデジタルアセット管理機能を提供しています。File Library のアクセスは Workspace ごとに有効になります。利用可否についてお問い合わせください。
このガイドでは、独自のストレージを使用する方法を紹介します。アップロードと処理を
Template に移行し、アセットを自分のバケットにエクスポートします。アプリケーションのアセットカタログは、そのストレージと併せて管理してください。既存の DAM フォルダーとメタデータの移行、本番環境の配信先を
tlcdn.com 上の Smart CDN URL に変更する作業、承認ワークフロー、権利管理、アセットピッカー、CMS 連携の置き換えには、個別の移行計画が必要です。File Library が利用できても、Cloudinary のすべての DAM 機能と一対一で互換性があるわけではありません。
移行の対応表
| Cloudinary の概念 | Transloadit への移行方法 |
|---|---|
| アップロードプリセット | 保存済みの Templateを template_id で参照 |
| 変換 URL | Assembly リクエスト、または Smart CDN(対応する Robot と最後の /file/serve Step を使用) |
| 事前変換 | オンデマンドではなくアップロード時に Template の Step を実行 |
| 画像のリサイズとクロップ | 🤖/image/resize。代表的なアセットでクロップ結果を比較 |
| 画像の最適化 | 🤖/image/optimize。形式と品質を意図的に選択 |
| 動画のトランスコード | 🤖/video/encode |
| アダプティブ動画 | 🤖/video/adaptive または 🤖/video/ondemand |
| アセットの保存 | 🤖/s3/store または別のエクスポート用 Robot と、独自のアセットカタログ |
| 配信 URL | 独自のストレージや CDN の URL、または最後に 🤖/file/serve の Step を置く Smart CDN |
| アップロードウィジェット | Transloadit プラグインを組み込んだ Uppy。コールバックとサーバー側の署名処理を更新 |
| Webhook | Assembly Notification。イベント処理と署名検証を書き換え |
移行前の判断事項。 この表はタスクの対応を示すもので、API の互換性を示すものではありません。プリセットの検証、命名、アクセスのルールをバックエンドで再実装してください。Cloudinary の形式と品質の自動選択や注目領域に基づくクロップについては、出力の比較が必要です。以下の固定 WebP クロップでは、f_auto、q_auto、g_auto の動作は再現されません。名前付き変換、オーバーレイ、AI エフェクト、アドオンを別途洗い出し、再実装するもの、維持するもの、除外するものを決めてください。このガイドでは、これらのエフェクトに相当する実装は提供していません。
URL ではなくワークフローから着手
Cloudinary の変換 URLでは、配信パスに処理パラメーターを埋め込みます。Transloadit では、必要な処理 Step を Template に記述し、アプリから呼び出します。Template の定義は、アプリケーションコードや回帰テスト用アセットと併せてバージョン管理してください。
たとえば、この Template は 1600 × 900 固定の WebP クロップを生成し、その出力を最適化します。置き換え対象の Cloudinary の派生画像と、見た目やファイルサイズを比較してください。
{
"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"
}
}
}
YOUR_AWS_CREDENTIALS を保存済みのサードパーティ認証情報に置き換えてください。この例では、CDN がバケットのルートを配信し、そのオブジェクトの読み取り権限を持つことを前提としています。url_prefix は返される URL のみを変更し、CDN の設定やアクセス権限は変更しません。acl: "bucket-default" はオブジェクト ACL を送信しません。バケットポリシーと CDN のオリジンアクセスでアクセスを設定してください。
バックエンドで、保存済みの template_id と、notify_url(Assembly Notification用)を指定した署名付き Assembly リクエストを作成します。通知の署名を検証し、ASSEMBLY_COMPLETED を必須条件としてから、アプリケーションのレコードを切り替えてください。この例では、エクスポート済みファイルを
results.optimized から読み取ります。ストレージの Step が、ファイルを生成した Step の URL を更新するためです。is_temp_url: false を持つ結果のみを永続化してください。Transloadit の一時 URL は 24 時間で期限切れになり、配信用 URL としては使えません。変換結果の保存を参照してください。
動的画像 URL の置き換え
アプリが動的変換 URL に依存している場合、一般的な移行方法は次の 2 通りです。
- 変換の種類ごとに Template を用意し、アセットの作成時または変更時に Assembly を実行します。
- エッジでキャッシュすべきオンデマンド変換には、Smart CDN と署名付き URL を使用します。
トラフィックの多いページでは、標準となるバリエーションをあらかじめ生成して保存する方法を推奨します。アクセスがロングテール型に分布する非常に大規模なアセットライブラリーでは、Smart CDN で事前処理の負担を減らせます。
Smart CDN には、対応する Robot のみで構成し、レスポンス分岐が
/file/serve で終わる専用の Template が必要です。たとえば、画像をインポートしてリサイズし、その出力を配信します。/video/encode と /video/adaptive は Smart CDN に対応していません。署名付き Smart CDN URL はバックエンドで生成してください。
配信先参照の置き換え。 元ファイルと使用中の各派生ファイルの URL について、検証済みの移行先との対応を管理してください。データベースのレコード、srcset、CSS、メールテンプレート、CMS コンテンツ内の参照も対象です。Cloudinary の配信 URLには、クラウド名、リソース種別、配信種別、パブリック ID が含まれ、変換やバージョンの要素も任意で含まれます。ホスト名だけを変更しても、これらのパスは変換できません。アプリケーションに埋め込まれた
res.cloudinary.com の参照を置き換えてください。リダイレクトは管理下のアプリケーションルートやメディア用ホスト名に設定し、制限付きメディアの認可を維持してください。古いリンクが移行元サービスを必要とする間は、そのサービスも維持してください。
既存の Cloudinary アセットのインポート
最初に一覧を作成。 Cloudinary の Admin API を使い、アカウントで使用しているリソース種別と配信種別を列挙してください。next_cursor をたどってすべてのページを取得し、tags、context、metadata を明示的にリクエストしてください。fields でレスポンスを制限する場合は、そこにもこれらのフィールドを含めます。アカウントの Admin API レート制限を守ってください。asset_id、public_id、種別、バージョン、ソース URL、バイトサイズ、移行先との対応を独自のマニフェストに記録してください。Cloudinary の一覧では取得できない、アプリケーション側のみのアセットレコードも含めます。
整理情報は別途保持。 ファイルをダウンロードしても、アセットカタログは移行されません。
| 情報 | 保持方法の判断 |
|---|---|
| タグ、コンテキストメタデータ、構造化メタデータ | 値をデータベースまたはサイドカーファイルに保存し、構造化フィールドの定義、型、検証ルールを保持 |
| フォルダーと表示名 | 動的フォルダーモードでは、asset_folder、表示名、パブリック ID を個別に保持。フォルダーを移動しても配信 URL は不変。固定フォルダーモードでは、パブリック ID にフォルダーパスを格納 |
| コレクション | 手動で選択したメンバー構成または動的コレクションのフィルタールールと、共有に関する判断を保持。ストレージパスだけでは表現不可 |
| バージョンとバックアップ | 現在のファイルのみをコピーするか、保持された履歴もコピーするかを判断。バックアップ済みバージョンを列挙し、選択したバージョンを個別にダウンロード。バックアップを有効にしたことがなければ、過去のファイルをバックアップから復元することは不可 |
カタログの関連付けと権限は、アプリケーションで再構築してください。以下のインポート用 Template は、選択したバイナリとサムネイルをコピーします。ホスティング型 DAM カタログの作成や、メタデータ、コレクション、バージョン履歴の移行は行いません。配信 URL のバージョン要素は、CDN キャッシュの更新を制御します。保持されている過去のファイルのエクスポートには、バックアップのダウンロード機能を使用してください。
選択したメディアを認可済みの HTTPS URL で取得できる場合は、再アップロードする代わりに 🤖/http/import を使用します。
{
"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"
}
}
}
アセット一覧からバックエンドで選択した認可済みのソース URL を、Assembly のフィールド
cloudinary_url として渡してください。変換済みの Cloudinary URLを指定すると、その派生ファイルがインポートされます。元ファイルが必要な場合は、意図的に元ファイルを選択してください。制限付きアセットでは、適切に認可されたダウンロードをバックエンドで生成し、インポートに十分な時間を確保してください。エクスポートが完了し、想定する配信経路でアクセスでき、寸法と品質が要件を満たすまでは、古いアセット ID と URL を保持してください。このインポート用 Template は、results.imported と results.thumbnail の下にエクスポート済みファイルを返します。非公開の S3 オブジェクトには、引き続き認可されたダウンロードか、設定済みの CDN が必要です。
アップロードウィジェットと自動化。Cloudinary Upload ウィジェットを Uppy に置き換え、サーバー署名による連携ガイドに従ってください。検証済みの Assembly の結果を永続化するよう、コールバックを更新します。Cloudinary Media Library ピッカーは、既存の DAM アセットを選択します。このピッカーと CMS 連携を置き換えるには、アップロード UI の置き換えに加えて、別途アセットブラウザーとカタログが必要です。
Cloudinary の通知は、事前変換の個別通知など、複数のアセットイベントを対象としています。処理完了を Assembly Notification に対応付け、名前変更、削除、カタログ、モデレーションのイベントはアプリケーションで処理してください。Transloadit の通知形式に合わせて署名検証を書き換え、処理が永続的に反映された後にのみ受信確認を返し、Assembly ID で更新の重複を排除してください。Webhook API ドキュメントを使って失敗時と再試行時の処理をテストし、失敗したインポートは再実行する前にマニフェストに記録してください。
セキュリティに関する判断。 Cloudinary は署名付きアップロードと署名なしアップロードをサポートしています。その署名方式は、Transloadit の認証とは互換性がありません。バックエンドでユーザーを認可し、許可された Template とフィールドのみに署名してください。配信アクセスは別途扱います。Cloudinary の非公開配信タイプは元ファイルを保護しますが、派生アセットはデフォルトでアクセス可能です。一方、認証必須タイプは両方を保護します。意図したポリシーをバケットと CDN に再実装してください。署名付きアップロードや署名付き処理 URL は、エクスポートされたオブジェクトの ACL ではありません。
Cloudinary の Perception Point マルウェア検出アドオンを使用している場合は、移行先のパイプラインでも、公開配信前にマルウェアスキャンと隔離を行う計画を立ててください。このガイドのどちらの例でも、マルウェアスキャンやコンテンツモデレーションは有効になりません。このガイドでは、隔離システム、コンテンツモデレーションポリシー、DRM、アクセス制御の完全な実装は設定しません。
エージェントと再現可能な実行。 Cloudinary のエージェントツールと MCP サーバーは、アセット、変換、分析、環境に関する操作を AI クライアントに公開します。これらのツールを呼び出すエージェントは、アプリケーションの依存関係として洗い出してください。エージェントにはバージョン管理された Template の処理設定を提案させ、レビューしたうえで、入力と出力バリエーションを制限して保存済みワークフローを実行してください。サポートや再実行のため、Assembly ID、失敗理由、移行先との対応を保持します。エージェントを追加しても、アセットカタログは移行されず、ピクセル単位での一致も保証されません。このガイドでは、個々の MCP ツールやエージェント連携の移植は扱いません。
チェックリスト
工数の見積もり。 計画上の目安として、アップロード経路が 1 つ、固定変換が数種類、公開配信という構成で、エンジニアリング作業に数日、その後に既存データの移行時間を確保してください。履歴、カスタムエフェクト、制限付き配信、CMS 連携があり、DAM への依存度が高いアプリケーションでは、数週間以上かかる場合があります。これは見積もりであり、移行の実測ベンチマークではありません。代表的なバッチを測定し、転送時間と処理コストを見積もってください。移行元のダウンロード料金、移行先のストレージと CDN のコスト、併用期間も含めます。ホスティング型 DAM の置き換えには、別途見積もりが必要です。
- アセット、メタデータ、使用中の変換、ウィジェットとピッカーの連携、認可ルールを洗い出します。
- バージョン管理された Template とサードパーティーの認証情報を作成し、代表的な出力を比較します。
- バッチサイズ、同時実行数、再試行回数の上限と、移行予算を定義します。データを移動する前に、実行リージョン、ストレージリージョン、保持、コンプライアンスの要件をチームで確認します。
- 小規模なパイロット移行を実施し、完了状態、永続的な URL、寸法、ファイルサイズ、メタデータの対応、非公開アクセス、エラーからの復旧を検証します。
- フィーチャーフラグを使って新規アップロードを切り替え、既存アセットを上限付きのバッチで移行します。再試行で追跡されない重複アセットが生じないよう、すべての成功と失敗を記録します。
- 配信先参照を置き換えるか、管理下のインフラにリダイレクトを追加し、実際のページ、メールのリンク、キャッシュされたコンテンツをテストします。
- 合意した併用期間が終了し、一覧との照合が完了するまでは、ロールバック用に Cloudinary の識別子と配信経路を保持します。不足しているアセットと古いリンクの問題を解消してから廃止します。