Importer des fichiers avec Cloud Storage sur Flutter

Cloud Storage for Firebase vous permet d'importer rapidement et facilement des fichiers dans un bucket Cloud Storage fourni et géré par Firebase.

Importer des fichiers

Pour importer un fichier dans Cloud Storage, vous devez d'abord créer une référence au chemin d'accès complet du fichier, y compris son nom.

// 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, appelez la méthode putFile(), putString() ou putData() pour importer le fichier dans Cloud Storage.

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

Importer à partir d'un fichier

Pour importer 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 officiel path_provider pour générer un chemin d'accès au fichier et le transmettre à 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) {
  // ...
}

Importer à partir d'une chaîne

Vous pouvez importer des données sous forme de chaîne brute encodée au format base64, base64url ou data_url à l'aide de la méthode putString(). Par exemple, pour importer une chaîne de texte encodé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) {
  // ...
}

Importer des données brutes

Vous pouvez importer des données typées de niveau inférieur sous la forme d'un Uint8List dans les cas où l'importation d'une chaîne ou d'un 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 importé un fichier, vous pouvez obtenir une URL pour le télécharger en appelant la méthode getDownloadUrl() au niveau de Reference:

await mountainsRef.getDownloadURL();

Ajouter des métadonnées de fichier

Vous pouvez également inclure des métadonnées lorsque vous importez des fichiers. Ces métadonnées contiennent des propriétés de métadonnées de fichier classiques telles que contentType (communément appelées type MIME). La méthode putFile() déduit automatiquement le type MIME à partir 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. Consultez la page Utiliser des métadonnées de fichier.

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

Gérer les importations

En plus de démarrer des importations, vous pouvez les suspendre, les reprendre et les annuler à l'aide des méthodes pause(), resume() et cancel(). Les événements de mise en veille et de reprise génèrent respectivement des changements d'état pause et progress. L'annulation d'une importation entraîne l'échec de l'importation et une erreur indiquant qu'elle a été annulée.

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 de l'importation

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

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

Traitement des erreurs

Plusieurs raisons peuvent expliquer l'apparition d'erreurs lors de l'importation, par exemple si le fichier local n'existe pas ou si l'utilisateur n'est pas autorisé à importer le fichier souhaité. Pour en savoir plus sur les erreurs, consultez la section Gérer les erreurs de la documentation.

Exemple complet

Vous trouverez ci-dessous un exemple complet d'importation avec surveillance de la progression et gestion des erreurs:

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 importé des fichiers, découvrons comment les télécharger à partir de Cloud Storage.