Cloud Storage for Firebase 可讓您從 Firebase 提供及管理的 Cloud Storage 值區,輕鬆快速地下載檔案。
可建立參照
如要下載檔案,請先為要下載的檔案建立 Cloud Storage 參考資料。
您可以將子項路徑附加至 Cloud Storage 值區的根目錄,藉此建立參照,或是透過參照 Cloud Storage 中物件的現有 gs://
或 https://
網址建立參照。
Swift
// Create a reference with an initial file path and name let pathReference = storage.reference(withPath: "images/stars.jpg") // Create a reference from a Google Cloud Storage URI let gsReference = storage.reference(forURL: "gs://<your-firebase-storage-bucket>/images/stars.jpg") // Create a reference from an HTTPS URL // Note that in the URL, characters are URL escaped! let httpsReference = storage.reference(forURL: "https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg")
Objective-C
// Create a reference with an initial file path and name FIRStorageReference *pathReference = [storage referenceWithPath:@"images/stars.jpg"]; // Create a reference from a Google Cloud Storage URI FIRStorageReference *gsReference = [storage referenceForURL:@"gs://<your-firebase-storage-bucket>/images/stars.jpg"]; // Create a reference from an HTTPS URL // Note that in the URL, characters are URL escaped! FIRStorageReference *httpsReference = [storage referenceForURL:@"https://firebasestorage.googleapis.com/b/bucket/o/images%20stars.jpg"];
下載檔案
取得參考資料後,您可以透過下列三種方式從 Cloud Storage 下載檔案:
- 下載到記憶體中的
NSData
- 下載到代表裝置上檔案的
NSURL
- 產生可在線上代表檔案的
NSURL
在記憶體中下載
使用 dataWithMaxSize:completion:
方法,將檔案下載至記憶體中的 NSData
物件。這是快速下載檔案最簡單的方式,但必須將整個檔案內容載入記憶體。如果您要求的檔案大於應用程式可用記憶體,應用程式將會當機。為避免記憶體問題,請務必將大小上限設為應用程式可以處理的項目,或使用其他下載方法。
Swift
// Create a reference to the file you want to download let islandRef = storageRef.child("images/island.jpg") // Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes) islandRef.getData(maxSize: 1 * 1024 * 1024) { data, error in if let error = error { // Uh-oh, an error occurred! } else { // Data for "images/island.jpg" is returned let image = UIImage(data: data!) } }
Objective-C
// Create a reference to the file you want to download FIRStorageReference *islandRef = [storageRef child:@"images/island.jpg"]; // Download in memory with a maximum allowed size of 1MB (1 * 1024 * 1024 bytes) [islandRef dataWithMaxSize:1 * 1024 * 1024 completion:^(NSData *data, NSError *error){ if (error != nil) { // Uh-oh, an error occurred! } else { // Data for "images/island.jpg" is returned UIImage *islandImage = [UIImage imageWithData:data]; } }];
下載至本機檔案
writeToFile:completion:
方法會將檔案直接下載到本機裝置。如果使用者想在離線期間存取檔案,或在其他應用程式中分享檔案,請使用這個選項。writeToFile:completion:
會傳回 FIRStorageDownloadTask
,供您管理下載作業及監控上傳作業狀態。
Swift
// Create a reference to the file you want to download let islandRef = storageRef.child("images/island.jpg") // Create local filesystem URL let localURL = URL(string: "path/to/image")! // Download to the local filesystem let downloadTask = islandRef.write(toFile: localURL) { url, error in if let error = error { // Uh-oh, an error occurred! } else { // Local file URL for "images/island.jpg" is returned } }
Objective-C
// Create a reference to the file you want to download FIRStorageReference *islandRef = [storageRef child:@"images/island.jpg"]; // Create local filesystem URL NSURL *localURL = [NSURL URLWithString:@"path/to/image"]; // Download to the local filesystem FIRStorageDownloadTask *downloadTask = [islandRef writeToFile:localURL completion:^(NSURL *URL, NSError *error){ if (error != nil) { // Uh-oh, an error occurred! } else { // Local file URL for "images/island.jpg" is returned } }];
如要主動管理下載內容,可以使用 writeToFile:
方法並觀察下載工作,而不要使用完成處理常式。詳情請參閱管理下載項目。
產生下載網址
如果您已擁有以網址為基礎的下載基礎架構,或是單純想分享網址,則可對 Cloud Storage 參考資料呼叫 downloadURLWithCompletion:
方法,以取得檔案的下載網址。
Swift
// Create a reference to the file you want to download let starsRef = storageRef.child("images/stars.jpg") // Fetch the download URL starsRef.downloadURL { url, error in if let error = error { // Handle any errors } else { // Get the download URL for 'images/stars.jpg' } }
Objective-C
// Create a reference to the file you want to download FIRStorageReference *starsRef = [storageRef child:@"images/stars.jpg"]; // Fetch the download URL [starsRef downloadURLWithCompletion:^(NSURL *URL, NSError *error){ if (error != nil) { // Handle any errors } else { // Get the download URL for 'images/stars.jpg' } }];
使用 FirebaseUI 下載映像檔
FirebaseUI 提供簡單、可自訂且可用於實際工作環境的原生行動繫結,能夠消除樣板程式碼並推廣 Google 最佳做法。使用 FirebaseUI 與 SDWebImage 整合之後,您就能快速輕鬆地從 Cloud Storage 下載、快取及顯示圖片。
首先,請將 FirebaseUI 新增至您的 Podfile
:
pod 'FirebaseStorageUI'
然後您就能直接從 Cloud Storage 將圖片載入 UIImageView
:
Swift
// Reference to an image file in Firebase Storage let reference = storageRef.child("images/stars.jpg") // UIImageView in your ViewController let imageView: UIImageView = self.imageView // Placeholder image let placeholderImage = UIImage(named: "placeholder.jpg") // Load the image using SDWebImage imageView.sd_setImage(with: reference, placeholderImage: placeholderImage)
Objective-C
// Reference to an image file in Firebase Storage FIRStorageReference *reference = [storageRef child:@"images/stars.jpg"]; // UIImageView in your ViewController UIImageView *imageView = self.imageView; // Placeholder image UIImage *placeholderImage; // Load the image using SDWebImage [imageView sd_setImageWithStorageReference:reference placeholderImage:placeholderImage];
管理下載內容
除了開始下載,您還可以使用 pause
、resume
和 cancel
方法暫停、繼續及取消下載。這些方法會引發您可以觀察的 pause
、resume
和 cancel
事件。
Swift
// Start downloading a file let downloadTask = storageRef.child("images/mountains.jpg").write(toFile: localFile) // Pause the download downloadTask.pause() // Resume the download downloadTask.resume() // Cancel the download downloadTask.cancel()
Objective-C
// Start downloading a file FIRStorageDownloadTask *downloadTask = [[storageRef child:@"images/mountains.jpg"] writeToFile:localFile]; // Pause the download [downloadTask pause]; // Resume the download [downloadTask resume]; // Cancel the download [downloadTask cancel];
監控下載進度
您可以將觀察器附加至 FIRStorageDownloadTask
,以監控下載進度。新增觀察器會傳回 FIRStorageHandle
,可用於移除觀察器。
Swift
// Add a progress observer to a download task let observer = downloadTask.observe(.progress) { snapshot in // A progress event occurred }
Objective-C
// Add a progress observer to a download task FIRStorageHandle observer = [downloadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) { // A progress event occurred }];
這些觀察器可以登錄到 FIRStorageTaskStatus
事件:
「FIRStorageTaskStatus」事件 | 一般用量 |
---|---|
FIRStorageTaskStatusResume |
這個事件會在工作開始或繼續下載時觸發,通常會與 FIRStorageTaskStatusPause 事件搭配使用。 |
FIRStorageTaskStatusProgress |
從 Cloud Storage 下載資料時,這個事件就會觸發,並可用來填入下載進度指標。 |
FIRStorageTaskStatusPause |
這個事件會在下載暫停時觸發,通常會與 FIRStorageTaskStatusResume 事件搭配使用。 |
FIRStorageTaskStatusSuccess |
下載成功時,就會觸發這個事件。 |
FIRStorageTaskStatusFailure |
下載失敗時,就會觸發這個事件。請查看錯誤來判斷失敗原因。 |
事件發生時,系統會回傳 FIRStorageTaskSnapshot
物件。此快照是在事件發生時,無法變更的工作檢視畫面。這個物件包含下列屬性:
屬性 | 類型 | 說明 |
---|---|---|
progress |
NSProgress |
包含下載進度的 NSProgress 物件。 |
error |
NSError |
下載期間發生錯誤 (如果有的話)。 |
metadata |
FIRStorageMetadata |
nil 。 |
task |
FIRStorageDownloadTask |
這是一項工作的快照,可用於管理 (pause 、resume 、cancel ) 工作。 |
reference |
FIRStorageReference |
這項工作的參照。 |
您也可以將觀察器依狀態、或全部移除,來移除個別觀察器。
Swift
// Create a task listener handle let observer = downloadTask.observe(.progress) { snapshot in // A progress event occurred } // Remove an individual observer downloadTask.removeObserver(withHandle: observer) // Remove all observers of a particular status downloadTask.removeAllObservers(for: .progress) // Remove all observers downloadTask.removeAllObservers()
Objective-C
// Create a task listener handle FIRStorageHandle observer = [downloadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) { // A progress event occurred }]; // Remove an individual observer [downloadTask removeObserverWithHandle:observer]; // Remove all observers of a particular status [downloadTask removeAllObserversForStatus:FIRStorageTaskStatusProgress]; // Remove all observers [downloadTask removeAllObservers];
為避免記憶體流失,所有觀察器都會在 FIRStorageTaskStatusSuccess
或 FIRStorageTaskStatusFailure
發生後移除。
處理錯誤
導致下載錯誤的原因有很多,包括檔案不存在,或使用者沒有存取所需檔案的權限。如要進一步瞭解錯誤,請參閱說明文件的「處理錯誤」一節。
完整範例
以下完整範例說明如何下載到含有錯誤處理的本機檔案:
Swift
// Create a reference to the file we want to download let starsRef = storageRef.child("images/stars.jpg") // Start the download (in this case writing to a file) let downloadTask = storageRef.write(toFile: localURL) // Observe changes in status downloadTask.observe(.resume) { snapshot in // Download resumed, also fires when the download starts } downloadTask.observe(.pause) { snapshot in // Download paused } downloadTask.observe(.progress) { snapshot in // Download reported progress let percentComplete = 100.0 * Double(snapshot.progress!.completedUnitCount) / Double(snapshot.progress!.totalUnitCount) } downloadTask.observe(.success) { snapshot in // Download completed successfully } // Errors only occur in the "Failure" case downloadTask.observe(.failure) { snapshot in guard let errorCode = (snapshot.error as? NSError)?.code else { return } guard let error = StorageErrorCode(rawValue: errorCode) else { return } switch (error) { case .objectNotFound: // File doesn't exist break case .unauthorized: // User doesn't have permission to access file break case .cancelled: // User cancelled the download break /* ... */ case .unknown: // Unknown error occurred, inspect the server response break default: // Another error occurred. This is a good place to retry the download. break } }
Objective-C
// Create a reference to the file we want to download FIRStorageReference *starsRef = [storageRef child:@"images/stars.jpg"]; // Start the download (in this case writing to a file) FIRStorageDownloadTask *downloadTask = [storageRef writeToFile:localURL]; // Observe changes in status [downloadTask observeStatus:FIRStorageTaskStatusResume handler:^(FIRStorageTaskSnapshot *snapshot) { // Download resumed, also fires when the download starts }]; [downloadTask observeStatus:FIRStorageTaskStatusPause handler:^(FIRStorageTaskSnapshot *snapshot) { // Download paused }]; [downloadTask observeStatus:FIRStorageTaskStatusProgress handler:^(FIRStorageTaskSnapshot *snapshot) { // Download reported progress double percentComplete = 100.0 * (snapshot.progress.completedUnitCount) / (snapshot.progress.totalUnitCount); }]; [downloadTask observeStatus:FIRStorageTaskStatusSuccess handler:^(FIRStorageTaskSnapshot *snapshot) { // Download completed successfully }]; // Errors only occur in the "Failure" case [downloadTask observeStatus:FIRStorageTaskStatusFailure handler:^(FIRStorageTaskSnapshot *snapshot) { if (snapshot.error != nil) { switch (snapshot.error.code) { case FIRStorageErrorCodeObjectNotFound: // File doesn't exist break; case FIRStorageErrorCodeUnauthorized: // User doesn't have permission to access file break; case FIRStorageErrorCodeCancelled: // User canceled the upload break; /* ... */ case FIRStorageErrorCodeUnknown: // Unknown error occurred, inspect the server response break; } } }];
您也可以為儲存在 Cloud Storage 的檔案取得及更新中繼資料。