💾 ファイルストレージドライバー

ファイルストレージドライバーは、NodeBlocksアプリケーションでの安全なファイル操作のための統一されたインターフェースを提供します。クラウドストレージプロバイダーの設定と操作を抽象化し、ビジネスロジックを変更することなく異なるストレージサービスを使用できるようにします。

---

🎯 概要

NodeBlocksのファイルストレージドライバーは、署名付きURL機能を備えた設定済みストレージインスタンスを作成するファクトリ関数です。これらは以下を提供します：

• アップロード、ダウンロード、削除のための署名付きURLによる安全なファイル操作
• 異なるクラウドストレージプロバイダー間の統一されたインターフェース
• プロジェクトIDとバケット名によるシンプルな設定
• モック実装によるテストサポート

---

📋 利用可能なファイルストレージドライバー

Google Cloud Storageドライバー

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 = await createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket'
);

カスタム有効期限を使用した例:

import { createFileStorageDriver } from '@nodeblocks/backend-sdk/drivers';

const fileStorage = await createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket',
  { signedUrlExpiresInSeconds: 1800 } // 30分
);

---

🔧 ファイルストレージドライバーメソッド

generateSignedUploadUrl

クラウドストレージへの安全なファイルアップロードのための署名付き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

クラウドストレージからの安全なファイルダウンロードのための署名付き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

クラウドストレージからの安全なファイル削除のための署名付き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"

---

🔗 関連ドキュメント

• ファイルストレージブロック - ドライバーを使用したファイルストレージ操作
• ファイルストレージスキーマ - ファイルストレージ検証スキーマ