Télécharger des fichiers avec Cloud Storage sur Flutter

Cloud Storage pour Firebase vous permet de télécharger rapidement et facilement des fichiers vers un bucket Cloud Storage fourni et géré par Firebase.

Télécharger des fichiers

Pour télécharger un fichier sur Cloud Storage, vous créez d'abord une référence au chemin complet du fichier, y compris le nom du fichier.

// 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);

Une fois que vous avez créé une référence appropriée, vous appelez la méthode putFile() , putString() ou putData() pour télécharger le fichier sur Cloud Storage.

Vous ne pouvez pas importer de données avec une référence à la racine de votre bucket Cloud Storage. Votre référence doit pointer vers une URL enfant.

Télécharger à partir d'un fichier

Pour télécharger un fichier, vous devez d'abord obtenir le chemin absolu vers son emplacement sur l'appareil. Par exemple, si un fichier existe dans le répertoire des documents de l'application, utilisez le package path_provider officiel pour générer un chemin de fichier et transmettez-le à 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) {
  // ...
}

Télécharger à partir d'une chaîne

Vous pouvez télécharger des données sous forme de chaîne codée brute, base64 , base64url ou data_url à l'aide de la méthode putString() . Par exemple, pour télécharger une chaîne de texte codée sous forme d'URL de données :

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

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

Téléchargement de données brutes

Vous pouvez télécharger des données typées de niveau inférieur sous la forme d'une Uint8List dans les cas où le téléchargement d'une chaîne ou File n'est pas pratique. Dans ce cas, appelez la méthode putData() avec vos données :

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

Obtenir une URL de téléchargement

Après avoir téléchargé un fichier, vous pouvez obtenir une URL pour télécharger le fichier en appelant la méthode getDownloadUrl() sur Reference :

await mountainsRef.getDownloadURL();

Ajouter des métadonnées de fichier

Vous pouvez également inclure des métadonnées lorsque vous téléchargez des fichiers. Ces métadonnées contiennent des propriétés de métadonnées de fichier typiques telles que contentType (communément appelé type MIME). La méthode putFile() déduit automatiquement le type MIME de l'extension File , mais vous pouvez remplacer le type détecté automatiquement en spécifiant contentType dans les métadonnées. Si vous ne fournissez pas de contentType et que Cloud Storage ne peut pas déduire une valeur par défaut à partir de l'extension de fichier, Cloud Storage utilise application/octet-stream . Voir Utiliser les métadonnées de fichier .

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

Gérer les téléchargements

En plus de démarrer les téléchargements, vous pouvez suspendre, reprendre et annuler les téléchargements à l'aide des méthodes pause() , resume() et cancel() . Les événements de pause et de reprise déclenchent respectivement des changements d'état pause et progress . L'annulation d'un téléchargement entraîne l'échec du téléchargement avec une erreur indiquant que le téléchargement a été annulé.

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');

Surveiller la progression du téléchargement

Vous pouvez écouter le flux d'événements d'une tâche pour gérer le succès, l'échec, la progression ou les pauses de votre tâche de téléchargement :

Type d'événement	Utilisation typique
TaskState.running	Émis périodiquement au fur et à mesure que les données sont transférées et peut être utilisé pour remplir un indicateur de téléchargement/téléchargement.
TaskState.paused	Émis à chaque fois que la tâche est suspendue.
TaskState.success	Émis lorsque la tâche est terminée avec succès.
TaskState.canceled	Émis à chaque fois que la tâche est annulée.
TaskState.error	Émis lorsque le téléchargement a échoué. Cela peut se produire en raison de délais d'attente du réseau, d'échecs d'autorisation ou si vous annulez la tâche.

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;
  }
});

La gestion des erreurs

Il existe un certain nombre de raisons pour lesquelles des erreurs peuvent survenir lors du téléchargement, notamment le fait que le fichier local n'existe pas ou que l'utilisateur n'a pas l'autorisation de télécharger le fichier souhaité. Vous pouvez trouver plus d'informations sur les erreurs dans la section Gérer les erreurs de la documentation.

Exemple complet

Un exemple complet de téléchargement avec suivi de la progression et gestion des erreurs est présenté ci-dessous :

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;
  }
});

Maintenant que vous avez téléchargé des fichiers, apprenons comment les télécharger depuis Cloud Storage.