Carica file con Cloud Storage su Flutter

Cloud Storage for Firebase ti consente di caricare file in modo semplice e rapido in un bucket Cloud Storage fornito e gestito da Firebase.

Nota: per impostazione predefinita, un bucket Cloud Storage for Firebase richiede Firebase Authentication per eseguire qualsiasi azione sui dati o sui file del bucket. Puoi sostituire Firebase Security Rules con Cloud Storage per consentire l'accesso non autenticato per situazioni specifiche. Tuttavia, per la maggior parte delle situazioni, ti consigliamo vivamente di limitare l'accesso e configurare regole di sicurezza efficaci (soprattutto per le app di produzione). Tieni presente che se utilizzi Google App Engine e hai un bucket Cloud Storage predefinito con un formato del nome *.appspot.com, potresti dover considerare in che modo le tue regole di sicurezza influiscono sull'accesso ai file App Engine.

Nota: per i progetti con piano Spark, Firebase blocca il caricamento e l'hosting di determinati tipi di file eseguibili per Windows (file con estensioni .exe, .dll e .bat), Android (estensione .apk) e Apple (estensione .ipa) da Cloud Storage for Firebase e Firebase Hosting. Queste norme hanno lo scopo di prevenire gli abusi sulla nostra piattaforma. I progetti nel piano Blaze non sono interessati. Per ulteriori informazioni, consulta queste domande frequenti.

Carica file

Per caricare un file su Cloud Storage, devi prima creare un riferimento al percorso completo del file, incluso il nome.

// Create a storage reference from our app
final storageRef = FirebaseStorage.instance.ref();

// Create a reference to "mountains.jpg"
final mountainsRef = storageRef.child("mountains.jpg");

// Create a reference to 'images/mountains.jpg'
final mountainImagesRef = storageRef.child("images/mountains.jpg");

// While the file names are the same, the references point to different files
assert(mountainsRef.name == mountainImagesRef.name);
assert(mountainsRef.fullPath != mountainImagesRef.fullPath);

Dopo aver creato un riferimento appropriato, chiama il metodo putFile(), putString() o putData() per caricare il file su Cloud Storage.

Non puoi caricare dati con un riferimento alla radice del tuo bucket Cloud Storage. Il riferimento deve indirizzare a un URL secondario.

Carica da un file

Per caricare un file, devi prima recuperare il percorso assoluto della relativa posizione sul dispositivo. Ad esempio, se esiste un file nella directory dei documenti dell'applicazione, utilizza il pacchetto ufficiale path_provider per generare un percorso del file e passarlo a putFile():

Directory appDocDir = await getApplicationDocumentsDirectory();
String filePath = '${appDocDir.absolute}/file-to-upload.png';
File file = File(filePath);

try {
  await mountainsRef.putFile(file);
} on firebase_core.FirebaseException catch (e) {
  // ...
}

Carica da una stringa

Puoi caricare i dati come stringa non elaborata, codificata in base64, base64url o data_url utilizzando il metodo putString(). Ad esempio, per caricare una stringa di testo codificata come URL di dati:

String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';

try {
  await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
  // ...
}

Caricamento dei dati non elaborati

Puoi caricare dati di tipo inferiore sotto forma di Uint8List nei casi in cui non sia pratico caricare una stringa o File. In questo caso, chiama il metodo putData() con i tuoi dati:

try {
  // Upload raw data.
  await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
  // ...
}

Ottenere un URL di download

Dopo aver caricato un file, puoi ottenere un URL per scaricarlo chiamando il metodo getDownloadUrl() su Reference:

await mountainsRef.getDownloadURL();

Aggiungere metadati dei file

Puoi anche includere i metadati quando carichi i file. Questi metadati contengono proprietà di metadati dei file tipiche come contentType (comunemente noto come tipo MIME). Il metodo putFile() ricava automaticamente il tipo MIME dall'estensione File, ma puoi sostituire il tipo rilevato automaticamente specificando contentType nei metadati. Se non fornisci un valore contentType e Cloud Storage non può dedurre un valore predefinito dall'estensione del file, Cloud Storage utilizza application/octet-stream. Consulta Utilizzare i metadati dei file.

try {
  await mountainsRef.putFile(file, SettableMetadata(
    contentType: "image/jpeg",
  ));
} on firebase_core.FirebaseException catch (e) {
  // ...
}

Gestisci caricamenti

Oltre ad avviare i caricamenti, puoi metterli in pausa, riprenderli e annullarli utilizzando i metodi pause(), resume() e cancel(). Gli eventi di messa in pausa e ripresa attivano rispettivamente le modifiche di stato pause e progress. L'annullamento di un caricamento ne causa il fallimento con un errore che indica che il caricamento è stato annullato.

final task = mountainsRef.putFile(largeFile);

// Pause the upload.
bool paused = await task.pause();
print('paused, $paused');

// Resume the upload.
bool resumed = await task.resume();
print('resumed, $resumed');

// Cancel the upload.
bool canceled = await task.cancel();
print('canceled, $canceled');

Monitorare l'avanzamento del caricamento

Puoi ascoltare lo stream di eventi di un'attività per gestire l'esito positivo, l'errore, l'avanzamento o le interruzioni dell'attività di caricamento:

Tipo di evento	Utilizzo tipico
TaskState.running	Viene emesso periodicamente durante il trasferimento dei dati e può essere utilizzato per compilare un indicatore di caricamento/download.
TaskState.paused	Viene emesso ogni volta che l'attività viene messa in pausa.
TaskState.success	Viene emesso quando l'attività è stata completata correttamente.
TaskState.canceled	Viene emesso ogni volta che l'attività viene annullata.
TaskState.error	Viene emesso quando il caricamento non è riuscito. Ciò può verificarsi a causa di timeout di rete, errori di autorizzazione o se annulli l'attività.

mountainsRef.putFile(file).snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // ...
      break;
    case TaskState.paused:
      // ...
      break;
    case TaskState.success:
      // ...
      break;
    case TaskState.canceled:
      // ...
      break;
    case TaskState.error:
      // ...
      break;
  }
});

Gestione degli errori

Esistono diversi motivi per cui potrebbero verificarsi errori durante il caricamento, ad esempio il file locale non esiste o l'utente non dispone dell'autorizzazione per caricare il file desiderato. Puoi trovare ulteriori informazioni sugli errori nella sezione Gestire gli errori della documentazione.

Esempio completo

Di seguito è riportato un esempio completo di caricamento con monitoraggio dell'avanzamento e gestione degli errori:

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/path/to/mountains.jpg";
final file = File(filePath);

// Create the file metadata
final metadata = SettableMetadata(contentType: "image/jpeg");

// Create a reference to the Firebase Storage bucket
final storageRef = FirebaseStorage.instance.ref();

// Upload file and metadata to the path 'images/mountains.jpg'
final uploadTask = storageRef
    .child("images/path/to/mountains.jpg")
    .putFile(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.snapshotEvents.listen((TaskSnapshot taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      final progress =
          100.0 * (taskSnapshot.bytesTransferred / taskSnapshot.totalBytes);
      print("Upload is $progress% complete.");
      break;
    case TaskState.paused:
      print("Upload is paused.");
      break;
    case TaskState.canceled:
      print("Upload was canceled");
      break;
    case TaskState.error:
      // Handle unsuccessful uploads
      break;
    case TaskState.success:
      // Handle successful uploads on complete
      // ...
      break;
  }
});

Ora che hai caricato i file, scopri come scaricarli da Cloud Storage.