This page describes how to use the Cloud Storage for Firebase SDK to download files from a Cloud Storage bucket.
Create a reference
To download a file, first create a Cloud Storage reference to the file you want to download.
You can create a reference by appending child paths to the root of your
Cloud Storage bucket, or you can create a reference from an existing
gs:// or https:// URL referencing an object in Cloud Storage.
// Create a reference with an initial file path and name StorageReference pathReference = storage.GetReference("images/stars.jpg"); // Create a reference from a Google Cloud Storage URI StorageReference gsReference = storage.GetReferenceFromUrl("gs://bucket/images/stars.jpg"); // Create a reference from an HTTPS URL // Note that in the URL, characters are URL escaped! StorageReference httpsReference = storage.GetReferenceFromUrl("https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg");
Download files
Once you have a reference, you can download files from Cloud Storage in four ways:
- Download from a URL
- Download to a byte array
- Download with a Stream
- Download to a local file
The method you will use to retrieve your files will depend on how you want to consume the data in your game.
Download from a URL
If you want to use a URL with Unity's
WWW or
UnityWebRequest,
you can get a download URL for a file by calling GetDownloadUrlAsync().
// Fetch the download URL reference.GetDownloadUrlAsync().ContinueWithOnMainThread(task => { if (!task.IsFaulted && !task.IsCanceled) { Debug.Log("Download URL: " + task.Result); // ... now download the file via WWW or UnityWebRequest. } });
Download to a byte array
You can download the file to a byte buffer in memory using the
GetBytesAsync() method. This method loads the entire contents of your file
into memory. If you request a file larger than your app's available memory, your
app will crash. To protect against memory issues, make sure to set the max size
to something you know your app can handle, or use another download method.
// Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes) const long maxAllowedSize = 1 * 1024 * 1024; reference.GetBytesAsync(maxAllowedSize).ContinueWithOnMainThread(task => { if (task.IsFaulted || task.IsCanceled) { Debug.LogException(task.Exception); // Uh-oh, an error occurred! } else { byte[] fileContents = task.Result; Debug.Log("Finished downloading!"); } });
Download via a stream
Downloading the file with a Stream lets you process the data as it's loaded.
This gives you maximum flexibility when dealing with your download. Call
GetStreamAsync and pass your own stream processor as the first argument. This
delegate will get called on a background thread with a Stream which lets you
perform latency-intensive operations or calculations such as storing the
contents to disk.
// Download via a Stream reference.GetStreamAsync(stream => { // Do something with the stream here. // // This code runs on a background thread which reduces the impact // to your framerate. // // If you want to do something on the main thread, you can do that in the // progress eventhandler (second argument) or ContinueWith to execute it // at task completion. }, null, CancellationToken.None);
GetStreamAsync() takes an optional argument after the stream processor that
lets you cancel the operation or get notified of progress.
Download to a local file
The GetFileAsync() method downloads a file directly to a local device. Use
this if your users want to have access to the file while offline or to share
the file in a different app.
// Create local filesystem URL string localUrl = "file:///local/images/island.jpg"; // Download to the local filesystem reference.GetFileAsync(localUrl).ContinueWithOnMainThread(task => { if (!task.IsFaulted && !task.IsCanceled) { Debug.Log("File downloaded."); } });
You can attach listeners to downloads in order to monitor the progress of the
download. The listener follows the standard System.IProgress<T>
interface. You can use an instance of the StorageProgress class, to provide
your own Action<T> as a callback for progress ticks.
// Create local filesystem URL string localUrl = "file:///local/images/island.jpg"; // Start downloading a file Task task = reference.GetFileAsync(localFile, new StorageProgress<DownloadState>(state => { // called periodically during the download Debug.Log(String.Format( "Progress: {0} of {1} bytes transferred.", state.BytesTransferred, state.TotalByteCount )); }), CancellationToken.None); task.ContinueWithOnMainThread(resultTask => { if (!resultTask.IsFaulted && !resultTask.IsCanceled) { Debug.Log("Download finished."); } });
Error handling
There are a number of reasons why errors might occur on download, including the file not existing, or the user not having permission to access the intended file. For more information about errors, see Handle errors.
Next steps
You can also get and update metadata for files that are stored in Cloud Storage.