Uploadcare から Transloadit への移行
Uploadcare は、アップロード、管理、URL の APIを提供しており、CDN 配信やファイルグループもこれに含まれます。Transloadit では、これらをアップロード/インポート用 Robot、処理用 Robot、エクスポート用 Robot、任意の CDN 配信に分離しています。利用中の操作を洗い出し、対応する処理を Transloadit Template の Step に割り当ててください。Uploadcare のすべての機能を一対一で置き換えられるわけではありません。
ファイルのホスティングには、Transloadit Storage(現在ベータ版)または独自のストレージを選べます。Transloadit Storage を使う場合、別途ストレージアカウントを用意する必要はありません。File Library(プレビュー版)では、Transloadit Storage 内のファイルを参照、整理、プレビュー、ダウンロードするデジタルアセット管理機能を提供しています。File Library へのアクセスは Workspace ごとに有効になります。利用可否についてお問い合わせください。
以下の実行可能なワークフローは、独自のストレージを使う構成の例です。アップロードと処理を Template に移し、ファイルをバケットにエクスポートします。既存のアセットフォルダーやメタデータの移行、配信 URL の切り替え、アセットピッカーや CMS/エディター連携の置き換えには、別途移行計画が必要です。以下の例では実装していません。
移行の対応表
| Uploadcare の概念 | Transloadit への移行方法 |
|---|---|
| ファイルアップローダー | Uppy + Transloadit によるアップロード、または別の SDK |
| CDN 操作 URL | Template の Step、または対応する Robot と最後の /file/serve Step を使う Smart CDN |
| 画像のリサイズ/切り抜き | 🤖/image/resize |
| 画像圧縮 | 🤖/image/optimize。形式と品質を明示的に決定 |
| 動画エンコーディング | 🤖/video/encode |
| ファイルグループ | 複数の入力ファイルを一つの Assembly で処理。旧グループ ID、メンバーの順序、各メンバーの変換設定はアプリケーションで保持 |
| ストレージ | 🤖/s3/store、または別のエクスポート用 Robot |
| Webhook | Assembly Notification。ペイロードの処理と検証を書き換え |
Step の依存関係は、処理間でファイルを受け渡すために使います。永続的なファイルグループのレコードを置き換えるものではありません。Smart CDN の URL はバックエンドで署名し、オンデマンド配信には別の対応 Template を使ってください。
変換方針の決定。 URL 操作チェーン全体、アプリケーションのプリセット、切り抜き座標、向き、寸法、品質、形式を洗い出してください。Uploadcare の
format/autoは、ブラウザーの機能に応じて形式を選択します。以下の WebP 固定のアバターでは、このネゴシエーションは再現しません。透過やアニメーションも含め、代表的な画像で出力を比較してください。動画変換には専用の Template が必要です。以下のどちらの例も、動画ストリーミング、ドキュメント変換、すべての URL 操作、カスタムアップローダープラグインの移行には対応しません。
モデレーションは別のワークフロー。 Uploadcare の不適切なコンテンツのモデレーションは、アップロード時、または非同期 REST アドオン経由で画像をスキャンし、結果は appdata に返されます。移行対象の一覧には、しきい値や削除/レビューの判断を含め、モデレーション結果とポリシーを記録してください。これらの例はファイルの最適化やプレビューを行うもので、そのモデレーションゲートを再現するものではありません。UGC の公開前に代替手段を選定して検証し、準備が整うまで既存のゲートを維持してください。MIME フィルタリング、マルウェアスキャン、不適切なコンテンツの検出は、それぞれ異なる問題に対処します。
アップロードウィジェットの置き換え
ブラウザーからのアップロードには、Uppy と Transloadit Plugin を使ってください。Uppy は、ファイルピッカー、ドラッグ&ドロップ UI、再開可能なアップロード、リモートソース、Transloadit との直接連携を提供します。
ユーザーが画像をアップロードし、変換済みの CDN URL を受け取る一般的な Uploadcare のフローは、次のようになります。
- ブラウザーが Uppy 経由でアップロードし、保存済みの Transloadit Template を参照します。
- Template が、アプリに必要なすべての派生ファイルを生成します。
- Transloadit が、結果の URL をバックエンドに通知します。
- バックエンドが、その URL をデータベースに保存します。
署名付き Assembly リクエストに notify_url を設定し、受信する通知の署名を検証してください。ブラウザー側で処理完了を待つには、Uppy の waitForEncoding を有効にしてください。デフォルトでは、アップロードの完了だけを待ちます。
Uploadcare の UUID、グループ ID、CDN 操作 URL を想定したコールバックを書き換えてください。独自のアセット ID を保持し、完了した Assembly とエクスポート済みファイルに関連付けます。ローカルソースとリモートソース、再開、キャンセル、検証、失敗をテストしてください。アップロード UI の置き換えだけでは、既存のアセットブラウザーや CMS 連携は置き換わりません。
Uploadcare の Webhookは、アップロード、ファイル情報、ストレージ、削除のイベントを対象としています。任意の署名シークレットを設定すると
X-Uc-Signature ヘッダーが生成され、配信に失敗すると再試行されます。処理完了は Assembly Notification に対応付け、カタログと削除のイベントはアプリケーションで処理し、Transloadit 独自の通知検証を使ってください。Assembly ID を基準に更新を冪等にし、エクスポートが成功してから公開してください。以前のイベントペイロードや再試行スケジュールをそのまま流用せず、再試行と状態の突き合わせの動作をテストしてください。
セキュリティ方針の決定。 Uploadcare の署名付きアップロードは取り込みを認可します。一方、署名付き配信は、セキュアな CDN サブドメインまたは設定済みのカスタムドメイン経由のアクセスを制限します。公開/非公開のパス、トークンの有効期限、許可する派生ファイルを洗い出してください。許可する Template とフィールドには、バックエンドで署名した Transloadit リクエストを使い、ダウンロードの認可はバケット/CDN 側で適用してください。署名付き Assembly リクエストは、エクスポート済み S3 オブジェクトへのアクセスを許可したり制限したりするものではありません。移行を簡単にするために非公開ファイルを公開しないでください。Uploadcare のマルウェア保護を使っている場合は、明示的なスキャン用 Stepと隔離/公開ゲートを追加し、テストしてください。掲載した Template はファイルをスキャンしません。完全な ACL 実装、コンプライアンス適合性の確認、リージョン別ルーティングは、このガイドの例の範囲外です。
Template の例
この Template は、アップロードされた画像を受け取り、正方形の WebP アバターを作成します。元の画像とアバターの両方を最適化し、最適化したファイルを S3 に保存します。最適化には format パラメーターがなく、この例のように progressive を無効にしたままにすると、最適化後のファイルが大きい場合は元のファイルを返します。progressive を有効にすると、サイズが大きくなっても最適化結果を保持できます。
{
"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"
}
}
}
S3 用のサードパーティ認証情報を設定し、読み取りアクセス付きでバケットのルートを配信するように CDN を設定してください。url_prefix は CDN の作成やアクセス権の付与を行いません。acl: "bucket-default"はオブジェクト ACL を送信しません。バケットポリシーと CDN のオリジンアクセスでアクセスを設定してください。ASSEMBLY_COMPLETED の後、元の画像は results.optimized_original から、アバターは results.optimized_avatar から読み取ります。is_temp_url: false を持つエントリーだけを永続化してください。エクスポートによって、生成元 Step の URL が更新されます。Transloadit の一時 URL は 24 時間後に期限切れになります。処理結果ファイルの保存を参照してください。
既存の Uploadcare ファイルのインポート
元のファイルとカタログデータの洗い出し。 アプリケーションが参照する UUID を列挙し、ページネーションをたどりながら、プロジェクトの
REST API ファイル一覧と突き合わせてください。ファイル情報には、original_file_url、original_filename、ファイルサイズ、保存状態、処理データが含まれます。各ファイルについて、認可された元のファイルのダウンロードを選択してください。original_file_url がない場合やファイルが削除されている場合は、レコードを移行する前にその欠落を解消してください。必要に応じて、バックエンドで新しい署名付きソース URL を取得してください。
任意のメタデータ、タグ、関連する appdata は、データベースまたはサイドカーレコードに保持してください。ファイルのバイト列をインポートしても、これらはコピーされません。ファイルグループは、インデックス付きメンバーを持つ変更不能なコレクションで、メンバーには変換設定を含められます。グループ ID、順序付きのメンバー UUID、変換設定を別途記録してください。Assembly はファイルを処理しますが、その永続的なコレクションは再作成しません。アプリケーションで管理しているフォルダーパス、その他のコレクション間の関係、改訂履歴を保持し、改訂ごとに異なるストレージキーを割り当ててください。これらの Template は、過去の改訂やアプリケーションだけが管理する関係の検出もエクスポートも行いません。
一覧に認可済みの Uploadcare ダウンロード URL がある場合は、🤖/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"
}
}
}
プレビュー用 Step は 🤖/file/preview(ベータ版)を使います。コンテンツのサムネイルを取得できない場合は、汎用のファイル形式アイコンを返すことがあります。バックエンドで認可済みの uploadcare_url 値を選択してください。変換済みの CDN URL をインポートすると、その派生版がコピーされ、元のファイルとは限りません。参照されているファイルだけをバックフィルするか、認可済み URL の配列を
/http/import に渡して、範囲を限定したバッチで処理できます。旧 ID と新しい保存先の対応表を保持し、読み取り先を切り替える前に配信へのアクセスと出力品質を検証してください。このインポート用 Template は、エクスポート済みファイルを
results.imported と results.preview の配下に返します。非公開の S3 オブジェクトには、認可されたダウンロードまたは設定済みの CDN が必要です。
チェックリスト
配信の切り替え。 各 UUID と使用中の操作チェーンを、検証済みの移行先に対応付けて記録してください。アプリケーションのレコード、レンダリング済みページ、srcset、CSS、メール、CMS コンテンツ内の URL を置き換えてください。新しいストレージのホスト名に Uploadcare の操作構文を追加しても、その操作は適用されません。リダイレクトは、管理下にあるドメインまたはアプリケーションルートでのみ使用し、旧パスを解決する仕組みと意図したアクセスルールを用意してください。プロバイダー所有の CDN URL については、管理下にある参照を更新し、並行運用期間中はソースへのアクセスを維持してください。リダイレクトを恒久化したりソースファイルを削除したりする前に、認可、キャッシュ、実際のページをテストしてください。
計画上の見積もり。 アップローダーが一つ、画像の派生ファイルが数種類、アクセス可能な一覧、既存のバケット/CDN がある場合、テスト済みの試験導入までにエンジニアリング作業を数日、その後のバックフィルには実測に基づく時間を見込んでください。非公開配信、グループ、モデレーション、CMS の変更、改訂/カタログのエクスポートには、数週間以上かかる場合があります。これはエンジニアリング計画上の見積もりであり、実測した移行ベンチマークではありません。代表的なバッチで、インポート、処理、エクスポートのスループットとコストを測定してください。ソースのダウンロード、移行先の配信、両サービスの並行運用期間も含めてください。
- 元のファイル、メタデータ、タグ、グループの順序/変換設定、改訂、アクセスルール、操作、アップローダーのコールバック、モデレーション結果を洗い出してください。切り替え前に、対象外の機能への対応を決めてください。
- Template の処理設定をリポジトリでバージョン管理し、必要な派生ファイルとゲートをテストしてください。サポートに備えて、Template の改訂、Assembly ID、失敗情報、移行先との対応表を保持してください。
- 認証情報、ストレージ/CDN のアクセス、署名、通知受信側を設定してください。試験導入で、永続的な配信と重複/失敗の処理を検証してください。
- バッチサイズ、同時実行数、再試行回数に上限を設け、移行予算を設定してください。データを移動する前に、処理とストレージのリージョン、保持期間、コンプライアンス要件を確認してください。
- 機能フラグで新規アップロードを切り替え、範囲を限定したバッチでバックフィルしてください。再試行前に部分的なエクスポートの状態を突き合わせてください。元のファイル、派生ファイル、カタログの件数、非公開アクセスを比較してください。
- 対象群ごとに読み取り先と配信参照を更新し、ロールバック用にソースとの対応表を保持してください。ソースの最終差分を突き合わせ、ロールバック可能期間とキャッシュの有効期間が過ぎるまで旧配信を利用可能な状態に保ってください.