🔍 ファイルストレージスキーマ

ファイルストレージスキーマは、NodeBlocksアプリケーションでのファイル管理データ検証用のJSONスキーマ定義を提供します。これらのスキーマは、データの整合性を保証し、ファイルストレージ関連のAPIエンドポイントの明確な契約を提供します。

---

🎯 概要

ファイルストレージスキーマは以下の目的で設計されています：

• コンテンツタイプ検証による画像アップロードリクエストの検証
• ファイルサイズ制限と制約の処理
• MIMEタイプ検証による複数の画像形式のサポート
• 安全なファイル操作契約の提供
• 署名付きURLの適切なレスポンス構造の保証

---

📋 ファイルストレージスキーマタイプ

画像アップロードスキーマ

コンテンツタイプとサイズ検証を含む画像アップロード操作用のスキーマ。

レスポンススキーマ

署名付きURLを含むファイルストレージ操作レスポンス用のスキーマ。

---

🔧 利用可能なファイルストレージスキーマ

getSignedImageUploadUrlSchema

画像をアップロードするための必須フィールドを含む画像アップロードスキーマ。

目的: 画像アップロードURL生成リクエストを検証します

スキーマ詳細:

• Type: OpenAPIOperation
• Parameters: コンテンツタイプとファイルサイズ用のクエリパラメータ
• Response: objectIdとsignedUrlを含むオブジェクト
• Content Types: サポートされている画像MIMEタイプのみ
• File Size Limit: 最大10MB

Query Parameters:

• contentType: string (必須) - サポートされている画像MIMEタイプ
• contentLength: integer (必須) - ファイルサイズ（バイト単位、最大10MB）

サポートされている画像MIMEタイプ:

• image/jpeg
• image/png
• image/webp
• image/gif
• image/svg+xml
• image/avif
• image/bmp
• image/x-icon
• image/tiff
• image/heif
• image/heic

Response Structure:

{
  objectId: string;    // Cloud Storage object path, e.g. 'bucket-name/object-key'
  signedUrl: string;   // Pre-signed URL to access the object
}

使用例:

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

const { getSignedImageUploadUrlSchema } = schemas;

const imageUploadSchema = getSignedImageUploadUrlSchema({});
const validate = ajv.compile(imageUploadSchema.schemas as SchemaDefinition);
const isValid = validate({
  contentType: 'image/jpeg',
  contentLength: 1024000
});

リクエスト例:

GET /files/image/upload-url?contentType=image/jpeg&contentLength=1024000

レスポンス例:

{
  "objectId": "bucket-name/object-key",
  "signedUrl": "https://storage.googleapis.com/bucket-name/object-key?signature=..."
}

---

getSignedFileUploadUrlSchema

安全なファイルアップロード用のコンテンツタイプとサイズ検証を含むファイルアップロードスキーマ。

目的: セキュリティチェックを含む署名付きファイルアップロードURL生成リクエストを検証します

スキーマ詳細:

• Type: OpenAPIOperation
• Parameters: コンテンツタイプとファイルサイズ用のクエリパラメータ
• Response: objectIdとsignedUrlを含むオブジェクト
• Security: 許可リストから危険なMIMEタイプを除外
• File Size Limit: 最大10MB

Query Parameters:

• contentType: string (必須) - mime-typesライブラリからサポートされているMIMEタイプ
• contentLength: integer (必須) - ファイルサイズ（バイト単位、最大10MB）

MIMEタイプ検証:

• 検証に mime-types ライブラリの列挙型を使用
• 悪用される可能性のある危険なファイルタイプを除外
• 幅広い安全なファイル形式をサポート

除外される危険なMIMEタイプ:

• 実行可能ファイル（.exe、.com、.batなど）
• スクリプトファイル（.js、.vbs、.pyなど）
• マクロ対応ドキュメント
• アーカイブと圧縮ファイル
• その他の潜在的に有害なファイルタイプ

Response Structure:

{
  objectId: string;    // Cloud Storage object name/key
  signedUrl: string;   // Pre-signed URL for file access
}

使用例:

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

const { getSignedFileUploadUrlSchema } = schemas;

const fileUploadSchema = getSignedFileUploadUrlSchema({});
const validate = ajv.compile(fileUploadSchema.schemas as SchemaDefinition);
const isValid = validate({
  contentType: 'image/jpeg',
  contentLength: 1024000
});

リクエスト例:

GET /files/upload-url?contentType=image/jpeg&contentLength=1024000

レスポンス例:

{
  "objectId": "bucket-name/object-key.jpg",
  "signedUrl": "https://storage.googleapis.com/bucket-name/object-key.jpg?signature=..."
}

---

🔗 関連ドキュメント

• ファイルストレージ概要 - ファイルストレージドメイン概要
• ファイルストレージブロック - ブロックドキュメント