コンテンツへスキップ
オーラベースのロゴ
オーラベース

JavaScript SDK を使用してファイルを保存および提供する

client.storage による日常のストレージ フロー: バケット管理、シングルおよびマルチパートのアップロード、ストリーミング ダウンロード、HMAC 署名付き URL、およびゴミ箱の復元。

ハウツーガイド8 分 読み取りレベル 中間2026/10/28 に改訂

このページは自動翻訳されました。英語版が正式です。

バケット管理#

バケット はファイルをグループ化し、それらがパブリックかどうかを決定します。バケットの作成と削除には service_role キーが必要です。バケットを一覧表示するには、サインインしているユーザーまたは service_role キーが必要です (匿名キーは 403 FORBIDDENを受け取ります)。

server/buckets.tstypescript
// パブリックバケットを作成します (API キーなしで誰でもオブジェクトを読み取ることができます)
await admin.storage.createBucket('avatars', { public: true })

// プライベートバケットを作成します(オブジェクト所有者またはservice_roleのみが読み取り可能)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // ファイルごとに 10 MiB の制限
  allowedMimeTypes: ['application/pdf'],
})

// アクセス可能なバケットをリストする
const { data: buckets, error } = await admin.storage.listBuckets()

バケットは fileSizeLimit (バイト単位) および allowedMimeTypesも受け入れます。大きすぎるアップロードの場合は 413 PAYLOAD_TOO_LARGEが返され、許可されていないタイプの場合は 400 BAD_REQUESTが返されます。

アップロード、ダウンロード、リスト、削除#

files.tstypescript
const bucket = aura.storage.from('invoices')

// アップロード: ファイル、BLOB、バッファー、または Uint8Array
// 5 MiB を超えるファイルは自動的に複数のパートに分割されます
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { キー、バケット、URL、サイズ、content_type、etag }

// 現在のユーザーが所有する既存のファイルを置き換えます
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// プレフィックス/フォルダーの下にあるファイルを一覧表示する
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// ファイルを BLOB としてダウンロードする
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// ファイル全体をメモリにロードせずにストリームダウンロード
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// ファイルを削除します (デフォルトではゴミ箱に移動され、保存期間は 30 日間です)
await bucket.remove([`${user.id}/2026-10.pdf`])

// 完全な削除 (ゴミ箱をバイパスし、ディスク クォータをすぐに解放します)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

主要な実行時の動作:

  • 既存のパスをアップロードすると、upsert: true が指定されていない限り、409 CONFLICT が返されます。
  • 匿名アップロードは、プライベート バケットとパブリック バケットの両方で とともに 403 FORBIDDEN とともに拒否されます (書き込みには認証された JWT またはサービス キーが必要です)。
  • パス トラバーサル保護: .. または不正な文字を含むパスは、未処理の例外をスローせずに 400 INVALID_PATH を返します。
  • ユーザー分離: あるユーザーは、別のユーザーが所有するファイルを上書きまたは削除できません (owner_id = auth.uid())。 ${user.id}/...のようなユーザー スコープのフォルダーを使用してパスを構造化します。

ファイルを共有する (公開 URL と署名付き URL)#

share.tstypescript
// 1. パブリック バケット: 直接の永続 URL (API キーなしで提供)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// カスタム ファイル名を使用して添付ファイルとして強制的にダウンロードする
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. プライベート バケット: 構成可能な TTL を使用した HMAC 署名付き URL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // 300秒(5分間)有効
  { download: true }
)
// data.signedUrl と data.url には、HMAC 署名付き URL が含まれます

// 3. 秘密鍵を公開せずに直接ブラウザにアップロード
// サーバー側 (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// ブラウザクライアント (API キーは必要ありません):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

署名付き URL は、HTTP メソッド (GET または PUT)、バケット、キー、および有効期限のタイムスタンプをシールします。期限切れになるか、オブジェクトが削除されると、リクエストは 403 FORBIDDENを受け取ります。

誰が何をできるのか(アクセスマトリックス)#

アクション匿名キー (anon)サインインしたユーザー (authenticated)サービスロール (service_role)
パブリック バケット内のファイルを読み取りますはいはいはい
プライベート バケット内のファイルを読み取りますいいえ (403)所有者のみ (owner_id = auth.uid())はい
新しいファイルをアップロードしますいいえ (403)はい(所有者になります)はい
置換 (upsert) または を削除しますいいえ (403)所有者のみはい
パブリック バケット内のファイルをリストするはいはいはい
プライベート バケット内のファイルをリストするいいえ (403)所有者のみ (RLS フィルター)はい
バケットの作成、更新、または削除いいえ (403)いいえ (403)はい
署名付きアップロード URL の作成いいえ (403)いいえ (403)はい

所有者は JWT サブジェクト (auth.uid()) によって識別されます。パブリック バケットとプライベート バケットの両方で、ユーザーは他のユーザーのオブジェクトを上書きしたり破棄したりすることはできません。

移動、コピー、メタデータ、ゴミ箱#

server/organise.tstypescript
// ファイルをコピーします (元の Content-Type とカスタム メタデータを保持します)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// ファイルを移動または名前変更する
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// オブジェクトのメタデータ (サイズ、MIME タイプ、ETag、カスタム メタデータ) を検査します。
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// 現在ゴミ箱にあるアイテムをリストします (30 日間保持)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// ゴミ箱からオブジェクトを復元する
await admin.storage.from('invoices').restore('2026/final.pdf')

リアルタイムの画像変換 (サイズ変更、形式変換、回転) については、Storage SDK Referenceを参照してください。