Cloud Storage for Firebase 可讓您快速輕鬆地從 Firebase 提供及管理的 Cloud Storage 儲存體下載檔案。
可建立參照
如要下載檔案,請先建立要下載檔案的 Cloud Storage 參照。
您可以將子路徑附加至 Cloud Storage 值區的根目錄,藉此建立參照,也可以從現有的 gs://
或 https://
網址建立參照,以便參照 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");
下載檔案
取得參照後,您可以透過下列三種方式下載 Cloud Storage 中的檔案:
- 下載至記憶體中的緩衝區
- 下載至裝置上的特定路徑
- 產生代表檔案的線上字串網址
在記憶體中下載
使用 GetBytes()
方法,將檔案下載至記憶體中的位元組緩衝區。這是快速下載檔案最簡單的方式,但必須將檔案的整個內容載入記憶體中。如果您要求的檔案大小超過應用程式可用的記憶體,應用程式就會當機。為避免記憶體問題,請務必將最大大小設為應用程式可處理的大小,或使用其他下載方法。
// 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<size_t> future = island_ref.GetBytes(byte_buffer, kMaxAllowedSize);
在要求完成時,我們必須等待 Future 完成,才能讀取檔案。由於遊戲通常會以迴圈執行,且比其他應用程式更少使用回呼,因此您通常會輪詢完成狀態。
// 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" } }
下載至本機檔案
GetFile()
方法會將檔案直接下載到本機裝置。如果使用者想在離線時存取檔案,或在其他應用程式中分享檔案,請使用這個選項。
// 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<size_t> 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()
會使用非必要的 Controller
引數,您可以用這個引數管理下載作業。詳情請參閱「管理下載內容」。
產生下載網址
如果您已經有以網址為基礎的下載基礎架構,或是只想取得要分享的網址,您可以在 Cloud Storage 參照上呼叫 GetDownloadUrl()
方法,取得檔案的下載網址。
// 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<std::string> 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(); }
管理下載內容
除了開始下載作業,您還可以使用 Controller
上的 Pause()
、Resume()
和 Cancel()
方法暫停、繼續及取消下載作業,並視需要將這些方法傳遞至 GetBytes()
或 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();
監控下載進度
您可以將事件監聽器附加至下載作業,以便監控下載進度。
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); }
處理錯誤
下載時可能會發生錯誤,原因有很多,包括檔案不存在,或使用者沒有權限存取所需檔案。如要進一步瞭解錯誤,請參閱文件中的「處理錯誤」一節。
後續步驟
您也可以取得及更新中繼資料,適用於儲存在 Cloud Storage 中的檔案。