Importer des fichiers avec Cloud Storage sur les plates-formes Apple

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

Créer une référence

Pour importer un fichier, commencez par créer une référence Cloud Storage vers l'emplacement dans Cloud Storage où vous souhaitez importer le fichier.

Vous pouvez créer une référence en ajoutant des chemins d'accès enfants à la racine de votre bucket Cloud Storage:

Swift

// Create a root reference
let storageRef = storage.reference()

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

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

// While the file names are the same, the references point to different files
mountainsRef.name == mountainImagesRef.name            // true
mountainsRef.fullPath == mountainImagesRef.fullPath    // false

Objective-C

// Create a root reference
FIRStorageReference *storageRef = [storage reference];

// Create a reference to "mountains.jpg"
FIRStorageReference *mountainsRef = [storageRef child:@"mountains.jpg"];

// Create a reference to 'images/mountains.jpg'
FIRStorageReference *mountainImagesRef = [storageRef child:@"images/mountains.jpg"];

// While the file names are the same, the references point to different files
[mountainsRef.name isEqualToString:mountainImagesRef.name];         // true
[mountainsRef.fullPath isEqualToString:mountainImagesRef.fullPath]; // false

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 des fichiers

Une fois que vous disposez d'une référence, vous pouvez importer des fichiers dans Cloud Storage de deux manières:

  1. Importer à partir de données en mémoire
  2. Importer à partir d'une URL représentant un fichier sur l'appareil

Importer à partir de données en mémoire

La méthode putData:metadata:completion: est la méthode la plus simple pour importer un fichier dans Cloud Storage. putData:metadata:completion: prend un objet NSData et renvoie un FIRStorageUploadTask, que vous pouvez utiliser pour gérer votre importation et surveiller son état.

Swift

// Data in memory
let data = Data()

// Create a reference to the file you want to upload
let riversRef = storageRef.child("images/rivers.jpg")

// Upload the file to the path "images/rivers.jpg"
let uploadTask = riversRef.putData(data, metadata: nil) { (metadata, error) in
  guard let metadata = metadata else {
    // Uh-oh, an error occurred!
    return
  }
  // Metadata contains file metadata such as size, content-type.
  let size = metadata.size
  // You can also access to download URL after upload.
  riversRef.downloadURL { (url, error) in
    guard let downloadURL = url else {
      // Uh-oh, an error occurred!
      return
    }
  }
}

Objective-C

// Data in memory
NSData *data = [NSData dataWithContentsOfFile:@"rivers.jpg"];

// Create a reference to the file you want to upload
FIRStorageReference *riversRef = [storageRef child:@"images/rivers.jpg"];

// Upload the file to the path "images/rivers.jpg"
FIRStorageUploadTask *uploadTask = [riversRef putData:data
                                             metadata:nil
                                           completion:^(FIRStorageMetadata *metadata,
                                                        NSError *error) {
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Metadata contains file metadata such as size, content-type, and download URL.
    int size = metadata.size;
    // You can also access to download URL after upload.
    [riversRef downloadURLWithCompletion:^(NSURL * _Nullable URL, NSError * _Nullable error) {
      if (error != nil) {
        // Uh-oh, an error occurred!
      } else {
        NSURL *downloadURL = URL;
      }
    }];
  }
}];

Importer à partir d'un fichier local

Vous pouvez importer des fichiers locaux sur les appareils, tels que des photos et des vidéos de l'appareil photo, à l'aide de la méthode putFile:metadata:completion:. putFile:metadata:completion: prend un NSURL et renvoie un FIRStorageUploadTask, que vous pouvez utiliser pour gérer votre importation et surveiller son état.

Swift

// File located on disk
let localFile = URL(string: "path/to/image")!

// Create a reference to the file you want to upload
let riversRef = storageRef.child("images/rivers.jpg")

// Upload the file to the path "images/rivers.jpg"
let uploadTask = riversRef.putFile(from: localFile, metadata: nil) { metadata, error in
  guard let metadata = metadata else {
    // Uh-oh, an error occurred!
    return
  }
  // Metadata contains file metadata such as size, content-type.
  let size = metadata.size
  // You can also access to download URL after upload.
  riversRef.downloadURL { (url, error) in
    guard let downloadURL = url else {
      // Uh-oh, an error occurred!
      return
    }
  }
}

Objective-C

// File located on disk
NSURL *localFile = [NSURL URLWithString:@"path/to/image"];

// Create a reference to the file you want to upload
FIRStorageReference *riversRef = [storageRef child:@"images/rivers.jpg"];

// Upload the file to the path "images/rivers.jpg"
FIRStorageUploadTask *uploadTask = [riversRef putFile:localFile metadata:nil completion:^(FIRStorageMetadata *metadata, NSError *error) {
  if (error != nil) {
    // Uh-oh, an error occurred!
  } else {
    // Metadata contains file metadata such as size, content-type, and download URL.
    int size = metadata.size;
    // You can also access to download URL after upload.
    [riversRef downloadURLWithCompletion:^(NSURL * _Nullable URL, NSError * _Nullable error) {
      if (error != nil) {
        // Uh-oh, an error occurred!
      } else {
        NSURL *downloadURL = URL;
      }
    }];
  }
}];

Si vous souhaitez gérer activement votre importation, vous pouvez utiliser les méthodes putData: ou putFile: et observer la tâche d'importation, plutôt que d'utiliser le gestionnaire de fin. Pour en savoir plus, consultez Gérer les importations.

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 name, size et contentType (généralement appelées type MIME). La méthode putFile: infère automatiquement le type de contenu à partir de l'extension de nom de fichier NSURL, 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. Pour en savoir plus sur les métadonnées de fichier, consultez la section Utiliser les métadonnées de fichier.

Swift

// Create storage reference
let mountainsRef = storageRef.child("images/mountains.jpg")

// Create file metadata including the content type
let metadata = StorageMetadata()
metadata.contentType = "image/jpeg"

// Upload data and metadata
mountainsRef.putData(data, metadata: metadata)

// Upload file and metadata
mountainsRef.putFile(from: localFile, metadata: metadata)

Objective-C

// Create storage reference
FIRStorageReference *mountainsRef = [storageRef child:@"images/mountains.jpg"];

// Create file metadata including the content type
FIRStorageMetadata *metadata = [[FIRStorageMetadata alloc] init];
metadata.contentType = @"image/jpeg";

// Upload data and metadata
FIRStorageUploadTask *uploadTask = [mountainsRef putData:data metadata:metadata];

// Upload file and metadata
uploadTask = [mountainsRef putFile:localFile metadata:metadata];

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. Ces méthodes génèrent des événements pause, resume et cancel. Si vous annulez une importation, celle-ci échoue et un message d'erreur indique qu'elle a été annulée.

Swift

// Start uploading a file
let uploadTask = storageRef.putFile(from: localFile)

// Pause the upload
uploadTask.pause()

// Resume the upload
uploadTask.resume()

// Cancel the upload
uploadTask.cancel()

Objective-C

// Start uploading a file
FIRStorageUploadTask *uploadTask = [storageRef putFile:localFile];

// Pause the upload
[uploadTask pause];

// Resume the upload
[uploadTask resume];

// Cancel the upload
[uploadTask cancel];

Surveiller la progression de l'importation

Vous pouvez associer des observateurs aux FIRStorageUploadTask pour surveiller la progression de l'importation. L'ajout d'un observateur renvoie un FIRStorageHandle qui peut être utilisé pour supprimer l'observateur.

Swift

// Add a progress observer to an upload task
let observer = uploadTask.observe(.progress) { snapshot in
  // A progress event occured
}

Objective-C

// Add a progress observer to an upload task
FIRStorageHandle observer = [uploadTask observeStatus:FIRStorageTaskStatusProgress
                                              handler:^(FIRStorageTaskSnapshot *snapshot) {
                                                // A progress event occurred
                                              }];

Vous pouvez ajouter les suivants à un événement FIRStorageTaskStatus:

FIRStorageTaskStatus événement Utilisation type
FIRStorageTaskStatusResume Cet événement se déclenche lorsque la tâche commence ou reprend l'importation. Il est souvent utilisé avec l'événement FIRStorageTaskStatusPause.
FIRStorageTaskStatusProgress Cet événement se déclenche chaque fois que des données sont importées dans Cloud Storage et peut être utilisé pour renseigner un indicateur de progression de l'importation.
FIRStorageTaskStatusPause Cet événement se déclenche chaque fois que l'importation est mise en pause et est souvent utilisé avec l'événement FIRStorageTaskStatusResume.
FIRStorageTaskStatusSuccess Cet événement se déclenche lorsqu'une importation a bien été effectuée.
FIRStorageTaskStatusFailure Cet événement se déclenche lorsqu'une importation a échoué. Examinez l'erreur pour déterminer la raison de l'échec.

Lorsqu'un événement se produit, un objet FIRStorageTaskSnapshot est renvoyé. Cet instantané est une vue immuable de la tâche au moment de l'événement. Cet objet contient les propriétés suivantes:

Propriété Type Description
progress NSProgress Objet NSProgress contenant la progression de l'importation.
error NSError Erreur survenue lors de l'importation, le cas échéant.
metadata FIRStorageMetadata Lors de l'importation, les métadonnées sont importées. Après un événement FIRTaskStatusSuccess, contient les métadonnées du fichier importé.
task FIRStorageUploadTask Tâche dont il s'agit d'un instantané, qui peut être utilisée pour la gérer (pause, resume, cancel).
reference FIRStorageReference Référence de cette tâche.

Vous pouvez également supprimer des observateurs, soit individuellement, soit par état, ou en les supprimant tous.

Swift

// Create a task listener handle
let observer = uploadTask.observe(.progress) { snapshot in
  // A progress event occurred
}

// Remove an individual observer
uploadTask.removeObserver(withHandle: observer)

// Remove all observers of a particular status
uploadTask.removeAllObservers(for: .progress)

// Remove all observers
uploadTask.removeAllObservers()

Objective-C

// Create a task listener handle
FIRStorageHandle observer = [uploadTask observeStatus:FIRStorageTaskStatusProgress
                                              handler:^(FIRStorageTaskSnapshot *snapshot) {
                                                // A progress event occurred
                                              }];

// Remove an individual observer
[uploadTask removeObserverWithHandle:observer];

// Remove all observers of a particular status
[uploadTask removeAllObserversForStatus:FIRStorageTaskStatusProgress];

// Remove all observers
[uploadTask removeAllObservers];

Pour éviter les fuites de mémoire, tous les observateurs sont supprimés après un FIRStorageTaskStatusSuccess ou un FIRStorageTaskStatusFailure.

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:

Swift

// Local file you want to upload
let localFile = URL(string: "path/to/image")!

// Create the file metadata
let metadata = StorageMetadata()
metadata.contentType = "image/jpeg"

// Upload file and metadata to the object 'images/mountains.jpg'
let uploadTask = storageRef.putFile(from: localFile, metadata: metadata)

// Listen for state changes, errors, and completion of the upload.
uploadTask.observe(.resume) { snapshot in
  // Upload resumed, also fires when the upload starts
}

uploadTask.observe(.pause) { snapshot in
  // Upload paused
}

uploadTask.observe(.progress) { snapshot in
  // Upload reported progress
  let percentComplete = 100.0 * Double(snapshot.progress!.completedUnitCount)
    / Double(snapshot.progress!.totalUnitCount)
}

uploadTask.observe(.success) { snapshot in
  // Upload completed successfully
}

uploadTask.observe(.failure) { snapshot in
  if let error = snapshot.error as? NSError {
    switch (StorageErrorCode(rawValue: error.code)!) {
    case .objectNotFound:
      // File doesn't exist
      break
    case .unauthorized:
      // User doesn't have permission to access file
      break
    case .cancelled:
      // User canceled the upload
      break

    /* ... */

    case .unknown:
      // Unknown error occurred, inspect the server response
      break
    default:
      // A separate error occurred. This is a good place to retry the upload.
      break
    }
  }
}

Objective-C

// Local file you want to upload
NSURL *localFile = [NSURL URLWithString:@"path/to/image"];

// Create the file metadata
FIRStorageMetadata *metadata = [[FIRStorageMetadata alloc] init];
metadata.contentType = @"image/jpeg";

// Upload file and metadata to the object 'images/mountains.jpg'
FIRStorageUploadTask *uploadTask = [storageRef putFile:localFile metadata:metadata];

// Listen for state changes, errors, and completion of the upload.
[uploadTask observeStatus:FIRStorageTaskStatusResume handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload resumed, also fires when the upload starts
}];

[uploadTask observeStatus:FIRStorageTaskStatusPause handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload paused
}];

[uploadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload reported progress
  double percentComplete = 100.0 * (snapshot.progress.completedUnitCount) / (snapshot.progress.totalUnitCount);
}];

[uploadTask observeStatus:FIRStorageTaskStatusSuccess handler:^(FIRStorageTaskSnapshot *snapshot) {
  // Upload completed successfully
}];

// Errors only occur in the "Failure" case
[uploadTask observeStatus:FIRStorageTaskStatusFailure handler:^(FIRStorageTaskSnapshot *snapshot) {
  if (snapshot.error != nil) {
    switch (snapshot.error.code) {
      case FIRStorageErrorCodeObjectNotFound:
        // File doesn't exist
        break;

      case FIRStorageErrorCodeUnauthorized:
        // User doesn't have permission to access file
        break;

      case FIRStorageErrorCodeCancelled:
        // User canceled the upload
        break;

      /* ... */

      case FIRStorageErrorCodeUnknown:
        // Unknown error occurred, inspect the server response
        break;
    }
  }
}];

Maintenant que vous avez importé des fichiers, découvrez comment les télécharger depuis Cloud Storage.