Files SDK

Files SDKとは？

Files SDKは、オブジェクトストレージとブロブストレージのバックエンドとやり取りするための、統一された単一の一貫性のあるAPIを提供する統合ストレージSDKです。クラウドプロバイダーごとに異なるSDKを学ぶ必要はなく、S3、Cloudflare R2、Google Cloud Storage、Azure Blob、そして30以上の他のプロバイダーで動作する、小さくて正直なインターフェースを一つ手に入れられます。Web標準のI/O（File、Blob、ReadableStream、ArrayBuffer、stringを受け入れ）を使用し、Node、Bun、Workers、Vercelなど、fetchが動作するあらゆる環境で実行できます。

対象者

• フルスタック開発者：ストレージプロバイダーを変更するたびに、アプリケーション内のすべてのアップロードおよびダウンロード呼び出しを書き直す必要がない方。
• プラットフォームエンジニア：マルチテナントまたはマルチリージョンシステムを構築しており、プロバイダー固有の癖を単一のクラスの背後に抽象化する必要がある方。
• インディーハッカーやスタートアップチーム：シンプルなファイルシステムアダプターから始めて、後でアプリケーションコードを変更せずにS3やR2に移行したい方。

主な機能

プロバイダー間で共通の小さなAPI

アップロード、ダウンロード、リスト、削除、ヘッド、存在確認、コピー、URL生成 — S3、GCS、Azure、ローカルファイルシステムのいずれを使用している場合でも、同じ10個のメソッドが同じように動作します。アダプターを交換しても、呼び出しは変わりません。

Web標準のI/O

SDKはFile、Blob、ReadableStreamなどのネイティブなWeb型を受け入れ、それらを返します。独自のストリームラッパーやバッファ変換はありません。fetch APIをサポートする任意のランタイム（Node、Bun、Cloudflare Workers、Vercel Edgeなど）で実行できます。

files.rawによるエスケープハッチ

バージョニング、ライフサイクルポリシー、ACL、マルチパートアップロードなどのプロバイダー固有の機能が必要な場合、ネイティブクライアントは常に1プロパティ先にあります。files.rawはアダプターごとに型付けされているため、コードベースを離れることなく、基盤となるSDKの完全なオートコンプリートを利用できます。

予測可能なエラー

すべてのプロバイダーエラーは、一貫性のあるcodeプロパティを持つ単一のFilesErrorに正規化されます。元のエラーはcauseとして添付されるため、障害を均一に処理しながら、完全なコンテキストでデバッグできます。

際立っている点

「プロバイダー間で共通の小さなAPI。ストレージプロバイダーを交換しても、呼び出しを書き直す必要はありません。」

それが中核となる約束であり、Files SDKは妥協なくそれを実現します。他の抽象化レイヤーがプロバイダー固有の詳細を漏らしたり、最小公分母的なAPIに強制したりするのに対し、Files SDKはユースケースの95%をカバーするクリーンな10メソッドのインターフェースを提供し、残りの5%についてはネイティブクライアントを提供します。互換性マトリックスは、どのメソッドがどのプロバイダーで動作するかを、動作が異なる場合の明確な注意事項とともに正確に示します。

検討する価値がある場合…

アプリケーションが触れるすべてのストレージプロバイダー用のアダプターコードを維持することにうんざりしている場合、またはあるバックエンドから別のバックエンドに移行する予定があり、苦痛な書き直しを避けたい場合。また、ユーザーが提供するストレージを受け入れ、プロバイダーを指定する必要がないライブラリやフレームワークを構築している場合にも、Files SDKは最適です。