İçeriğe geç
Aurabase Logosu
aura tabanı

Dosyaları JavaScript SDK'sıyla depolayın ve sunun

Client.storage ile günlük depolama akışları: paket yönetimi, tek ve çok parçalı yüklemeler, akışlı indirmeler, HMAC imzalı URL'ler ve çöp kutusu geri yükleme.

Nasıl yapılır kılavuzu8 dk. okuSeviye orta düzey28 Eki 2026 tarihinde revize edildi

Bu sayfa otomatik olarak çevrildi. İngilizce versiyonu yetkilidir.

Paket yönetimi#

Bir kovası dosyaları gruplandırır ve bunların herkese açık olup olmadığına karar verir. Paket oluşturmak ve silmek için service_role anahtarı gerekir. Grupların listelenmesi, oturum açmış bir kullanıcı veya service_role anahtarı gerektirir (anonim anahtar, 403 FORBIDDEN alır).

server/buckets.tstypescript
// Genel bir paket oluşturun (herkes API anahtarları olmadan nesneleri okuyabilir)
await admin.storage.createBucket('avatars', { public: true })

// Özel bir paket oluşturun (yalnızca nesne sahipleri veya hizmet_rolü okuyabilir)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // Dosya başına 10 MiB sınırı
  allowedMimeTypes: ['application/pdf'],
})

// Erişilebilir paketleri listele
const { data: buckets, error } = await admin.storage.listBuckets()

Bir paket ayrıca fileSizeLimit (bayt cinsinden) ve allowedMimeTypes öğelerini de kabul eder. Çok büyük bir yükleme 413 PAYLOAD_TOO_LARGE değerini döndürür, izin verilmeyen bir tür ise 400 BAD_REQUEST değerini döndürür.

Yükleme, indirme, listeleme, kaldırma#

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

// Yükleme: Dosya, Blob, Arabellek veya Uint8Array
// 5 MiB'tan büyük dosyalar otomatik olarak çok parçalı parçalara bölünür
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { anahtar, paket, url, boyut, içerik_türü, etag }

// Geçerli kullanıcının sahip olduğu mevcut bir dosyayı değiştirin
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// Bir önek/klasör altındaki dosyaları listeleme
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// Dosyayı Blob olarak indir
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// Dosyanın tamamını belleğe yüklemeden indirme akışını gerçekleştirin
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// Bir dosyayı kaldırma (varsayılan olarak 30 günlük saklama süresiyle çöp kutusuna taşınmıştır)
await bucket.remove([`${user.id}/2026-10.pdf`])

// Kalıcı silme (çöp kutusunu atlar ve disk kotasını anında boşaltır)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

Temel çalışma zamanı davranışları:

  • Mevcut bir yolu yüklemek, 409 CONFLICT değerini döndürür (upsert: true sağlanmadığı sürece).
  • Anonim yüklemeler, hem özel hem de genel paketlerde ile 403 FORBIDDEN ile reddedilir (yazma, kimliği doğrulanmış bir JWT veya hizmet anahtarı gerektirir).
  • Yol geçiş koruması: .. veya geçersiz karakterler içeren yollar, işlenmeyen istisnalar oluşturmadan 400 INVALID_PATH değerini döndürür.
  • Kullanıcı izolasyonu: bir kullanıcı başka bir kullanıcının (owner_id = auth.uid()) sahip olduğu dosyaların üzerine yazamaz veya dosyaları silemez. ${user.id}/... gibi kullanıcı kapsamlı klasörleri kullanarak yolları yapılandırın.

Dosya paylaşma (genel ve imzalı URL'ler)#

share.tstypescript
// 1. Genel paket: doğrudan kalıcı URL (API anahtarları olmadan sunulur)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// Özel dosya adıyla ek olarak indirmeye zorla
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. Özel paket: yapılandırılabilir TTL ile HMAC imzalı URL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // 300 saniye (5 dakika) geçerlidir
  { download: true }
)
// data.signedUrl ve data.url, HMAC imzalı URL'yi içerir

// 3. Gizli anahtarları açığa çıkarmadan doğrudan tarayıcı yüklemesi
// Sunucu tarafı (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// Tarayıcı istemcisi (API anahtarı gerekmez):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

İmzalı URL'ler HTTP yöntemini (GET veya PUT), paketi, anahtarı ve son kullanma zaman damgasını mühürler. Süresi dolduğunda veya nesne silindiğinde istekler 403 FORBIDDEN alır.

Kim ne yapabilir (Erişim matrisi)#

EylemAnonim anahtar (anon)Oturum açmış kullanıcı (authenticated)Hizmet rolü (service_role)
Genel paketteki dosyayı okuyunEvetEvetEvet
Özel paketteki dosyayı okuyunHayır (403)Yalnızca sahip (owner_id = auth.uid())Evet
Yeni bir dosya yükleyinHayır (403)Evet (sahibi olur)Evet
(upsert) öğesini değiştirin veya öğesini silinHayır (403)Yalnızca sahipEvet
Genel paketteki dosyaları listelemeEvetEvetEvet
Özel bir paketteki dosyaları listeleHayır (403)Yalnızca sahip (RLS filtre)Evet
Paketleri oluşturun, güncelleyin veya silinHayır (403)Hayır (403)Evet
Mint imzalı yükleme URL'leriHayır (403)Hayır (403)Evet

Sahibi JWT konusuyla (auth.uid()) tanımlanır. Hem genel hem de özel paketlerde kullanıcılar diğer kullanıcıların nesnelerinin üzerine yazamaz veya bunları yok edemez.

Taşıma, kopyalama, meta veriler ve çöp kutusu#

server/organise.tstypescript
// Bir dosyayı kopyalayın (orijinal İçerik Türünü ve özel meta verileri korur)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// Dosyayı taşıma veya yeniden adlandırma
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// Nesne meta verilerini inceleyin (boyut, MIME türü, ETag, özel meta veriler)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// Şu anda çöp kutusundaki öğeleri listeleme (30 günlük saklama)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// Bir nesneyi çöp kutusundan geri yükleme
await admin.storage.from('invoices').restore('2026/final.pdf')

Gerçek zamanlı görüntü dönüştürmeleri için (yeniden boyutlandırma, biçim dönüştürme, döndürme), Depolama SDK Referansı'ye bakın.