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.
Kotlin+KTX
// Create a storage reference from our app val storageRef = storage.reference // Create a reference to "mountains.jpg" val mountainsRef = storageRef.child("mountains.jpg") // Create a reference to 'images/mountains.jpg' val 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.path == mountainImagesRef.path // false
Java
// Create a storage reference from our app StorageReference storageRef = storage.getReference(); // Create a reference to "mountains.jpg" StorageReference mountainsRef = storageRef.child("mountains.jpg"); // Create a reference to 'images/mountains.jpg' StorageReference mountainImagesRef = storageRef.child("images/mountains.jpg"); // While the file names are the same, the references point to different files mountainsRef.getName().equals(mountainImagesRef.getName()); // true mountainsRef.getPath().equals(mountainImagesRef.getPath()); // false
Une fois que vous avez créé une référence appropriée, vous appelez la méthode putBytes()
, putFile()
ou putStream()
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 de données en mémoire
La méthode putBytes()
est le moyen le plus simple de télécharger un fichier sur Cloud Storage. putBytes()
prend un byte[]
et renvoie une UploadTask
que vous pouvez utiliser pour gérer et surveiller l'état du téléchargement.
Kotlin+KTX
// Get the data from an ImageView as bytes imageView.isDrawingCacheEnabled = true imageView.buildDrawingCache() val bitmap = (imageView.drawable as BitmapDrawable).bitmap val baos = ByteArrayOutputStream() bitmap.compress(Bitmap.CompressFormat.JPEG, 100, baos) val data = baos.toByteArray() var uploadTask = mountainsRef.putBytes(data) uploadTask.addOnFailureListener { // Handle unsuccessful uploads }.addOnSuccessListener { taskSnapshot -> // taskSnapshot.metadata contains file metadata such as size, content-type, etc. // ... }
Java
// Get the data from an ImageView as bytes imageView.setDrawingCacheEnabled(true); imageView.buildDrawingCache(); Bitmap bitmap = ((BitmapDrawable) imageView.getDrawable()).getBitmap(); ByteArrayOutputStream baos = new ByteArrayOutputStream(); bitmap.compress(Bitmap.CompressFormat.JPEG, 100, baos); byte[] data = baos.toByteArray(); UploadTask uploadTask = mountainsRef.putBytes(data); uploadTask.addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception exception) { // Handle unsuccessful uploads } }).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() { @Override public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) { // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc. // ... } });
Étant donné que putBytes()
accepte un byte[]
, votre application doit conserver l'intégralité du contenu d'un fichier en mémoire à la fois. Pensez à utiliser putStream()
ou putFile()
pour utiliser moins de mémoire.
Télécharger à partir d'un flux
La méthode putStream()
est le moyen le plus polyvalent de télécharger un fichier sur Cloud Storage. putStream()
prend un InputStream
et renvoie une UploadTask
que vous pouvez utiliser pour gérer et surveiller l'état du téléchargement.
Kotlin+KTX
val stream = FileInputStream(File("path/to/images/rivers.jpg")) uploadTask = mountainsRef.putStream(stream) uploadTask.addOnFailureListener { // Handle unsuccessful uploads }.addOnSuccessListener { taskSnapshot -> // taskSnapshot.metadata contains file metadata such as size, content-type, etc. // ... }
Java
InputStream stream = new FileInputStream(new File("path/to/images/rivers.jpg")); uploadTask = mountainsRef.putStream(stream); uploadTask.addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception exception) { // Handle unsuccessful uploads } }).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() { @Override public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) { // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc. // ... } });
Télécharger à partir d'un fichier local
Vous pouvez télécharger des fichiers locaux sur l'appareil, tels que des photos et des vidéos de l'appareil photo, avec la méthode putFile()
. putFile()
prend un File
et renvoie une UploadTask
que vous pouvez utiliser pour gérer et surveiller l'état du téléchargement.
Kotlin+KTX
var file = Uri.fromFile(File("path/to/images/rivers.jpg")) val riversRef = storageRef.child("images/${file.lastPathSegment}") uploadTask = riversRef.putFile(file) // Register observers to listen for when the download is done or if it fails uploadTask.addOnFailureListener { // Handle unsuccessful uploads }.addOnSuccessListener { taskSnapshot -> // taskSnapshot.metadata contains file metadata such as size, content-type, etc. // ... }
Java
Uri file = Uri.fromFile(new File("path/to/images/rivers.jpg")); StorageReference riversRef = storageRef.child("images/"+file.getLastPathSegment()); uploadTask = riversRef.putFile(file); // Register observers to listen for when the download is done or if it fails uploadTask.addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception exception) { // Handle unsuccessful uploads } }).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() { @Override public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) { // taskSnapshot.getMetadata() contains file metadata such as size, content-type, etc. // ... } });
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 StorageReference
:
Kotlin+KTX
val ref = storageRef.child("images/mountains.jpg") uploadTask = ref.putFile(file) val urlTask = uploadTask.continueWithTask { task -> if (!task.isSuccessful) { task.exception?.let { throw it } } ref.downloadUrl }.addOnCompleteListener { task -> if (task.isSuccessful) { val downloadUri = task.result } else { // Handle failures // ... } }
Java
final StorageReference ref = storageRef.child("images/mountains.jpg"); uploadTask = ref.putFile(file); Task<Uri> urlTask = uploadTask.continueWithTask(new Continuation<UploadTask.TaskSnapshot, Task<Uri>>() { @Override public Task<Uri> then(@NonNull Task<UploadTask.TaskSnapshot> task) throws Exception { if (!task.isSuccessful()) { throw task.getException(); } // Continue with the task to get the download URL return ref.getDownloadUrl(); } }).addOnCompleteListener(new OnCompleteListener<Uri>() { @Override public void onComplete(@NonNull Task<Uri> task) { if (task.isSuccessful()) { Uri downloadUri = task.getResult(); } else { // Handle failures // ... } } });
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 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
. Consultez la section Utiliser les métadonnées de fichier pour plus d’informations sur les métadonnées de fichier.
Kotlin+KTX
// Create file metadata including the content type var metadata = storageMetadata { contentType = "image/jpg" } // Upload the file and metadata uploadTask = storageRef.child("images/mountains.jpg").putFile(file, metadata)
Java
// Create file metadata including the content type StorageMetadata metadata = new StorageMetadata.Builder() .setContentType("image/jpg") .build(); // Upload the file and metadata uploadTask = storageRef.child("images/mountains.jpg").putFile(file, 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()
. 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é.
Kotlin+KTX
uploadTask = storageRef.child("images/mountains.jpg").putFile(file) // Pause the upload uploadTask.pause() // Resume the upload uploadTask.resume() // Cancel the upload uploadTask.cancel()
Java
uploadTask = storageRef.child("images/mountains.jpg").putFile(file); // Pause the upload uploadTask.pause(); // Resume the upload uploadTask.resume(); // Cancel the upload uploadTask.cancel();
Surveiller la progression du téléchargement
Vous pouvez ajouter des écouteurs pour gérer le succès, l'échec, la progression ou les pauses dans votre tâche de téléchargement :
Type d'auditeur | Utilisation typique |
---|---|
OnProgressListener | Cet écouteur est appelé 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. |
OnPausedListener | Cet écouteur est appelé chaque fois que la tâche est suspendue. |
OnSuccessListener | Cet écouteur est appelé lorsque la tâche est terminée avec succès. |
OnFailureListener | Cet écouteur est appelé chaque fois que le téléchargement échoue. 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. |
OnFailureListener
est appelé avec une instance Exception
. Les autres écouteurs sont appelés avec un objet UploadTask.TaskSnapshot
. Cet objet est une vue immuable de la tâche au moment où l'événement s'est produit. Un UploadTask.TaskSnapshot
contient les propriétés suivantes :
Propriété | Taper | Description |
---|---|---|
getDownloadUrl | String | Une URL qui peut être utilisée pour télécharger l'objet. Il s'agit d'une URL publique indevinable qui peut être partagée avec d'autres clients. Cette valeur est renseignée une fois le téléchargement terminé. |
getError | Exception | Si la tâche échoue, la cause sera une exception. |
getBytesTransferred | long | Nombre total d'octets transférés lors de la prise de cet instantané. |
getTotalByteCount | long | Nombre total d'octets devant être téléchargés. |
getUploadSessionUri | String | Un URI qui peut être utilisé pour poursuivre cette tâche via un autre appel à putFile. |
getMetadata | StorageMetadata | Avant la fin du téléchargement, ce sont les métadonnées qui sont envoyées au serveur. Une fois le téléchargement terminé, ce sont les métadonnées renvoyées par le serveur. |
getTask | UploadTask | Tâche qui a créé cet instantané. Utilisez cette tâche pour annuler, suspendre ou reprendre le téléchargement. |
getStorage | StorageReference | StorageReference utilisé pour créer UploadTask . |
Les écouteurs d'événements UploadTask
offrent un moyen simple et puissant de surveiller les événements de téléchargement.
Kotlin+KTX
// Observe state change events such as progress, pause, and resume // You'll need to import com.google.firebase.storage.ktx.component1 and // com.google.firebase.storage.ktx.component2 uploadTask.addOnProgressListener { (bytesTransferred, totalByteCount) -> val progress = (100.0 * bytesTransferred) / totalByteCount Log.d(TAG, "Upload is $progress% done") }.addOnPausedListener { Log.d(TAG, "Upload is paused") }
Java
// Observe state change events such as progress, pause, and resume uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() { @Override public void onProgress(UploadTask.TaskSnapshot taskSnapshot) { double progress = (100.0 * taskSnapshot.getBytesTransferred()) / taskSnapshot.getTotalByteCount(); Log.d(TAG, "Upload is " + progress + "% done"); } }).addOnPausedListener(new OnPausedListener<UploadTask.TaskSnapshot>() { @Override public void onPaused(UploadTask.TaskSnapshot taskSnapshot) { Log.d(TAG, "Upload is paused"); } });
Gérer les modifications du cycle de vie des activités
Les téléchargements se poursuivent en arrière-plan même après des modifications du cycle de vie des activités (telles que la présentation d'une boîte de dialogue ou la rotation de l'écran). Tous les auditeurs que vous aviez attachés resteront également attachés. Cela pourrait entraîner des résultats inattendus s'ils sont appelés après l'arrêt de l'activité.
Vous pouvez résoudre ce problème en abonnant vos auditeurs avec une étendue d'activité pour les désinscrire automatiquement lorsque l'activité s'arrête. Utilisez ensuite la méthode getActiveUploadTasks
lorsque l'activité redémarre pour obtenir les tâches de téléchargement toujours en cours d'exécution ou récemment terminées.
L'exemple ci-dessous illustre cela et montre également comment conserver le chemin de référence de stockage utilisé.
Kotlin+KTX
override fun onSaveInstanceState(outState: Bundle) { super.onSaveInstanceState(outState) // If there's an upload in progress, save the reference so you can query it later outState.putString("reference", storageRef.toString()) } override fun onRestoreInstanceState(savedInstanceState: Bundle) { super.onRestoreInstanceState(savedInstanceState) // If there was an upload in progress, get its reference and create a new StorageReference val stringRef = savedInstanceState.getString("reference") ?: return storageRef = Firebase.storage.getReferenceFromUrl(stringRef) // Find all UploadTasks under this StorageReference (in this example, there should be one) val tasks = storageRef.activeUploadTasks if (tasks.size > 0) { // Get the task monitoring the upload val task = tasks[0] // Add new listeners to the task using an Activity scope task.addOnSuccessListener(this) { // Success! // ... } } }
Java
@Override protected void onSaveInstanceState(Bundle outState) { super.onSaveInstanceState(outState); // If there's an upload in progress, save the reference so you can query it later if (mStorageRef != null) { outState.putString("reference", mStorageRef.toString()); } } @Override protected void onRestoreInstanceState(Bundle savedInstanceState) { super.onRestoreInstanceState(savedInstanceState); // If there was an upload in progress, get its reference and create a new StorageReference final String stringRef = savedInstanceState.getString("reference"); if (stringRef == null) { return; } mStorageRef = FirebaseStorage.getInstance().getReferenceFromUrl(stringRef); // Find all UploadTasks under this StorageReference (in this example, there should be one) List<UploadTask> tasks = mStorageRef.getActiveUploadTasks(); if (tasks.size() > 0) { // Get the task monitoring the upload UploadTask task = tasks.get(0); // Add new listeners to the task using an Activity scope task.addOnSuccessListener(this, new OnSuccessListener<UploadTask.TaskSnapshot>() { @Override public void onSuccess(UploadTask.TaskSnapshot state) { // Success! // ... } }); } }
getActiveUploadTasks
récupère toutes les tâches de téléchargement actives au niveau et en dessous de la référence fournie, vous devrez donc peut-être gérer plusieurs tâches.
Poursuite des téléchargements lors des redémarrages du processus
Si votre processus est arrêté, tous les téléchargements en cours seront interrompus. Cependant, vous pouvez continuer le téléchargement une fois le processus redémarré en reprenant la session de téléchargement avec le serveur. Cela peut permettre d'économiser du temps et de la bande passante en ne démarrant pas le téléchargement dès le début du fichier.
Pour ce faire, commencez le téléchargement via putFile
. Sur la StorageTask
résultante, appelez getUploadSessionUri
et enregistrez la valeur résultante dans un stockage persistant (tel que SharedPreferences).
Kotlin+KTX
uploadTask = storageRef.putFile(localFile) uploadTask.addOnProgressListener { taskSnapshot -> sessionUri = taskSnapshot.uploadSessionUri if (sessionUri != null && !saved) { saved = true // A persisted session has begun with the server. // Save this to persistent storage in case the process dies. } }
Java
uploadTask = mStorageRef.putFile(localFile); uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() { @Override public void onProgress(UploadTask.TaskSnapshot taskSnapshot) { Uri sessionUri = taskSnapshot.getUploadSessionUri(); if (sessionUri != null && !mSaved) { mSaved = true; // A persisted session has begun with the server. // Save this to persistent storage in case the process dies. } } });
Après le redémarrage de votre processus avec un téléchargement interrompu, appelez à nouveau putFile. Mais cette fois-ci, nous passons aussi par l'Uri qui a été sauvé.
Kotlin+KTX
// resume the upload task from where it left off when the process died. // to do this, pass the sessionUri as the last parameter uploadTask = storageRef.putFile( localFile, storageMetadata { }, sessionUri, )
Java
//resume the upload task from where it left off when the process died. //to do this, pass the sessionUri as the last parameter uploadTask = mStorageRef.putFile(localFile, new StorageMetadata.Builder().build(), sessionUri);
Les séances durent une semaine. Si vous tentez de reprendre une session après son expiration ou si une erreur s'est produite, vous recevrez un rappel d'échec. Il est de votre responsabilité de vous assurer que le fichier n'a pas changé entre les téléchargements.
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 :
Kotlin+KTX
// File or Blob file = Uri.fromFile(File("path/to/mountains.jpg")) // Create the file metadata metadata = storageMetadata { contentType = "image/jpeg" } // Upload file and metadata to the path 'images/mountains.jpg' uploadTask = storageRef.child("images/${file.lastPathSegment}").putFile(file, metadata) // Listen for state changes, errors, and completion of the upload. // You'll need to import com.google.firebase.storage.ktx.component1 and // com.google.firebase.storage.ktx.component2 uploadTask.addOnProgressListener { (bytesTransferred, totalByteCount) -> val progress = (100.0 * bytesTransferred) / totalByteCount Log.d(TAG, "Upload is $progress% done") }.addOnPausedListener { Log.d(TAG, "Upload is paused") }.addOnFailureListener { // Handle unsuccessful uploads }.addOnSuccessListener { // Handle successful uploads on complete // ... }
Java
// File or Blob file = Uri.fromFile(new File("path/to/mountains.jpg")); // Create the file metadata metadata = new StorageMetadata.Builder() .setContentType("image/jpeg") .build(); // Upload file and metadata to the path 'images/mountains.jpg' uploadTask = storageRef.child("images/"+file.getLastPathSegment()).putFile(file, metadata); // Listen for state changes, errors, and completion of the upload. uploadTask.addOnProgressListener(new OnProgressListener<UploadTask.TaskSnapshot>() { @Override public void onProgress(UploadTask.TaskSnapshot taskSnapshot) { double progress = (100.0 * taskSnapshot.getBytesTransferred()) / taskSnapshot.getTotalByteCount(); Log.d(TAG, "Upload is " + progress + "% done"); } }).addOnPausedListener(new OnPausedListener<UploadTask.TaskSnapshot>() { @Override public void onPaused(UploadTask.TaskSnapshot taskSnapshot) { Log.d(TAG, "Upload is paused"); } }).addOnFailureListener(new OnFailureListener() { @Override public void onFailure(@NonNull Exception exception) { // Handle unsuccessful uploads } }).addOnSuccessListener(new OnSuccessListener<UploadTask.TaskSnapshot>() { @Override public void onSuccess(UploadTask.TaskSnapshot taskSnapshot) { // Handle successful uploads on complete // ... } });
Maintenant que vous avez téléchargé des fichiers, apprenons comment les télécharger depuis Cloud Storage.