本頁面由 Cloud Translation API 翻譯而成。

透過 Apple 平台上的 Cloud Storage 下載檔案

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 的檔案取得及更新中繼資料。