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 avec une 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 de 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, base64, base64url ou data_url encodé à l'aide de la méthode putString(). Par exemple, pour importer une chaîne de texte encodée en tant qu'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 lorsque 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() sur 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 typiques telles que contentType (généralement 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 de valeur par défaut à partir de l'extension de fichier, Cloud Storage utilise application/octet-stream. Consultez 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 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 pause et de reprise génèrent respectivement des modifications d'état pause et progress. Si vous annulez une importation, celle-ci échoue et une erreur indique 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:

Type d'événement	Utilisation type
TaskState.running	Émis périodiquement lors du transfert de données et peut être utilisé pour renseigner un indicateur d'importation/de téléchargement.
TaskState.paused	Émis chaque fois que la tâche est mise en veille.
TaskState.success	Émis lorsque la tâche est terminée.
TaskState.canceled	Émis chaque fois que la tâche est annulée.
TaskState.error	Émis en cas d'échec de l'importation. Cela peut se produire en raison d'expirations de délais d'attente 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;
  }
});

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écouvrez comment les télécharger depuis Cloud Storage.