Importer des fichiers avec Cloud Storage sur Android

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.

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 // 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 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 pointer vers une URL enfant.

Importer à partir de données en mémoire

La méthode putBytes() est le moyen le plus simple d'importer un fichier dans Cloud Storage. putBytes() utilise 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.
    // ...
}

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

Comme putBytes() accepte un byte[], votre application doit conserver l'intégralité du contenu d'un fichier en mémoire en même temps. Envisagez d'utiliser putStream() ou putFile() pour réduire l'utilisation de la mémoire.

Importer à partir d'un flux

La méthode putStream() est la plus polyvalente pour importer un fichier dans Cloud Storage. putStream() utilise 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.
    // ...
}

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

Importer depuis 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() utilise 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.
    // ...
}

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 importé un fichier, vous pouvez obtenir une URL pour le télécharger en appelant la méthode getDownloadUrl() sur 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
        // ...
    }
}

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 importez des fichiers. Ces métadonnées contiennent des propriétés de métadonnées de fichier standards telles que name, size et contentType (communément appelées "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. Pour en savoir plus sur les métadonnées de fichier, consultez la section Utiliser les 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)

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 importations

En plus de lancer 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 déclenchent respectivement les changements d'état pause et progress. L'annulation d'une importation entraîne l'échec de l'importation avec une erreur indiquant que l'importation 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()

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 de l'importation

Vous pouvez ajouter des écouteurs pour gérer la réussite, l'échec, la progression ou les pauses de votre tâche d'importation :

Type d'écouteur Utilisation standard
OnProgressListener Cet écouteur est appelé régulièrement lors du transfert des données et peut être utilisé pour renseigner 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 s'est terminée avec succès.
OnFailureListener Cet écouteur est appelé chaque fois que l'importation échoue. Cela peut se produire en raison de délais d'inactivité 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 permettant de 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 indiquée sous la forme d'une exception.
getBytesTransferred long Nombre total d'octets transférés au moment où cet instantané a été pris.
getTotalByteCount long Nombre total d'octets à importer.
getUploadSessionUri String URI pouvant ê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, suspendre ou reprendre l'importation.
getStorage StorageReference StorageReference utilisé pour créer le UploadTask.

Les écouteurs d'événements UploadTask offrent un moyen simple et efficace 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")
}

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 d'une activité

Les importations se poursuivent en arrière-plan même après des modifications du cycle de vie de l'activité (par exemple, l'affichage d'une boîte de dialogue ou la rotation de l'écran). Tous les écouteurs que vous aviez 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, vous pouvez abonner 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 de référence de stockage utilisé.

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

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 d'importation actives au niveau de la référence fournie et en dessous. Vous devrez donc 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 l'importation une fois le processus redémarré en reprenant la session d'importation avec le serveur. Cela peut vous faire gagner du temps et économiser de la bande passante en évitant de recommencer l'importation depuis le début du fichier.

Pour ce faire, commencez l'importation via putFile. Sur le StorageTask obtenu, appelez getUploadSessionUri et enregistrez la valeur obtenue dans un espace de 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.
    }
}

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

Une fois que votre processus redémarre 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,
)

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 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 est de votre responsabilité de vous assurer que le fichier n'a pas été modifié entre les importations.

Gestion des exceptions

Plusieurs raisons peuvent expliquer l'apparition d'erreurs lors de l'importation, par exemple l'absence du fichier local ou l'absence 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 exceptions :

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

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 importé des fichiers, découvrez comment les télécharger depuis Cloud Storage.