Cloud Storage for Firebase vous permet de télécharger rapidement et facilement des fichiers à partir d'un bucket Cloud Storage fourni et géré par Firebase.
Créer une référence
Pour télécharger un fichier, commencez par créer une référence Cloud Storage au fichier que vous souhaitez télécharger.
Vous pouvez créer une référence en ajoutant des chemins d'accès enfants à la racine de votre bucket Cloud Storage, ou à partir d'une URL gs:// ou https:// existante référençant un objet dans Cloud Storage.
// Create a reference with an initial file path and name
StorageReference path_reference = storage->GetReference("images/stars.jpg");
// Create a reference from a Cloud Storage URI
StorageReference gs_reference = storage->GetReferenceFromUrl("gs://bucket/images/stars.jpg");
// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
StorageReference https_reference = storage->GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");
Télécharger les fichiers
Une fois que vous disposez d'une référence, vous pouvez télécharger des fichiers depuis Cloud Storage de trois manières différentes:
- Télécharger dans un tampon en mémoire
- Télécharger dans un chemin spécifique sur l'appareil
- Générer une URL de chaîne représentant le fichier en ligne
Télécharger en mémoire
Téléchargez le fichier dans un tampon d'octets en mémoire à l'aide de la méthode GetBytes(). Il s'agit du moyen le plus simple de télécharger rapidement un fichier, mais il doit charger l'intégralité du contenu de votre fichier en mémoire. Si vous demandez un fichier plus volumineux que la mémoire disponible de votre application, celle-ci plantera. Pour vous protéger contre les problèmes de mémoire, veillez à définir la taille maximale sur une valeur que votre application peut gérer, ou utilisez une autre méthode de téléchargement.
// Create a reference to the file you want to download
StorageReference island_ref = storage_ref.Child("images/island.jpg");
// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes)
const size_t kMaxAllowedSize = 1 * 1024 * 1024
int8_t byte_buffer[kMaxAllowedSize];
firebase::Future future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);
Au moment où la requête a été effectuée, nous devons attendre la fin de la Future avant de pouvoir lire le fichier. Étant donné que les jeux s'exécutent généralement en boucle et sont moins basés sur les rappels que les autres applications, vous effectuez généralement une requête pour vérifier l'achèvement.
// In the game loop that polls for the result...
if (future.status() != firebase::kFutureStatusPending) {
if (future.status() != firebase::kFutureStatusComplete) {
LogMessage("ERROR: GetBytes() returned an invalid future.");
// Handle the error...
} else if (future.Error() != firebase::storage::kErrorNone) {
LogMessage("ERROR: GetBytes() returned error %d: %s", future.Error(),
future.error_message());
// Handle the error...
} else {
// byte_buffer is now populated with data for "images/island.jpg"
}
}
Télécharger dans un fichier local
La méthode GetFile() télécharge un fichier directement sur un appareil local. Utilisez-la si vos utilisateurs souhaitent accéder au fichier hors connexion ou le partager dans une autre application.
// Create a reference to the file you want to download
StorageReference islandRef = storage_ref.Child("images/island.jpg"];
// Create local filesystem URL
const char* local_url = "file:///local/images/island.jpg";
// Download to the local filesystem
Future future = islandRef.GetFile(local_url);
// Wait for Future to complete...
if (future.Error() != firebase::storage::kErrorNone) {
// Uh-oh, an error occurred!
} else {
// The file has been downloaded to local file URL "images/island.jpg"
}
GetFile() accepte un argument Controller facultatif que vous pouvez utiliser pour gérer votre téléchargement. Pour en savoir plus, consultez la section Gérer les téléchargements.
Générer une URL de téléchargement
Si vous disposez déjà d'une infrastructure de téléchargement basée sur des URL ou si vous souhaitez simplement partager une URL, vous pouvez obtenir l'URL de téléchargement d'un fichier en appelant la méthode GetDownloadUrl() sur une référence Cloud Storage.
// Create a reference to the file you want to download
StorageReference stars_ref = storage_ref.Child("images/stars.jpg");
// Fetch the download URL
firebase::Future future = stars_ref.GetDownloadUrl();
// Wait for Future to complete...
if (future.Error() != firebase::storage::kErrorNone) {
// Uh-oh, an error occurred!
} else {
// Get the download URL for 'images/stars.jpg'
std::string download_url = future.Result();
}
Gérer les téléchargements
En plus de démarrer les téléchargements, vous pouvez les suspendre, les reprendre et les annuler à l'aide des méthodes Pause(), Resume() et Cancel() sur Controller, que vous pouvez éventuellement transmettre aux méthodes GetBytes() ou GetFile().
// Start downloading a file
Controller controller;
storage_ref.Child("images/mountains.jpg").GetFile(local_file, nullptr, &controller);
// Pause the download
controller.Pause();
// Resume the download
controller.Resume();
// Cancel the download
controller.Cancel();
Surveiller la progression du téléchargement
Vous pouvez associer des écouteurs aux téléchargements afin de surveiller leur progression.
class MyListener : public firebase::storage::Listener {
public:
virtual void OnProgress(firebase::storage::Controller* controller) {
// A progress event occurred
}
};
{
// Start uploading a file
MyEventListener my_listener;
storage_ref.Child("images/mountains.jpg").GetFile(local_file, my_listener);
}
Gérer les erreurs
Plusieurs raisons peuvent expliquer l'apparition d'erreurs lors du téléchargement, y compris l'absence de fichier ou l'absence d'autorisation de l'utilisateur pour accéder au fichier souhaité. Pour en savoir plus sur les erreurs, consultez la section Gérer les erreurs de la documentation.
Étapes suivantes
Vous pouvez également obtenir et mettre à jour des métadonnées pour les fichiers stockés dans Cloud Storage.