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.
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).
// 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#
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 CONFLICTdeğerini döndürür (upsert: truesağlanmadığı sürece). - Anonim yüklemeler, hem özel hem de genel paketlerde ile
403 FORBIDDENile 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şturmadan400 INVALID_PATHdeğ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)#
// 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)#
| Eylem | Anonim anahtar (anon) | Oturum açmış kullanıcı (authenticated) | Hizmet rolü (service_role) |
|---|---|---|---|
| Genel paketteki dosyayı okuyun | Evet | Evet | Evet |
| Özel paketteki dosyayı okuyun | Hayır (403) | Yalnızca sahip (owner_id = auth.uid()) | Evet |
| Yeni bir dosya yükleyin | Hayır (403) | Evet (sahibi olur) | Evet |
(upsert) öğesini değiştirin veya öğesini silin | Hayır (403) | Yalnızca sahip | Evet |
| Genel paketteki dosyaları listeleme | Evet | Evet | Evet |
| Özel bir paketteki dosyaları listele | Hayır (403) | Yalnızca sahip (RLS filtre) | Evet |
| Paketleri oluşturun, güncelleyin veya silin | Hayır (403) | Hayır (403) | Evet |
| Mint imzalı yükleme URL'leri | Hayı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#
// 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.