Importer des fichiers avec Cloud Storage sur Android

Cloud Storage for Firebase vous permet d'importer rapidement et facilement des fichiers dans un Cloud Storage bucket 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.

Kotlin

// 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 // falseStorageActivity.kt

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());    // falseStorageActivity.java

Une fois que vous avez créé une référence appropriée, appelez la méthode putBytes(), putFile(), ou putStream() pour importer le fichier dans Cloud Storage.

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

Importer des données en mémoire

La méthode putBytes() est le moyen le plus simple d'importer un fichier dans Cloud Storage. putBytes() accepte un byte[] et renvoie un UploadTask que vous pouvez utiliser pour gérer et surveiller l'état de l'importation.

Kotlin

// 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.
    // ...
}StorageActivity.kt

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.
        // ...
    }
});StorageActivity.java

Étant donné que putBytes() accepte un byte[], votre application doit contenir l'intégralité du contenu d'un fichier en mémoire à la fois. Envisagez d'utiliser putStream() ou putFile() pour utiliser moins de mémoire.

Importer à partir d'un flux

La méthode putStream() est le moyen le plus polyvalent d'importer un fichier dans Cloud Storage. putStream() accepte un InputStream et renvoie un UploadTask que vous pouvez utiliser pour gérer et surveiller l'état de l'importation.

Kotlin

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.
    // ...
}StorageActivity.kt

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.
        // ...
    }
});StorageActivity.java

Importer un fichier local

Vous pouvez importer des fichiers locaux sur l'appareil, tels que des photos et des vidéos de l'appareil photo, à l'aide de la méthode putFile(). putFile() accepte un File et renvoie un UploadTask que vous pouvez utiliser pour gérer et surveiller l'état de l'importation.

Kotlin

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.
    // ...
}StorageActivity.kt

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.
        // ...
    }
});StorageActivity.java

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 le StorageReference :

Kotlin

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
        // ...
    }
}StorageActivity.kt

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
            // ...
        }
    }
});StorageActivity.java

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 (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 de 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 des métadonnées de fichier.

Kotlin

// 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)StorageActivity.kt

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);StorageActivity.java

Gérer les importations

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

Kotlin

uploadTask = storageRef.child("images/mountains.jpg").putFile(file)

// Pause the upload
uploadTask.pause()

// Resume the upload
uploadTask.resume()

// Cancel the upload
uploadTask.cancel()StorageActivity.kt

Java

uploadTask = storageRef.child("images/mountains.jpg").putFile(file);

// Pause the upload
uploadTask.pause();

// Resume the upload
uploadTask.resume();

// Cancel the upload
uploadTask.cancel();StorageActivity.java

Surveiller la progression de l'importation

Vous pouvez ajouter des écouteurs pour gérer les réussites, les échecs, la progression ou les pauses dans votre tâche d'importation :

Type d'écouteur	Utilisation type
`OnProgressListener`	Cet écouteur est appelé périodiquement lors du transfert des données et peut être utilisé pour remplir un indicateur d'importation/de téléchargement.
`OnPausedListener`	Cet écouteur est appelé chaque fois que la tâche est mise en pause.
`OnSuccessListener`	Cet écouteur est appelé lorsque la tâche est terminée.
`OnFailureListener`	Cet écouteur est appelé chaque fois que l'importation a échoué. 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é	Type	Description
`getDownloadUrl`	`String`	URL qui peut être utilisée pour télécharger l'objet. Il s'agit d'une URL publique impossible à deviner qui peut être partagée avec d'autres clients. Cette valeur est renseignée une fois l'importation terminée.
`getError`	`Exception`	Si la tâche a échoué, la cause sera une exception.
`getBytesTransferred`	`long`	Nombre total d'octets transférés lorsque cet instantané a été pris.
`getTotalByteCount`	`long`	Nombre total d'octets à importer.
`getUploadSessionUri`	`String`	URI qui peut être utilisé pour poursuivre cette tâche via un autre appel à putFile.
`getMetadata`	`StorageMetadata`	Avant la fin d'une importation, il s'agit des métadonnées envoyées au serveur. Une fois l'importation terminée, il s'agit des métadonnées renvoyées par le serveur.
`getTask`	`UploadTask`	Tâche qui a créé cet instantané. Utilisez cette tâche pour annuler, mettre en pause ou reprendre l'importation.
`getStorage`	`StorageReference`	`StorageReference` utilisé pour créer le `UploadTask`.

Les écouteurs d'événements UploadTask offrent un moyen simple et puissant de surveiller les événements d'importation.

Kotlin

// Observe state change events such as progress, pause, and resume
// You'll need to import com.google.firebase.storage.component1 and
// com.google.firebase.storage.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")
}StorageActivity.kt

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");
    }
});StorageActivity.java

Gérer les modifications du cycle de vie des activités

Les importations se poursuivent en arrière-plan, même après les modifications du cycle de vie des activités (par exemple , l'affichage d'une boîte de dialogue ou la rotation de l'écran). Tous les écouteurs que vous avez associés resteront également associés. Cela peut entraîner des résultats inattendus s'ils sont appelés après l'arrêt de l'activité.

Pour résoudre ce problème, abonnez vos écouteurs avec un champ d'application d'activité afin de les désinscrire automatiquement lorsque l'activité s'arrête. Ensuite, utilisez la méthode getActiveUploadTasks lorsque l'activité redémarre pour obtenir les tâches d'importation qui sont toujours en cours d'exécution ou qui ont été récemment terminées.

L'exemple ci-dessous illustre ce point et montre également comment conserver le chemin d'accès de la référence de stockage utilisée.

Kotlin

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!
            // ...
        }
    }
}UploadActivity.kt

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!
                // ...
            }
        });
    }
}UploadActivity.java

getActiveUploadTasks récupère toutes les tâches d'importation actives au niveau de la référence fournie et en dessous. Vous devrez peut-être gérer plusieurs tâches.

Poursuivre les importations lors des redémarrages de processus

Si votre processus est arrêté, toutes les importations en cours seront interrompues. Toutefois, vous pouvez continuer à importer une fois le processus redémarré en reprenant la session d'importation avec le serveur. Cela permet de gagner du temps et de la bande passante en ne démarrant pas l'importation au début du fichier.

Pour ce faire, commencez l'importation via putFile. Sur le StorageTask résultant, appelez getUploadSessionUri et enregistrez la valeur obtenue dans un stockage persistant (tel que SharedPreferences).

Kotlin

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.
    }
}UploadActivity.kt

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.
        }
    }
});UploadActivity.java

Une fois votre processus redémarré avec une importation interrompue, appelez à nouveau putFile. Mais cette fois, transmettez également l'URI qui a été enregistré.

Kotlin

// 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,
)UploadActivity.kt

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);UploadActivity.java

Les sessions durent une semaine. Si vous tentez de reprendre une session après son expiration ou si elle a rencontré une erreur, vous recevrez un rappel d'échec. Il vous incombe de vous assurer que le fichier n'a pas changé entre les importations.

Traitement des erreurs

Plusieurs raisons peuvent expliquer les erreurs lors de l'importation, y compris l'absence de fichier local ou le manque d'autorisation de l'utilisateur pour 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 :

Kotlin

// 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.component1 and
// com.google.firebase.storage.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
    // ...
}StorageActivity.kt

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
        // ...
    }
});StorageActivity.java

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

Importer des fichiers avec Cloud Storage sur Android Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.