Cloud Storage for Firebase 可讓您輕鬆快速地將檔案上傳至由 Firebase 提供及管理的 Cloud Storage 值區。
可建立參照
如要上傳檔案,請先建立 Cloud Storage 參考資料至您要上傳檔案的目標位置。
您可以將子項路徑附加至 Cloud Storage 值區的根目錄,藉此建立參照:
// Create a root reference StorageReference storage_ref = storage->GetReference(); // Create a reference to "mountains.jpg" StorageReference mountains_ref = storage_ref.Child("mountains.jpg"); // Create a reference to 'images/mountains.jpg' StorageReference mountain_images_ref = storage_ref.Child("images/mountains.jpg"); // While the file names are the same, the references point to different files mountains_ref.name() == mountain_images_ref.name(); // true mountains_ref.full_path() == mountain_images_ref.full_path(); // false
您無法上傳參照 Cloud Storage 值區根目錄的資料。您的參照必須指向子網址。
上傳檔案
取得參照後,您可以透過下列兩種方式將檔案上傳至 Cloud Storage:
- 從記憶體中的位元組緩衝區上傳
- 從代表裝置上檔案的檔案路徑上傳
從記憶體中的資料上傳
如要將檔案上傳至 Cloud Storage,使用 PutData()
方法是最簡單的方法。PutData()
會擷取位元組緩衝區,並傳回 Future<Metadata>
,其中 Future 完成後會包含檔案相關資訊。您可以使用 Controller
管理上傳作業並監控狀態。
// Data in memory const size_t kByteBufferSize = ... uint8_t byte_buffer[kByteBufferSize] = { ... }; // Create a reference to the file you want to upload StorageReference rivers_ref = storage_ref.Child("images/rivers.jpg"); // Upload the file to the path "images/rivers.jpg" Futurefuture = rivers_ref.PutBytes(byte_buffer, kByteBufferSize);
提出要求時,我們必須等到 Future 完成之後,才能上傳檔案。由於遊戲通常會以迴圈方式執行,且回呼促成的回呼不像其他應用程式,因此一般會輪詢作業是否完成。
if (future.status() != firebase::kFutureStatusPending) { if (future.status() != firebase::kFutureStatusComplete) { LogMessage("ERROR: GetData() returned an invalid future."); // Handle the error... } else if (future.Error() != firebase::storage::kErrorNone) { LogMessage("ERROR: GetData() returned error %d: %s", future.Error(), future.error_message()); // Handle the error... } } else { // Metadata contains file metadata such as size, content-type, and download URL. Metadata* metadata = future.Result(); std::string download_url = metadata->download_url(); } }
從本機檔案上傳
您可以使用 PutFile()
方法上傳裝置上的本機檔案,例如相機中的相片和影片。PutFile()
會使用代表檔案路徑的 std::string
,並傳回 Future<Metadata>
,其中 Future 完成後會包含檔案相關資訊。您可以使用 Controller
管理上傳作業並監控上傳狀態。
// File located on disk std::string local_file = ... // Create a reference to the file you want to upload StorageReference rivers_ref = storage_ref.Child("images/rivers.jpg"); // Upload the file to the path "images/rivers.jpg" Futurefuture = rivers_ref.PutFile(localFile); // Wait for Future to complete... if (future.Error() != firebase::storage::kErrorNone) { // Uh-oh, an error occurred! } else { // Metadata contains file metadata such as size, content-type, and download URL. Metadata* metadata = future.Result(); std::string download_url = metadata->download_url(); }
如要主動管理上傳作業,可提供 Controller
給 PutFile()
或 PutBytes()
方法。這可讓您使用控制器觀察執行中的上傳作業。詳情請參閱「管理上傳項目」。
新增檔案中繼資料
您也可以在上傳檔案時加入中繼資料。這個中繼資料包含一般檔案中繼資料屬性,例如 name
、size
和 content_type
(通常稱為 MIME 類型)。PutFile()
方法會從副檔名自動推論內容類型,但您可以在中繼資料中指定 content_type
,覆寫自動偵測的類型。如未提供 content_type
,且 Cloud Storage 無法從副檔名推斷預設值,Cloud Storage 會使用 application/octet-stream
。如要進一步瞭解檔案中繼資料,請參閱使用檔案中繼資料一節。
// Create storage reference StorageReference mountains_ref = storage_ref.Child("images/mountains.jpg"); // Create file metadata including the content type StorageMetadata metadata; metadata.set_content_type("image/jpeg"); // Upload data and metadata mountains_ref.PutBytes(data, metadata); // Upload file and metadata mountains_ref.PutFile(local_file, metadata);
管理上傳項目
除了開始上傳作業外,您還可以在 Controller
上使用 Pause()
、Resume()
和 Cancel()
方法暫停、繼續及取消上傳作業,並視需要傳遞至 PutBytes()
或 PutFile()
方法。
// Start uploading a file firebase::storage::Controller controller; storage_ref.Child("images/mountains.jpg").PutFile(local_file, nullptr, &controller); // Pause the upload controller.Pause(); // Resume the upload controller.Resume(); // Cancel the upload 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").PutFile(local_file, my_listener); }
處理錯誤
導致上傳發生錯誤的原因有很多,包括本機檔案不存在,或使用者沒有上傳所需檔案的權限。如要進一步瞭解錯誤,請參閱說明文件的處理錯誤一節。
後續步驟
上傳檔案後,不妨進一步瞭解如何從 Cloud Storage 下載這些檔案。