Firebase Storage: ce este, încărcarea fișierelor și stocarea în cloud

Ce este Firebase Storage și cum funcționează

Firebase Storage este o stocare de obiecte în cloud, construită pe baza Google Cloud Storage, care oferă SDK pentru platformele Android, iOS și web. Fiecare fișier este stocat ca un obiect într-un bucket Google Cloud și este adresat printr-o cale care seamănă cu un sistem de fișiere: gs://bucket-name/path/to/file.jpg. Dimensiunea unui singur fișier poate ajunge la 5 TB, permițând stocarea oricăror date media fără compresie prealabilă.

Arhitectura Firebase Storage utilizează modelul de referință al linkurilor (gsutil references), nu ierarhia clasică de foldere, deși SDK oferă o interfață cu directoare pentru confortul dezvoltatorului. Fizic, toate obiectele sunt stocate într-un spațiu de nume plat al bucketului, iar folderele virtuale sunt create cu ajutorul prefixelor de cale. Aceasta asigură o performanță liniară a căutării, indiferent de numărul de fișiere.

Avantajul cheie al Firebase Storage față de utilizarea directă a Google Cloud Storage este integrarea încorporată cu Firebase Authentication și Security Rules. Dezvoltatorul nu trebuie să configureze roluri IAM separate și conturi de serviciu: regulile de acces se scriu într-un limbaj declarativ, asemănător cu Firebase Realtime Database Rules, și se aplică automat la fiecare cerere.

Structura bucketului și căile către fișiere

Bucketul Firebase Storage se creează automat la conectarea serviciului în consola Firebase. Calea către fișier se construiește după principiul /nume_folder/nume_fișier și poate conține niveluri imbricate. Se recomandă organizarea căilor după schema /users/{userId}/images/{imageId}.jpg pentru izolarea datelor între utilizatori. O astfel de structură simplifică scrierea regulilor de securitate, deoarece calea conține identificatorul proprietarului.

Este important să înțelegeți că Firebase Storage nu este o bază de date relațională sau un server de fișiere în sensul clasic. Este o stocare de obiecte, optimizată pentru operații de citire și scriere a fișierelor întregi. Actualizarea unei părți de fișier este imposibilă: la reîncărcarea cu aceeași cale, obiectul vechi este înlocuit cu cel nou. Pentru stocarea datelor mici structurate, utilizați Firebase Realtime Database sau Cloud Firestore.

Tarifele și limitele Firebase Storage

Prețurile Firebase Storage depind de volumul datelor stocate și de numărul de operații. Tariful gratuit (Spark) include 5 GB de stocare, 20.000 de operații de scriere și 50.000 de operații de citire pe zi. Tariful plătit (Blaze) se plătește în funcție de utilizarea reală: 0,026 $ pe GB de date stocate, 0,05 $ pentru 10.000 de operații de scriere și 0,004 $ pentru 10.000 de operații de citire. În plus, se percepe o taxă pentru traficul de ieșire.

Pentru majoritatea aplicațiilor mobile cu câteva mii de utilizatori, limita gratuită este suficientă în faza de prototipare și testare. La scalarea la sute de mii de utilizatori, costurile Storage depășesc rareori 50–100 $ pe lună cu o abordare optimizată a încărcării și memorând în cache pe partea clientului.

Cum să încărcați fișiere în Firebase Storage

Încărcarea unui fișier în Firebase Storage se realizează prin metoda SDK corespunzătoare, care acceptă calea în stocare și datele fișierului (matrice de octeți, URI, flux sau Bitmap). SDK gestionează automat conexiunea, segmentează fișierul în părți la dimensiuni mari și oferă callback-uri pentru urmărirea progresului. Încărcarea se efectuează direct de pe dispozitivul client pe Google Cloud, ocolind serverul propriu, ceea ce reduce sarcina asupra infrastructurii proprii.

Pentru Android, Firebase Storage SDK utilizează clasele StorageReference și UploadTask. StorageReference se creează din calea rădăcină prin Firebase.storage.reference și indică un fișier specific în bucket. UploadTask returnează ascultători de progres, de pauză și de finalizare. La întreruperea conexiunii, UploadTask reia automat încărcarea de la ultimul octet transmis cu succes — acest comportament se numește reîncărcare reluabilă (resumable upload).

Metadatele fișierului (Content-Type, câmpuri personalizate) se transmit ca un obiect separat SettableMetadata la pornirea încărcării. Setarea corectă a Content-Type este esențială pentru afișarea corectă a fișierelor în browser și funcționarea memorării în cache CDN. Firebase Storage suportă toate tipurile MIME standard: image/jpeg, image/png, video/mp4, application/pdf și altele.

Gestionarea metadatelor la încărcare

Metadatele fișierului conțin câmpuri de sistem (Content-Type, Cache-Control, Content-Disposition) și perechi cheie-valoare personalizate (customMetadata). Câmpurile de sistem controlează antetele HTTP la descărcare. De exemplu, Cache-Control: public, max-age=31536000 activează memorarea în cache a răspunsului pentru un an, ceea ce reduce semnificativ numărul de descărcări repetate ale aceluiași fișier și economisește trafic.

Metadatele personalizate sunt convenabile pentru transmiterea de informații suplimentare despre fișier fără a crea o colecție separată în Firestore. De exemplu, în câmpul uploadedBy puteți salva userId-ul utilizatorului care a încărcat fișierul, ceea ce simplifică implementarea galeriilor cu conținut original. Metadatele personalizate nu sunt protejate separat de Security Rules — accesul la ele este reglementat de aceleași reguli ca și la fișierul propriu-zis.

Încărcarea multiplă și procesarea loturilor

Când este necesară încărcarea mai multor fișiere simultan (de exemplu, fotografii din galerie), nu se recomandă lansarea UploadTask-urilor independente în paralel fără restricții. Pe dispozitivele mobile, încărcarea paralelă a mai mult de 3–5 fișiere duce la suprasolicitarea stivei de rețea și la timeout-uri. Strategia optimă este utilizarea unei limite de concurență de 3 sau încărcarea secvențială cu afișarea unei bare de progres generale.

Pentru procesarea pe server după încărcare (generarea de thumbnails, compresie, moderare a conținutului), utilizați declanșatorul Firebase Cloud Functions: functions.storage.object().onFinalize(). Această funcție este apelată automat după finalizarea încărcării fiecărui fișier și poate salva o copie procesată pe o altă cale. Mai multe detalii în secțiunea despre scenariile tipice.

Descărcarea fișierelor și gestionarea linkurilor

Firebase Storage suportă două moduri de descărcare: descărcarea directă prin SDK cu obținerea unei matrice de octeți sau a unui fișier local și obținerea unui download URL direct pentru acces prin HTTP. URL-ul direct poate fi utilizat pentru afișarea imaginilor în ImageView, în WebView sau pentru furnizarea unui link utilizatorului. Download URL-ul este generat cu un token de securitate care poate fi revocat în consola Firebase.

Metoda storageReference.downloadUrl returnează un URL de forma https://firebasestorage.googleapis.com/v0/b/{bucket}/o/{path}?alt=media&token={token}. Tokenul de securitate este inclus automat în URL la generare, astfel încât linkul poate fi transmis terților (de exemplu, într-un mesager) fără riscul accesului neautorizat. Cu toate acestea, dacă tokenul este compromis, acesta poate fi revocat prin consola Firebase în secțiunea Storage — după aceasta, toate linkurile cu acest token încetează să mai funcționeze.

Pentru memorarea în cache a fișierelor descărcate pe client, utilizați stocarea locală și mecanismul ETag sau hash MD5. Firebase Storage returnează antetul HTTP ETag la cererea unui fișier, care poate fi comparat cu valoarea salvată local pentru a evita descărcarea repetată a fișierelor nemodificate. Acest lucru este util în special pentru conținutul media: avataruri, coperte, previzualizări — fișiere care se actualizează rar, dar sunt solicitate frecvent.

Download URL-urile directe și securitatea lor

Download URL-ul cu token este principala modalitate de a oferi acces la fișiere utilizatorilor neautentificați (de exemplu, pentru afișarea unei imagini într-un flux de știri). Tokenul este generat o singură dată și nu se modifică până la revocare, astfel încât URL-ul poate fi salvat într-o bază de date (de exemplu, lângă câmpul avatarUrl în Firestore). La schimbarea avatarului, fișierul vechi este șters, iar URL-ul nou este generat și salvat.

Este important să rețineți: prezența download URL-ului nu anulează Security Rules. Dacă regula interzice citirea fișierului, metoda downloadUrl va returna o eroare Permission Denied. Aceasta înseamnă că, chiar știind calea corectă către fișier, un client neautentificat nu va putea obține linkul. După obținerea URL-ului, accesul la fișier se realizează prin HTTP, ocolind Security Rules — de aceea tokenul este singura protecție a linkului de descărcare.

Memorarea în cache și lucrul cu ETag

HTTP ETag este un identificator al versiunii fișierului care se modifică la fiecare schimbare a conținutului. Firebase Storage returnează automat ETag în răspunsul la o cerere GET. Aplicația client poate salva ETag-ul în cache-ul local și, la o cerere repetată, poate trimite antetul If-None-Match: {etag}. Dacă fișierul nu s-a modificat, serverul va returna statusul 304 Not Modified fără a transmite date.

Pentru implementarea memorării inteligente în cache într-o aplicație mobilă, utilizați o combinație de sistem de fișiere local și bază de date (de exemplu, Room pentru stocarea perechilor cale-ETag). La descărcarea unui fișier, verificați ETag-l din baza de date: dacă se potrivește cu cel de pe server, utilizați copia locală. O astfel de abordare reduce traficul cu 60–80% pentru fișierele media statice și accelerează încărcarea ecranelor cu galerii.

Reguli de securitate pentru Firebase Storage

Security Rules este un limbaj declarativ de delimitare a accesului la fișierele în Firebase Storage, executat pe partea serverului Firebase. Fiecare regulă este legată de o cale în bucket și definește condițiile în care este permisă operația de citire (read) sau scriere (write). Regulile sunt verificate înaintea fiecărei cereri și nu pot fi ocolite de codul clientului. Aceasta este singura linie de protecție a datelor împotriva accesului neautorizat.

Regula de bază — accesul numai pentru utilizatorii autentificați: allow read, write: if request.auth != null. O astfel de regulă garantează că numai utilizatorii autentificați pot citi și scrie fișiere. Pentru o configurare mai fină, se utilizează variabila request.auth.uid, care conține identificatorul utilizatorului curent. Comparând uid-ul cu o parte a căii către fișier, puteți crea o stocare izolată pentru fiecare utilizator.

Important: Security Rules nu sunt un mecanism de validare a conținutului. Dacă trebuie să verificați tipul fișierului, dimensiunea sau prezența codului malijios, utilizați regula request.resource, care conține metadatele fișierului încărcat. Sunt disponibile proprietățile request.resource.size (dimensiunea fișierului), request.resource.contentType (tipul MIME) și request.resource.md5Hash (suma de control). Cu toate acestea, verificarea completă a conținutului se efectuează pe partea serverului prin Cloud Functions.

Exemplu de reguli pentru conținutul utilizatorilor

Configurația tipică pentru o aplicație cu avataruri și galerii de utilizatori arată astfel. Utilizatorul poate scrie numai în propriul său director /users/{userId}/, dar poate citi orice fișier din acest director (galerie publică). Dimensiunea fișierului este limitată la 5 MB, iar tipul — numai imagini. Această combinație de reguli acoperă 80% din scenariile de utilizare a Firebase Storage în aplicațiile sociale și UGC.

Sfat de securitate: nu utilizați niciodată regula allow read, write: if true pentru întreg bucketul. Aceasta deschide accesul la scriere oricui vă cunoaște projectId. În 2025, au crescut atacurile asupra bucketelor Firebase neprotejate, când atacatorii au folosit accesul deschis pentru stocarea de conținut ilegal. Începeți întotdeauna cu cele mai mici permisiuni necesare și extindeți-le doar la nevoie explicită.

Validarea conținutului prin Cloud Functions

Cloud Functions declanșatorul functions.storage.object().onFinalize() permite efectuarea verificării conținutului după încărcare. Dacă fișierul nu trece de validare (de exemplu, conține un virus sau încalcă regulile platformei), funcția poate să-l șteargă și să notifice utilizatorul. Aceasta este singura modalitate de a verifica conținutul real, deoarece Security Rules văd doar metadatele (dimensiunea și tipul MIME), nu și datele binare.

Exemplu de validare: o funcție în Node.js descarcă fișierul încărcat într-un director temporar, îl rulează printr-un detector antivirus (de exemplu, ClamAV), iar dacă este detectată o amenințare — șterge fișierul și înregistrează evenimentul în Firebase Crashlytics. Timpul de execuție al funcției este limitat la 540 de secunde, ceea ce este suficient pentru verificarea fișierelor de până la 50 MB.

Exemple de cod pentru Firebase Storage în Kotlin

Să analizăm exemple practice de integrare a Firebase Storage într-o aplicație Android în Kotlin. Codul utilizează clasele standard ale Firebase SDK și demonstrează încărcarea unei imagini din galeria dispozitivului, descărcarea unui fișier cu urmărirea progresului și obținerea unui download URL. Toate exemplele includ gestionarea erorilor și suspendarea sarcinilor la pierderea conexiunii.

Înainte de a utiliza codul, asigurați-vă că în fișierul build.gradle a fost adăugată dependența implementation(platform("com.google.firebase:firebase-bom:33.0.0")) și implementation("com.google.firebase:firebase-storage"). Firebase BOM selectează automat versiunile compatibile ale tuturor SDK-urilor, ceea ce elimină conflictele de versiuni.

Încărcarea imaginii din galerie

Primul exemplu — încărcarea unui fișier selectat de utilizator prin Intent ACTION_GET_CONTENT. URI-ul fișierului obținut este transmis către Firebase Storage SDK, care citește singur datele de la acest URI. Metoda putFile acceptă URI-ul și returnează un UploadTask — un obiect prin care puteți urmări progresul, întrerupe și relua încărcarea.

val storageRef = Firebase.storage.reference
val imageRef = storageRef.child(
    "users/${auth.uid}/profile.jpg"
)

val metadata = SettableMetadata().apply {
    contentType = "image/jpeg"
    customMetadata = mapOf(
        "uploadedBy" to auth.uid!!
    )
}

imageRef.putFile(imageUri, metadata)
    .addOnSuccessListener {
        Log.d("Storage", "Fișier încărcat")
    }
    .addOnFailureListener { e ->
        Log.e("Storage", "Eroare: ${e.message}")
    }

În exemplul de mai sus, variabila storageRef este referința rădăcină la bucketul proiectului. Metoda child acceptă un șir de cale și returnează un StorageReference care indică un anumit fișier. Dacă fișierul la calea specificată există deja, acesta va fi suprascris. Metadatele contentType și customMetadata se transmit prin obiectul SettableMetadata, care este atașat cererii putFile.

Descărcarea fișierului cu progres

Al doilea exemplu demonstrează descărcarea unui fișier cu obținerea unei matrice de octeți pentru afișarea în ImageView. Metoda getBytes(<maxSize>) încarcă întreg fișierul în memorie. Pentru fișiere mai mari de 10 MB, utilizați getFile(<localUri>) — acesta salvează conținutul direct într-un fișier local fără a-l stoca în memoria RAM, prevenind OutOfMemoryError.

val islandRef = storageRef.child("images/island.jpg")

val ONE_MEGABYTE: Long = 1024 * 1024
islandRef.getBytes(ONE_MEGABYTE)
    .addOnSuccessListener { bytes ->
        imageView.setImageBitmap(
            BitmapFactory.decodeByteArray(
                bytes, 0, bytes.size
            )
        )
    }
    .addOnFailureListener { e ->
        Log.e("Storage", "Nu s-a putut încărca: ${e.message}")
    }

Pentru obținerea unui download URL (de exemplu, pentru a salva linkul în Firestore), se utilizează metoda downloadUrl:

islandRef.downloadUrl.addOnSuccessListener { uri ->
    Log.d("Storage", "Download URL: $uri")
    // Salvează uri.toString() în Firestore
}

Sfat: downloadUrl este generat o singură dată și este stabil până la revocare. Salvați-l în baza de date la prima încărcare, nu îl solicitați de fiecare dată când afișați fișierul. Aceasta reduce numărul de cereri către Firebase Storage și accelerează interfața.

Scenarii tipice de utilizare a Firebase Storage

Firebase Storage este utilizat în aplicațiile mobile pentru stocarea oricăror fișiere ale utilizatorilor și de sistem. Cele mai frecvente scenarii sunt avatarurile și fotografiile de profil, imaginile în fluxul de conținut, fișierele video și audio, documentele (PDF, DOCX) pentru schimb între utilizatori, precum și backup-ul unui volum mic de date. În toate aceste cazuri, Storage acționează ca un depozit specializat de fișiere în combinație cu Firestore pentru stocarea metadatelor și linkurilor.

Aplicațiile sociale sunt cel mai frecvent caz de utilizare. Fiecare utilizator încarcă un avatar, fotografii ale postărilor și fișiere media. Structura de căi /users/{uid}/posts/{postId}/image.jpg permite izolarea datelor și simplificarea Security Rules. La ștergerea unui utilizator, Cloud Function poate parcurge toate directoarele utilizatorului și curăța stocarea. Potrivit blogului Firebase (2025), acest model este utilizat în 70% din proiectele de producție pe Firebase.

Aplicațiile de comerț electronic utilizează Firebase Storage pentru stocarea fotografiilor produselor, cataloagelor și fișierelor PDF cu instrucțiuni. În acest caz, accesul la fișiere este de obicei public (citire fără autentificare), iar scrierea — numai pentru administratori prin Cloud Functions cu verificare a drepturilor. Download URL-ul produselor este salvat în Firestore lângă celelalte date ale produsului, ceea ce permite afișarea imaginilor fără cereri suplimentare către Storage.

Mesagerii și chat-urile stochează în Firebase Storage imaginile și mesajele vocale trimise în dialoguri. Calea se construiește ca /chats/{chatId}/messages/{messageId}.jpg. Accesul la citire — numai pentru participanții la chat, ceea ce se verifică prin Security Rules cu utilizarea datelor din Firestore. Acesta este unul dintre puținele scenarii în care regula citește date dintr-un alt serviciu Firebase: allow read: if firestore.exists(/databases/(default)/documents/chats/{chatId}/members/{request.auth.uid}).