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.
Créer une référence
Pour télécharger un fichier, créez d'abord une référence Cloud Storage à l'emplacement dans Cloud Storage vers lequel vous souhaitez télécharger le fichier.
Vous pouvez créer une référence en ajoutant des chemins enfants à la racine de votre bucket Cloud Storage :
Rapide
// 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
Objectif 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 pointer vers une URL enfant.
Télécharger des fichiers
Une fois que vous avez une référence, vous pouvez télécharger des fichiers sur Cloud Storage de deux manières :
- Télécharger à partir de données en mémoire
- Importer à partir d'une URL représentant un fichier sur l'appareil
Télécharger à partir de données en mémoire
La méthode putData:metadata:completion:
est le moyen le plus simple de télécharger un fichier sur Cloud Storage. putData:metadata:completion:
prend un objet NSData et renvoie un FIRStorageUploadTask
, que vous pouvez utiliser pour gérer votre téléchargement et surveiller son état.
Rapide
// 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 } } }
Objectif 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; } }]; } }];
Télécharger à partir d'un fichier local
Vous pouvez télécharger des fichiers locaux sur les appareils, tels que des photos et des vidéos de l'appareil photo, avec la méthode putFile:metadata:completion:
putFile:metadata:completion:
prend une NSURL
et renvoie une FIRStorageUploadTask
, que vous pouvez utiliser pour gérer votre téléchargement et surveiller son état.
Rapide
// 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 } } }
Objectif 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 téléchargement, vous pouvez utiliser les méthodes putData:
ou putFile:
et observer la tâche de téléchargement, plutôt que d'utiliser le gestionnaire d'achèvement. Voir Gérer les téléchargements pour plus d'informations.
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 name
, size
et contentType
(communément appelé type MIME). La méthode putFile:
déduit automatiquement le type de contenu à partir de l'extension du 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
. Consultez la section Utiliser les métadonnées de fichier pour plus d’informations sur les métadonnées de fichier.
Rapide
// 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)
Objectif 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 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
. Ces méthodes déclenchent des événements pause
, resume
et cancel
. 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é.
Rapide
// 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()
Objectif 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 du téléchargement
Vous pouvez attacher des observateurs aux FIRStorageUploadTask
afin de surveiller la progression du téléchargement. L'ajout d'un observateur renvoie un FIRStorageHandle
qui peut être utilisé pour supprimer l'observateur.
Rapide
// Add a progress observer to an upload task let observer = uploadTask.observe(.progress) { snapshot in // A progress event occured }
Objectif c
// Add a progress observer to an upload task FIRStorageHandle observer = [uploadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) { // A progress event occurred }];
Ces observateurs peuvent être ajoutés à un événement FIRStorageTaskStatus
:
Événement FIRStorageTaskStatus | Utilisation typique |
---|---|
FIRStorageTaskStatusResume | Cet événement se déclenche lorsque la tâche démarre ou reprend le téléchargement et est souvent utilisé conjointement avec l'événement FIRStorageTaskStatusPause . |
FIRStorageTaskStatusProgress | Cet événement se déclenche à chaque fois que des données sont téléchargées vers Cloud Storage et peut être utilisé pour remplir un indicateur de progression du téléchargement. |
FIRStorageTaskStatusPause | Cet événement se déclenche chaque fois que le téléchargement est interrompu et est souvent utilisé conjointement avec l'événement FIRStorageTaskStatusResume . |
FIRStorageTaskStatusSuccess | Cet événement se déclenche lorsqu'un téléchargement s'est terminé avec succès. |
FIRStorageTaskStatusFailure | Cet événement se déclenche lorsqu'un téléchargement a échoué. Inspectez 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 où l'événement s'est produit. Cet objet contient les propriétés suivantes :
Propriété | Taper | Description |
---|---|---|
progress | NSProgress | Un objet NSProgress contenant la progression du téléchargement. |
error | NSError | Une erreur survenue lors du téléchargement, le cas échéant. |
metadata | FIRStorageMetadata | Pendant le téléchargement, contient des métadonnées en cours de téléchargement. Après un événement FIRTaskStatusSuccess , contient les métadonnées du fichier téléchargé. |
task | FIRStorageUploadTask | La tâche dont il s'agit est un instantané qui peut être utilisé pour gérer ( pause , resume , cancel ) la tâche. |
reference | FIRStorageReference | La référence d'où provient cette tâche. |
Vous pouvez également supprimer des observateurs, soit individuellement, par statut, soit en les supprimant tous.
Rapide
// 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()
Objectif 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 FIRStorageTaskStatusFailure
.
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 :
Rapide
// 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 } } }
Objectif 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 téléchargé des fichiers, apprenons comment les télécharger depuis Cloud Storage.