Przejdź do treści
Logo Aurabase
aurabaza

Przechowuj i udostępniaj pliki za pomocą pakietu JavaScript SDK

Codzienny przepływ danych za pomocą client.storage: zarządzanie zasobnikami, przesyłanie jedno- i wieloczęściowe, pobieranie strumieniowe, adresy URL podpisane HMAC i przywracanie kosza.

Przewodnik krok po kroku8 min przeczytanePoziom mediatorZmieniono 28 paź 2026

Ta strona została przetłumaczona automatycznie. Wersja angielska jest miarodajna.

Zarządzanie wiadrami#

Wiadro grupuje pliki i decyduje, czy są one publiczne. Tworzenie i usuwanie segmentów wymaga klucza service_role. Lista segmentów wymaga zalogowanego użytkownika lub klucza service_role (klucz anonimowy otrzymuje 403 FORBIDDEN).

server/buckets.tstypescript
// Utwórz wiadro publiczne (każdy może czytać obiekty bez kluczy API)
await admin.storage.createBucket('avatars', { public: true })

// Utwórz prywatny zasobnik (tylko właściciele obiektów lub rola_usługi mogą czytać)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // Limit 10 MiB na plik
  allowedMimeTypes: ['application/pdf'],
})

// Wyświetl listę dostępnych zasobników
const { data: buckets, error } = await admin.storage.listBuckets()

Wiadro akceptuje również fileSizeLimit (w bajtach) i allowedMimeTypes. Przesyłanie, które jest zbyt duże, zwraca 413 PAYLOAD_TOO_LARGE, a niedozwolony typ zwraca 400 BAD_REQUEST.

Przesyłaj, pobieraj, wyświetlaj listę, usuwaj#

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

// Prześlij: plik, obiekt blob, bufor lub tablicę Uint8Array
// Pliki > 5 MiB są automatycznie dzielone na części wieloczęściowe
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { klucz, wiadro, adres URL, rozmiar, typ_zawartości, etag }

// Zastąp istniejący plik należący do bieżącego użytkownika
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// Lista plików pod prefiksem/folderem
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// Pobierz plik jako obiekt Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// Pobieranie strumieniowe bez ładowania całego pliku do pamięci
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// Usuń plik (domyślnie przeniesiony do kosza z 30-dniowym okresem przechowywania)
await bucket.remove([`${user.id}/2026-10.pdf`])

// Trwałe usunięcie (pomija kosz i natychmiast zwalnia miejsce na dysku)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

Kluczowe zachowania w czasie wykonywania:

  • Przesyłanie istniejącej ścieżki zwraca 409 CONFLICT, chyba że podano upsert: true.
  • Anonimowe przesyłanie jest odrzucane z 403 FORBIDDEN zarówno w zasobnikach prywatnych, jak i publicznych (zapis wymaga uwierzytelnionego JWT lub klucza usługi).
  • Ochrona przed przejściem ścieżki: ścieżki zawierające .. lub niedozwolone znaki zwracają 400 INVALID_PATH bez zgłaszania nieobsługiwanych wyjątków.
  • Izolacja użytkownika: jeden użytkownik nie może nadpisywać ani usuwać plików należących do innego użytkownika (owner_id = auth.uid()). Strukturuj ścieżki przy użyciu folderów o zasięgu użytkownika, takich jak ${user.id}/....

Udostępnij plik (publiczne i podpisane adresy URL)#

share.tstypescript
// 1. Wiadro publiczne: bezpośredni stały adres URL (podawany bez kluczy API)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// Wymuś pobranie jako załącznika z niestandardową nazwą pliku
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. Wiadro prywatne: adres URL podpisany HMAC z konfigurowalnym TTL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // Ważne przez 300 sekund (5 minut)
  { download: true }
)
// data.signedUrl i data.url zawierają podpisany adres URL HMAC

// 3. Przesyłaj bezpośrednio do przeglądarki bez ujawniania tajnych kluczy
// Po stronie serwera (rola_usługi):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// Klient przeglądarki (nie jest wymagany klucz API):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

Podpisane adresy URL pieczętują metodę HTTP (GET lub PUT), zasobnik, klucz i znacznik czasu wygaśnięcia. Po wygaśnięciu lub usunięciu obiektu żądania otrzymują 403 FORBIDDEN.

Kto co może zrobić (Macierz dostępu)#

DziałanieKlucz anonimowy (anon)Zalogowany użytkownik (authenticated)Rola usługi (service_role)
Odczytaj plik w publicznym zasobnikuTakTakTak
Odczytaj plik w prywatnym zasobnikuNie (403)Tylko właściciel (owner_id = auth.uid())Tak
Prześlij nowy plikNie (403)Tak (staje się właścicielem)Tak
Zamień (upsert) lub usuńNie (403)Tylko właścicielTak
Lista plików w publicznym zasobnikuTakTakTak
Lista plików w prywatnym zasobnikuNie (403)Tylko właściciel (filtr RLS)Tak
Utwórz, zaktualizuj lub usuń zasobnikiNie (403)Nie (403)Tak
Podpisane przez Mint adresy URL przesyłaniaNie (403)Nie (403)Tak

Właściciel jest identyfikowany poprzez podmiot JWT (auth.uid()). Zarówno w zasobnikach publicznych, jak i prywatnych użytkownicy nie mogą nadpisywać ani niszczyć obiektów innych użytkowników.

Przenoś, kopiuj, metadane i kosz#

server/organise.tstypescript
// Skopiuj plik (zachowuje oryginalny typ zawartości i niestandardowe metadane)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// Przenieś lub zmień nazwę pliku
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// Sprawdź metadane obiektu (rozmiar, typ MIME, ETag, niestandardowe metadane)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// Wyświetl listę elementów aktualnie znajdujących się w koszu (przechowywanie przez 30 dni)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// Przywróć obiekt z kosza
await admin.storage.from('invoices').restore('2026/final.pdf')

Informacje na temat transformacji obrazu w czasie rzeczywistym (zmiana rozmiaru, konwersja formatu, obracanie) można znaleźć w dokumentacji Storage SDK Reference.