下載切片物件

下載大型檔案的其中一種策略稱為「切片物件下載」。在這種下載方式中，系統會平行發出範圍 GET 要求，並將資料儲存在預先分配的臨時目標檔案中。所有切片下載完畢後，系統會將暫存檔重新命名為目的地檔案。

切片物件下載功能可同時移轉物件的各個部分，加快下載整個物件的速度。您無法使用切片物件下載功能，只下載物件的特定切片或位元組範圍。如要下載或讀取物件的特定部分，請參閱「下載物件的一部分」或「讀取物件」。

如果網路和磁碟速度不是限制因素，切片物件下載速度可能會大幅提升；不過，切片物件下載會導致磁碟上多個位置發生多次寫入，因此這項下載策略可能會降低搜尋時間緩慢的磁碟效能，尤其是將下載作業分成大量切片時。Google Cloud CLI 等工具建立的分塊數量預設值較低，可盡量降低對效能的影響。

驗證資料完整性

下載切片物件時，一律應使用快速可組合核對和 (CRC32C)，驗證切片的資料完整性。如要執行切片物件下載作業，gcloud CLI 等工具必須在執行下載作業的機器上編譯 crcmod。如果無法使用已編譯的 crcmod，gcloud CLI 會改為執行非切片物件下載作業。

如要進一步瞭解如何對物件讀取作業執行資料驗證，請參閱「資料讀取作業的總和檢查碼」。

工具和 API 如何使用切片物件下載功能

視您與 Cloud Storage 的互動方式而定，系統可能會自動代您管理切片物件下載作業。本節說明不同工具的切片物件下載行為，並提供修改行為的相關資訊。

控制台

Google Cloud 控制台不會執行切片物件下載。

指令列

根據預設，gcloud storage cp 會啟用切片物件下載功能。您可以修改下列屬性，控管 gcloud CLI 執行分塊物件下載作業的方式和時機：

  • storage/sliced_object_download_threshold：執行物件切片下載作業的檔案大小總和下限。如要停用所有切片物件下載，請將這個值設為 0。

  • storage/sliced_object_download_max_components：下載時可使用的切片數量上限。如要不設限制，請將 0 設為 0，這樣切片數量就只會由 storage/sliced_object_download_component_size 決定。

  • storage/sliced_object_download_component_size：每個下載片段的目標大小。如果檔案總大小過大，導致下載這個大小的切片時，需要的切片數量會超過 storage/sliced_object_download_max_components 中設定的上限，系統就會忽略這項屬性。

如要修改這些屬性，請建立命名設定，然後使用 --configuration 專案層級旗標，逐一將設定套用至各個指令，或使用 gcloud config set 指令，將設定套用至所有 gcloud CLI 指令。

使用 gcloud CLI 執行分片物件下載作業時，不需要額外的本機磁碟空間。如果下載作業在完成前失敗，請再次執行指令，繼續下載失敗的部分。如果重試，系統不會重新下載先前成功下載的切片，除非來源物件在下載嘗試之間發生變化。

暫時下載的物件會顯示在目標目錄中，名稱後方加上 _.gstmp 後置字串。

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

只要將 AllowDivideAndConquer 設為 true，即可下載切片物件。例如：

import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.transfermanager.DownloadResult;
import com.google.cloud.storage.transfermanager.ParallelDownloadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import java.nio.file.Path;
import java.util.List;

class AllowDivideAndConquerDownload {

  public static void divideAndConquerDownloadAllowed(
      List<BlobInfo> blobs, String bucketName, Path destinationDirectory) {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowDivideAndConquerDownload(true)
            .build()
            .getService();
    ParallelDownloadConfig parallelDownloadConfig =
        ParallelDownloadConfig.newBuilder()
            .setBucketName(bucketName)
            .setDownloadDirectory(destinationDirectory)
            .build();
    List<DownloadResult> results =
        transferManager.downloadBlobs(blobs, parallelDownloadConfig).getDownloadResults();

    for (DownloadResult result : results) {
      System.out.println(
          "Download of "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

詳情請參閱「Cloud Storage Node.js API 參考文件」。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

您可以使用 downloadFileInChunks 方法，下載經過切片的物件。例如：

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of the GCS file to download
// const fileName = 'your-file-name';

// The path to which the file should be downloaded
// const destFileName = '/local/path/to/file.txt';

// The size of each chunk to be downloaded
// const chunkSize = 1024;

// Imports the Google Cloud client library
const {Storage, TransferManager} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function downloadFileInChunksWithTransferManager() {
  // Downloads the files
  await transferManager.downloadFileInChunks(fileName, {
    destination: destFileName,
    chunkSizeBytes: chunkSize,
  });

  console.log(
    `gs://${bucketName}/${fileName} downloaded to ${destFileName}.`
  );
}

downloadFileInChunksWithTransferManager().catch(console.error);

Python

詳情請參閱 Cloud Storage Python API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

您可以使用 download_chunks_concurrently 方法，下載切片物件。例如：

def download_chunks_concurrently(
    bucket_name, blob_name, filename, chunk_size=32 * 1024 * 1024, workers=8
):
    """Download a single file in chunks, concurrently in a process pool."""

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The file to be downloaded
    # blob_name = "target-file"

    # The destination filename or path
    # filename = ""

    # The size of each chunk. The performance impact of this value depends on
    # the use case. The remote service has a minimum of 5 MiB and a maximum of
    # 5 GiB.
    # chunk_size = 32 * 1024 * 1024 (32 MiB)

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case, but smaller files usually
    # benefit from a higher number of processes. Each additional process occupies
    # some CPU and memory resources until finished. Threads can be used instead
    # of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    transfer_manager.download_chunks_concurrently(
        blob, filename, chunk_size=chunk_size, max_workers=workers
    )

    print("Downloaded {} to {}.".format(blob_name, filename))

REST API

JSON API 和 XML API 都支援範圍 GET 要求，因此您可以使用任一 API 實作自己的物件切片下載策略。

為避免下載期間來源物件變更導致資料損毀，請在每個物件片段的下載要求中，提供來源物件的版本編號。