Cloud Storage for Firebase 可讓您快速輕鬆地從 Firebase 提供及管理的 Cloud Storage 儲存體下載檔案。
可建立參照
如要下載檔案,請先建立要下載檔案的 Cloud Storage 參照。
您可以將子路徑附加至 Cloud Storage 值區的根目錄,藉此建立參照,也可以從現有的 gs://
或 https://
網址建立參照,以便參照 Cloud Storage 中的物件。
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
在記憶體中下載
使用NSData
dataWithMaxSize:completion:
方法。這是快速下載檔案最簡單的方式,但必須將檔案的完整內容載入記憶體中。如果您要求的檔案大於應用程式可用記憶體,您的應用程式會
當機。為避免記憶體問題,請務必設定大小上限
或使用其他程式
下載方法。
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 中的檔案