💾 ファイルストレージドライバー
ファイルストレージドライバーは、NodeBlocksアプリケーションで安全なファイル操作のための一貫したインターフェースを提供します。クラウドストレージプロバイダーの設定と操作を抽象化し、ビジネスロジックを変更することなく異なるストレージサービスを使用できるようにします。
🎯 概要
NodeBlocksのファイルストレージドライバーは、署名付きURL機能を持つ設定されたストレージインスタンスを作成するファクトリ関数です。これらは以下を提供します：
- 安全なファイル操作 - アップロード、ダウンロード、削除用の署名付きURL
- 一貫したインターフェース - 異なるクラウドストレージプロバイダー間で
- シンプルな設定 - プロジェクトIDとバケット名を使用
- テストサポート - モック実装を使用
📋 利用可能なファイルストレージドライバー
Google Cloud Storage Driver
Google Cloud Storageドライバーは、署名付きURL生成機能を持つ設定されたファイルストレージインスタンスを作成します。
前提条件
このドライバーを使用するには、Application Default Credentialsを提供してGoogle Cloud SDKクライアントを認証します：
- バケットにアクセスする権限を持つGoogle Cloudサービスアカウントを作成
- サービスアカウントJSONキーファイルをダウンロード
GOOGLE_APPLICATION_CREDENTIALS環境変数をJSONキーファイルの絶対パスに設定
ドライバーはGoogle Cloud Application Default Credentialsに依存しており、認証情報はcreateFileStorageDriverに直接渡されません。
createFileStorageDriver
署名付きURL機能を持つGoogle Cloud Storageファイルストレージドライバーを作成します。
パラメータ:
projectId: string- Google Cloudプロジェクト識別子bucketName: string- ファイル操作用のストレージバケット名options?: object- オプション設定signedUrlExpiresInSeconds?: number- デフォルトのURL有効期限（秒単位）（デフォルト: 900）
戻り値: FileStorageDriver - 署名付きURL生成メソッドを持つファイルストレージドライバー
使用例:
import { createFileStorageDriver } from '@nodeblocks/backend-sdk/drivers';
const fileStorage = createFileStorageDriver(
'my-project-id',
'my-storage-bucket'
);
カスタム有効期限の例:
import { createFileStorageDriver } from '@nodeblocks/backend-sdk/drivers';
const fileStorage = createFileStorageDriver(
'my-project-id',
'my-storage-bucket',
{ signedUrlExpiresInSeconds: 1800 } // 30分
);
🔧 ファイルストレージドライバーメソッド
FileStorageDriverは、削除と署名付きURL生成を含む安全なファイル操作のためのメソッドを提供します：
deleteFile
Google Cloud Storageバケットからファイルを削除します。
パラメータ:
objectName: string- バケットから削除するストレージオブジェクト名/パス
戻り値: Promise<void> - ファイル削除が完了したときに解決されるPromise
使用例:
await fileStorage.deleteFile('uploads/temp-file.jpg');
generateSignedDeleteUrl
Google Cloud Storageでのファイル削除操作用の署名付きURLを生成します。
パラメータ:
objectName: string- 削除するストレージオブジェクト名/パス
戻り値: Promise<string> - ファイル削除用の署名付きURL
使用例:
const deleteUrl = await fileStorage.generateSignedDeleteUrl('uploads/temp-file.jpg');
generateSignedDownloadUrl
Google Cloud Storageでのファイルダウンロード操作用の署名付きURLを生成します。
パラメータ:
objectName: string- ダウンロードするストレージオブジェクト名/パス
戻り値: Promise<string> - ファイルダウンロード用の署名付きURL
使用例:
const downloadUrl = await fileStorage.generateSignedDownloadUrl('uploads/document.pdf');
generateSignedUploadUrl
Google Cloud Storageでのファイルアップロード操作用の署名付きURLを生成します。
パラメータ:
contentType: string- アップロードするファイルのMIMEタイプcontentLength: number- 最大ファイルサイズ（バイト単位）objectName: string- アップロード用のストレージオブジェクト名/パス
戻り値: Promise<string> - ファイルアップロード用の署名付きURL
使用例:
const uploadUrl = await fileStorage.generateSignedUploadUrl(
'image/jpeg',
5 * 1024 * 1024, // 5MB制限
'uploads/profile-avatar.jpg'
);
cURL例:
# 署名付きURLを使用してファイルをアップロード
curl -X PUT \
-H "Content-Type: image/jpeg" \
-H "Content-Length: 5242880" \
--upload-file ./avatar.jpg \
"https://storage.googleapis.com/my-bucket/uploads/profile-avatar.jpg?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"
generateSignedDownloadUrl
Google Cloud Storageでのファイルダウンロード操作用の署名付きURLを生成します。
パラメータ:
objectName: string- ダウンロードするストレージオブジェクト名/パス
戻り値: Promise<string> - ファイルダウンロード用の署名付きURL
使用例:
const downloadUrl = await fileStorage.generateSignedDownloadUrl('uploads/document.pdf');
cURL例:
# 署名付きURLを使用してファイルをダウンロード
curl -O \
"https://storage.googleapis.com/my-bucket/uploads/document.pdf?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"
generateSignedDeleteUrl
Google Cloud Storageでのファイル削除操作用の署名付きURLを生成します。
パラメータ:
objectName: string- 削除するストレージオブジェクト名/パス
戻り値: Promise<string> - ファイル削除用の署名付きURL
使用例:
const deleteUrl = await fileStorage.generateSignedDeleteUrl('uploads/temp-file.jpg');
cURL例:
# 署名付きURLを使用してファイルを削除
curl -X DELETE \
"https://storage.googleapis.com/my-bucket/uploads/temp-file.jpg?X-Goog-Algorithm=ALGORITHM&X-Goog-Credential=CREDENTIAL&X-Goog-Date=DATE&X-Goog-Expires=EXPIRES&X-Goog-SignedHeaders=host&X-Goog-Signature=SIGNATURE"
🔗 関連ドキュメント
- File Storage Blocks - ドライバーを使用したファイルストレージ操作
- File Storage Schemas - ファイルストレージバリデーションスキーマ