Filestack から Transloadit への移行
Filestack は、ファイル選択、アップロード、ストレージ、CDN 変換と非同期 Workflowを提供しています。Transloadit では、ブラウザーでのファイル選択は Uppy が担当し、ファイル処理は Robot が担当します。対応する Workflow を Template で定義し、その後 SDK、Uppy、または REST API を使って Assembly を作成します。アプリケーションで使っている処理は個別に確認してください。以下の対応表は、完全な機能互換を保証するものではありません。
このガイドでは、自身で管理するストレージへのファイル処理とエクスポートを扱います。ホスト型の Transloadit DAM 移行は対象外です。ホスト型 Media Library への取り込み、フォルダーとメタデータの維持、tlcdn.com を介した配信、移行のドライランとマニフェスト、Media Library のロール、ウィジェット、CMS/エディター連携には、別途移行計画が必要です。以下で説明するインベントリーは、アプリケーション側で管理する移行記録であり、ホスト型 DAM の移行ツールではありません。
移行対応表
| Filestack の概念 | Transloadit の出発点 |
|---|---|
| Picker | Uppy + Transloadit によるアップロード。コールバックを書き換え、各リモートソースを検証 |
| Upload | 🤖/upload/handle の後に処理とエクスポート |
| Transformation task | Template 内の Robot Step。パラメーターを読み替え、出力を比較 |
| 画像変換/リサイズ | 🤖/image/resize。クロップ、サイズ、形式の挙動を検証 |
| ドキュメントプレビュー | 🤖/document/thumbs または 🤖/file/preview(beta) |
| Virus Detection | 🤖/file/virusscan。公開前のスキャンゲートを定義 |
| Workflow | Transloadit Template。タスク依存関係と条件ルールを再構築 |
| Storage alias | インポート Robot とサードパーティ認証情報を使って既存ストレージから取り込み、その後に処理とエクスポート |
| Webhook | Assembly Notification。受信側と署名検証を書き換え |
| ファイルハンドルとカタログデータ | アセット ID、ストレージキー、アプリケーションデータベース。ソースから宛先への明示的な対応付けを維持 |
Filestack の storage alias は、Filestack を経由したアップロードなしで、既存の外部ストレージを Filestack の処理サービスに公開します。すでにソースバケットを所有している場合は、元ファイルをそこに残したまま、新しい派生ファイルを処理・エクスポートできるか判断してください。Filestack 管理のストレージでは、アカウントを廃止する前に、その CDN 経由で認可済みの元ファイルをダウンロードしてください。このガイドには、一括アカウントエクスポートやアセット探索用のスクリプトは含まれません。
カタログは別に保持します。 バイト列をコピーする前に、アセット ID、Filestack handle、元のダウンロード URL、保存場所/コンテナー/パス、ファイル名、MIME type、サイズ、チェックサム、必要な派生ファイルを記録してください。Filestack の metadata endpointでは、ファイル情報、ストレージ情報、ハッシュを返せます。この情報はオンデマンドで生成されます。ソースインベントリーと、完了した Assembly/エクスポートの対応付けは、自身のデータベースに保持してください。
Filestack の Picker upload tags は、アップロードレスポンスと Webhook で返されます。また、DAMでは、ユーザーがアセットのタグと説明を編集できます。これらの記録は、ファイルメタデータとは別に保持してください。以下の Template はバイト列をコピーして処理するものであり、カタログのタグや説明はコピーしません。保存済みのストレージパスを使って、宛先オブジェクトキーでフォルダー構造をどう維持するか判断してください。これらの例では新しいパスを生成します。アプリケーションで使うコレクションやリビジョン関係についても、順序や権限を含めて棚卸ししてください。Filestack の overwrite operation は handle の背後にあるファイルを置き換えるため、ダウンロードはバージョン履歴のエクスポートにはなりません。このガイドでは、コレクション所属や過去のリビジョンはエクスポートしません。必要であれば、切り替え前にアプリケーションまたは既存のアーカイブから取得してください。
Workflow ごとに Template を作成
変換レシピを読み替えます。 Filestack の Processing Engine は CDN URL 内でタスクを受け取り、Workflow ではタスクと条件ロジックを定義します。各アプリケーション画面で使っている完全なタスクチェーン、パラメーター、名前付きアプリケーションプリセット、workflow ID、条件を棚卸ししてください。必要なレシピを Template として再構築し、派生ファイルを生成し、代表的な画像とドキュメントについて、クロップ、アスペクト比、向き、ページ選択、品質、形式を比較してください。サムネイル Robot は、対話型の Filestack Document Viewer の代替にはなりません。必要であれば別のビューアーを選定してください。以下の例は画像/PDF プレビューと一般的なファイルプレビューを対象としており、Filestack のすべての変換機能やインテリジェンス機能を再現するものではありません。
この Template は、検出した MIME type を確認し、画像サムネイルまたは PDF の 1 ページ目のサムネイルを作成して、許可した元ファイルとプレビューを保存します。その他の MIME type はエラーで Assembly を停止します。これは型フィルタリングであり、マルウェアスキャンではありません。Workflow で必要な場合は /file/virusscan を追加してください。
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"accepted_files": {
"use": ":original",
"robot": "/file/filter",
"accepts": [["${file.mime}", "regex", "^(image/[^/]+|application/pdf)$"]],
"error_on_decline": true
},
"images": {
"use": "accepted_files",
"robot": "/file/filter",
"accepts": [["${file.mime}", "regex", "^image/"]]
},
"pdfs": {
"use": "accepted_files",
"robot": "/file/filter",
"accepts": [["${file.mime}", "=", "application/pdf"]]
},
"image_thumb": {
"use": "images",
"robot": "/image/resize",
"width": 600,
"height": 600,
"resize_strategy": "fit",
"format": "webp",
"result": true
},
"document_thumb": {
"use": "pdfs",
"robot": "/document/thumbs",
"format": "jpg",
"page": 1,
"width": 600,
"resize_strategy": "fit",
"result": true
},
"exported": {
"use": ["accepted_files", "image_thumb", "document_thumb"],
"robot": "/s3/store",
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "filestack-import/${unique_prefix}/${file.url_name}",
"url_prefix": "https://cdn.example.com/",
"acl": "bucket-default"
}
}
}
2 つのルーティングフィルターは MIME type を使って、画像と PDF を別々のプレビュー分岐に振り分けます。拒否された元ファイルは export Step に入りません。Assembly はトランザクションではありません。別のファイルが失敗しても、すでにエクスポート済みの許可ファイルはロールバックされません。エラーの無視は失敗を抑止しますが、ルーティングや検証の代わりにはなりません。
バックフィルの試行ごとに書き込まれたストレージオブジェクトを追跡してください。失敗した Assembly を再試行する前に、部分的なエクスポートを照合または削除し、再試行で重複オブジェクトや孤立オブジェクトが残らないようにします。一部のファイルのエクスポートに成功していても、失敗した試行はアプリケーションで公開しないでください。
CDN はバケットルートを読み込むように設定してください。url_prefix は返される
URL を変更するだけです。acl: "bucket-default" はオブジェクト ACL を送信しないため、アクセス制御はバケットポリシーと CDN のオリジンアクセスで設定してください。ASSEMBLY_COMPLETED の後、許可された元ファイルは results.accepted_files から、プレビューは results.image_thumb と results.document_thumb から読み取ります。export は、その use パラメーターで指定された Step 配下にエントリーを追加または更新します。ただし、その Step で result: false を明示的に設定している場合は除きます。永続化するのは is_temp_url: false を持つエントリーだけにしてください。一時的な Transloadit URL は
24 時間後に期限切れになります。詳しくは結果ファイルの保存を参照してください。
ファイル選択の置き換え
ブラウザー統合では、Filestack picker を Uppy に置き換えます。Uppy はローカルファイルの選択、ドラッグ&ドロップによるアップロード、リモートソースへの接続に対応しています。Transloadit Plugin は Template を使ってファイルを Assembly に送信します。waitForEncoding を有効にすると、完了した処理結果をブラウザーで受け取れます。または、署名付き Assembly リクエストで notify_url を設定し、バックエンドで
Assembly Notification を処理します。通知署名を検証し、データベースを更新する前に正常完了を必須にしてください。
Filestack の Picker response には、ファイル handle、URL、アップロードメタデータが含まれます。onUploadDone はアップロード済みファイルと失敗ファイルを報告します。そのレスポンス形式を前提にしたハンドラーは書き換え、キャンセル、再試行、許可するファイル形式/サイズ、アクセシビリティ、各リモートソースの認可フローをテストしてください。カタログタグはバックエンドに保持し、picker のメタデータがエクスポート後も残ると想定せず、アセット ID に関連付けてください。
自動化とセキュリティは意図的に置き換えます。 Filestack の
webhooks はイベントごとに異なるペイロードを持ち、検証には FS-Timestamp ヘッダーと FS-Signature ヘッダーを使います。workflow job の結果は Assembly Status のペイロードではありません。Transloadit の受信側は、その専用のドキュメント化された契約と署名方式に基づいて実装してください。データベース更新は冪等にし、Assembly ID を保持し、処理を再試行する前に部分的なエクスポートを照合してください。アセットを公開する前に、アップロード完了と、処理およびエクスポートの成功を分けて扱ってください。
Filestack の security policies では、HMAC-SHA256 で署名した
Base64URL ポリシーを使い、有効期限、calls、handles、アップロードパス/コンテナー、サイズを制限できます。アップロードと配信の認証は構成可能なため、アプリケーションで実際に強制している内容を棚卸ししてください。アップロード認可はバックエンドで
Transloadit authentication を使って再構成し、ダウンロード認可はストレージ/CDN 側で設定してください。既存の Filestack ポリシーと署名は、置き換え先サービスの認可には使えません。署名付きのソース URL を置き換えるためだけに、非公開エクスポートを公開にしないでください。Filestack の S3 upload access setting は、保存オブジェクトへのアクセスを制御します。宛先バケットポリシー、CDN のオリジンアクセス、署名付きダウンロード方式は、Assembly 認証とは別に確認してください。エクスポート例では
acl: "bucket-default" を設定しています。移行前に宛先ポリシーを検証してください。
Filestack の Virus Detection は、ストレージへのアップロード後に Workflow 経由で非同期に実行されます。これを使っている場合は、元ファイルやプレビューを公開する前に、置き換え後のスキャン/隔離ゲートを設計してテストしてください。MIME フィルタリングも、アップロード成功も、ファイルの安全性を証明するものではありません。
エージェント用ツールも考慮します。Filestack Claude Plugin は、アップロード、変換、ポリシー署名、Workflow 実行、Webhook 検証のためのツールを公開しています。これらのツールが実際に生成または呼び出している URL と Workflow を棚卸ししてください。必要な処理は、レビュー済みの Template 定義と SDK/API 呼び出しで再構築します。このガイドは、その Plugin やインテリジェンスモデルに対するドロップイン置換を提供するものではありません。サポートと調査のために、Template のリビジョン、Assembly ID、出力確認、再試行判断を保持してください。完全移行を承認する前に、サンプルバッチで処理コストと保存コストを見積もり、バックフィルの同時実行数と再試行回数に上限を設け、リージョン間データフロー、保持期間、コンプライアンス要件を確認してください。このガイドは、規制準拠やリージョンルーティング設定を確立するものではありません。
既存の Filestack URL の取り込み
Filestack の CDN URLs は、handle でファイルを識別します。変換タスクを含まない認可済みの元 URL を選び、ソースセキュリティで必要な場合は、有効な読み取り用ポリシー/署名を付与してください。キューに入ったダウンロードが完了できるだけの十分な有効期限を設定し、署名付きソース URL をログや公開マニフェストに残さないでください。ダウンロード可能な HTTPS URL に解決される場合は、🤖/http/import で移行できます。
{
"steps": {
"imported": {
"robot": "/http/import",
"url": "${fields.filestack_url}"
},
"preview": {
"use": "imported",
"robot": "/file/preview",
"result": true
},
"exported": {
"use": ["imported", "preview"],
"robot": "/s3/store",
"credentials": "YOUR_AWS_CREDENTIALS",
"path": "filestack-backfill/${unique_prefix}/${file.url_name}",
"acl": "bucket-default"
}
}
}
filestack_url の認可済み値は、バックエンドのアセットインベントリーから選択します。/file/preview は beta であり、コンテンツサムネイルを生成できない場合は、汎用のファイル種別アイコンにフォールバックします。上限を設けたバックフィル job を実行してください。/http/import は URL の配列も受け取れます。完了したエクスポートのアクセスと品質を確認するまでは、ソース handle と URL を保持してください。非公開の S3 オブジェクトには、認可済みのダウンロードか、設定済みの CDN が必要です。インポート Template は、エクスポート済みファイルを
results.imported と results.preview の配下に返します。
検証後に配信 URL を置き換えます。 古い handle と変換レシピごとに、新しいエクスポート URL への対応付けを保持してください。データベースレコード、レンダリング済みマークアップ、CSS、CMS コンテンツ、API レスポンスを更新する前に、元ファイルのチェックサム、派生ファイルの見た目、MIME type、認可済み/公開アクセスを確認してください。Filestack のタスクを新しい CDN ホスト名に付け足すのではなく、必要な派生ファイルは再生成してください。新しいアップロードが新しいパスを使う間も、ロールバック用に古いレコードと読み取りパス切り替えを保持してください。
自身で管理するドメインから配信している URL であれば、リダイレクトできます。Filestack の
custom CNAME を使っている場合は、配信レイヤーが古い
handle/task パスを解決でき、意図したアクセスルールを適用できるようになってから、そのオリジンを置き換えてください。Filestack 共有の cdn.filestackcontent.com ドメインには、自身のリダイレクトを設定できません。自身で管理するコンテンツ内のリンクは置き換え、更新できない参照についてはソースへの継続アクセスを計画してください。リダイレクトを恒久化する前に、キャッシュ動作とアクセス制御をテストしてください。
チェックリスト
計画時の見積もり。 1 つの picker、アクセス可能なアセットインベントリー、少数のプレビューレシピ、自身で管理するバケットであれば、テスト済みパイロットには数営業日のエンジニアリング工数を見込んでください。大規模なバックフィル、カスタムドメイン互換、非公開配信、ドキュメントビューアー、アプリケーション管理のカタログ/バージョンエクスポートがある場合は、数週間以上かかることがあります。これは計画用の見積もりであり、実測した移行ベンチマークではありません。代表的なバッチで計測し、転送制限、処理コスト、検証、ロールバックを含めてください。
- handle、ストレージパス、タグ/説明、バージョン、picker のコールバック、セキュリティルール、変換レシピ、workflow のタスク、エージェントツールの利用状況を棚卸しします。対象外の機能がある場合は、切り替え前に解消してください。
- 宛先オブジェクトキー、カタログ保存先、ダウンロード認可、CDN、旧 URL の扱い方を決めます。必要なアクセス権でサードパーティーの認証情報を設定してください。
- 代表的な画像、PDF、非対応ファイル、失敗ケースで Template を構築し、検証します。必要であれば、スキャン/隔離ゲートも含めてください。
- パイロットで picker と Webhook 受信側を置き換えます。完了処理、署名検証、再試行、冪等性、非公開ダウンロードアクセスを検証してください。
- 上限を設けたバックフィルを実行し、完了したエクスポートを記録して、部分的な試行を照合します。いずれかのアセットの読み取りパスを切り替える前に、元ファイルのチェックサムと派生ファイルの品質を比較してください。
- 新しいアップロードを切り替え、最終的なソース差分を照合した後、読み取りを段階的に移行します。エラー、コスト、旧 URL へのトラフィックを監視し、承認完了まではロールバック経路とソースアクセスを保持してください。