Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

下載物件

本頁面說明如何從 Cloud Storage 的值區下載物件到永久儲存空間。您也可以以互動方式讀取物件或讀取至記憶體。

必要的角色

如要取得下載物件所需的權限，請要求管理員授予您 bucket 的「Storage 物件檢視者」(roles/storage.objectViewer) 角色。如果您打算使用Google Cloud 控制台，請管理員授予您 bucket 的「Storage 管理員」(roles/storage.admin) 角色。

這些角色具備下載物件所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

storage.buckets.list
- 只有使用 Google Cloud 控制台執行本頁面上的工作時，才需要這項權限。
storage.objects.get
storage.objects.list
- 只有使用 Google Cloud 控制台執行本頁面上的工作時，才需要這項權限。

您或許還可透過其他預先定義的角色或自訂角色取得這些權限。

如需授予 bucket 角色的操作說明，請參閱「在 bucket 上設定及管理 IAM 政策」。

從 bucket 下載物件

如要從 bucket 下載物件，請完成下列操作說明：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要下載物件的 bucket 名稱。

系統會開啟「Bucket details」(bucket 詳細資料) 頁面，並選取「Objects」(物件) 分頁標籤。
前往該物件 (可能位於資料夾中)。
按一下與該物件相關的「下載」圖示。

物件的下載位置取決於瀏覽器設定。

如要瞭解如何透過 Google Cloud 控制台取得 Cloud Storage 作業失敗的詳細錯誤資訊，請參閱「疑難排解」一文。

指令列

使用 gcloud storage cp 指令：

gcloud storage cp gs://BUCKET_NAME/OBJECT_NAME SAVE_TO_LOCATION

其中：

BUCKET_NAME 是包含要下載物件的值區名稱。例如：my-bucket。
OBJECT_NAME 是您要下載的物件名稱。例如：pets/dog.png。
SAVE_TO_LOCATION 是您儲存物件的本機路徑。例如：Desktop/Images。

如果成功，回應會類似以下範例：

Completed files 1/1 | 164.3kiB/164.3kiB

如果下載作業在完成前中斷，請執行相同的 cp 指令，從中斷處繼續下載。

用戶端程式庫

C++

詳情請參閱「Cloud Storage C++ API 參考文件」。

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

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  gcs::ObjectReadStream stream = client.ReadObject(bucket_name, object_name);

  int count = 0;
  std::string line;
  while (std::getline(stream, line, '\n')) {
    ++count;
  }
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The object has " << count << " lines\n";
}

C#

詳情請參閱「Cloud Storage C# API 參考文件」。

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


using Google.Cloud.Storage.V1;
using System;
using System.IO;

public class DownloadFileSample
{
    public void DownloadFile(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        string localPath = "my-local-path/my-file-name")
    {
        var storage = StorageClient.Create();
        using var outputFile = File.OpenWrite(localPath);
        storage.DownloadObject(bucketName, objectName, outputFile);
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

Go

詳情請參閱「Cloud Storage Go API 參考文件」。

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

import (
	"context"
	"fmt"
	"io"
	"os"
	"time"

	"cloud.google.com/go/storage"
)

// downloadFile downloads an object to a file.
func downloadFile(w io.Writer, bucket, object string, destFileName string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// destFileName := "file.txt"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	f, err := os.Create(destFileName)
	if err != nil {
		return fmt.Errorf("os.Create: %w", err)
	}

	rc, err := client.Bucket(bucket).Object(object).NewReader(ctx)
	if err != nil {
		return fmt.Errorf("Object(%q).NewReader: %w", object, err)
	}
	defer rc.Close()

	if _, err := io.Copy(f, rc); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}

	if err = f.Close(); err != nil {
		return fmt.Errorf("f.Close: %w", err)
	}

	fmt.Fprintf(w, "Blob %v downloaded to local file %v\n", object, destFileName)

	return nil

}

Java

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

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

以下範例會下載個別物件：


import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.nio.file.Paths;

public class DownloadObject {
  public static void downloadObject(
      String projectId, String bucketName, String objectName, String destFilePath)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The path to which the file should be downloaded
    // String destFilePath = "/local/path/to/file.txt";

    StorageOptions storageOptions = StorageOptions.newBuilder().setProjectId(projectId).build();
    try (Storage storage = storageOptions.getService()) {

      storage.downloadTo(BlobId.of(bucketName, objectName), Paths.get(destFilePath));

      System.out.println(
          "Downloaded object "
              + objectName
              + " from bucket name "
              + bucketName
              + " to "
              + destFilePath);
    }
  }
}

以下範例會使用多個程序下載多個物件：

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 DownloadMany {

  public static void downloadManyBlobs(
      String bucketName, List<BlobInfo> blobs, Path destinationDirectory) throws Exception {

    try (TransferManager transferManager =
        TransferManagerConfig.newBuilder().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());
      }
    }
  }
}

下列範例會使用多個程序，下載具有相同前置字串的所有物件：

import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
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;
import java.util.stream.Collectors;

class DownloadBucket {

  public static void downloadBucketContents(
      String projectId, String bucketName, Path destinationDirectory) {
    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    List<BlobInfo> blobs =
        storage
            .list(bucketName)
            .streamAll()
            .map(blob -> blob.asBlobInfo())
            .collect(Collectors.toList());
    TransferManager transferManager = TransferManagerConfig.newBuilder().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 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

以下範例會下載個別物件：

/**
 * 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 your GCS file
// const fileName = 'your-file-name';

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

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

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

async function downloadFile() {
  const options = {
    destination: destFileName,
  };

  // Downloads the file
  await storage.bucket(bucketName).file(fileName).download(options);

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

downloadFile().catch(console.error);

以下範例會使用多個程序下載多個物件：

/**
 * 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 first GCS file to download
// const firstFileName = 'your-first-file-name';

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

// 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 downloadManyFilesWithTransferManager() {
  // Downloads the files
  await transferManager.downloadManyFiles([firstFileName, secondFileName]);

  for (const fileName of [firstFileName, secondFileName]) {
    console.log(`gs://${bucketName}/${fileName} downloaded to ${fileName}.`);
  }
}

downloadManyFilesWithTransferManager().catch(console.error);

下列範例會使用多個程序，下載具有相同前置字串的所有物件：

/**
 * 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 folder to download. The folder will be downloaded to the local path of the executing code.
// const folderName = 'your-folder-name';

// 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 downloadFolderWithTransferManager() {
  // Downloads the folder
  await transferManager.downloadManyFiles(folderName);

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

downloadFolderWithTransferManager().catch(console.error);

PHP

詳情請參閱「Cloud Storage PHP API 參考文件」。

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

use Google\Cloud\Storage\StorageClient;

/**
 * Download an object from Cloud Storage and save it as a local file.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $destination The local destination to save the object.
 *        (e.g. '/path/to/your/file')
 */
function download_object(string $bucketName, string $objectName, string $destination): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination);
    printf(
        'Downloaded gs://%s/%s to %s' . PHP_EOL,
        $bucketName,
        $objectName,
        basename($destination)
    );
}

Python

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

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

以下範例會下載個別物件：

from google.cloud import storage


def download_blob(bucket_name, source_blob_name, destination_file_name):
    """Downloads a blob from the bucket."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # source_blob_name = "storage-object-name"

    # The path to which the file should be downloaded
    # destination_file_name = "local/path/to/file"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(source_blob_name)
    blob.download_to_filename(destination_file_name)

    print(
        "Downloaded storage object {} from bucket {} to local file {}.".format(
            source_blob_name, bucket_name, destination_file_name
        )
    )

以下範例會使用多個程序下載多個物件：

def download_many_blobs_with_transfer_manager(
    bucket_name, blob_names, destination_directory="", blob_name_prefix="", workers=8
):
    """Download blobs in a list by name, concurrently in a process pool.

    The filename of each blob once downloaded is derived from the blob name and
    the `destination_directory `parameter. For complete control of the filename
    of each blob, use transfer_manager.download_many() instead.

    Directories will be created automatically as needed to accommodate blob
    names that include slashes.
    """

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

    # The list of blob names to download. The names of each blobs will also
    # be the name of each destination file (use transfer_manager.download_many()
    # instead to control each destination file name). If there is a "/" in the
    # blob name, then corresponding directories will be created on download.
    # blob_names = ["myblob", "myblob2"]

    # The directory on your computer to which to download all of the files. This
    # string is prepended to the name of each blob to form the full path using
    # pathlib. Relative paths and absolute paths are both accepted. An empty
    # string means "the current working directory". Note that this parameter
    # will NOT allow files to escape the destination_directory and will skip
    # downloads that attempt directory traversal outside of it.
    # destination_directory = ""

    # 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)

    results = transfer_manager.download_many_to_path(
        bucket,
        blob_names,
        destination_directory=destination_directory,
        blob_name_prefix=blob_name_prefix,
        max_workers=workers,
    )

    for name, result in zip(blob_names, results):
        # The results list is either `None`, an exception, or a warning for each blob in
        # the input list, in order.
        if isinstance(result, UserWarning):
            print("Skipped download for {} due to warning: {}".format(name, result))
        elif isinstance(result, Exception):
            print("Failed to download {} due to exception: {}".format(name, result))
        else:
            print(
                "Downloaded {} inside {} directory.".format(name, destination_directory)
            )

下列範例會使用多個程序下載 bucket 中的所有物件：

def download_bucket_with_transfer_manager(
    bucket_name, destination_directory="", workers=8, max_results=1000
):
    """Download all of the blobs in a bucket, concurrently in a process pool.

    The filename of each blob once downloaded is derived from the blob name and
    the `destination_directory `parameter. For complete control of the filename
    of each blob, use transfer_manager.download_many() instead.

    Directories will be created automatically as needed, for instance to
    accommodate blob names that include slashes.
    """

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

    # The directory on your computer to which to download all of the files. This
    # string is prepended (with os.path.join()) to the name of each blob to form
    # the full path. Relative paths and absolute paths are both accepted. An
    # empty string means "the current working directory". Note that this
    # parameter allows accepts directory traversal ("../" etc.) and is not
    # intended for unsanitized end user input.
    # destination_directory = ""

    # 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

    # The maximum number of results to fetch from bucket.list_blobs(). This
    # sample code fetches all of the blobs up to max_results and queues them all
    # for download at once. Though they will still be executed in batches up to
    # the processes limit, queueing them all at once can be taxing on system
    # memory if buckets are very large. Adjust max_results as needed for your
    # system environment, or set it to None if you are sure the bucket is not
    # too large to hold in memory easily.
    # max_results=1000

    from google.cloud.storage import Client, transfer_manager

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

    blob_names = [blob.name for blob in bucket.list_blobs(max_results=max_results)]

    results = transfer_manager.download_many_to_path(
        bucket, blob_names, destination_directory=destination_directory, max_workers=workers
    )

    for name, result in zip(blob_names, results):
        # The results list is either `None` or an exception for each blob in
        # the input list, in order.

        if isinstance(result, Exception):
            print("Failed to download {} due to exception: {}".format(name, result))
        else:
            print("Downloaded {} to {}.".format(name, destination_directory + name))

Ruby

詳情請參閱「Cloud Storage Ruby API 參考文件」。

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

def download_file bucket_name:, file_name:, local_file_path:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The path to which the file should be downloaded
  # local_file_path = "/local/path/to/file.txt"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name, skip_lookup: true
  file    = bucket.file file_name

  file.download local_file_path

  puts "Downloaded #{file.name} to #{local_file_path}"
end

Rust

use google_cloud_storage::client::Storage;
use tokio::io::AsyncWriteExt;

pub async fn sample(
    client: &Storage,
    bucket: &str,
    object: &str,
    file_path: &str,
) -> Result<(), anyhow::Error> {
    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket}"), object)
        .send()
        .await?;

    let mut file = tokio::fs::File::create(file_path).await?;
    while let Some(data) = reader.next().await.transpose()? {
        file.write_all(&data).await?;
    }
    file.flush().await?;

    println!("Downloaded {object} in bucket {bucket} to {file_path}.");
    Ok(())
}

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 透過 GET 物件要求呼叫 JSON API：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -o "SAVE_TO_LOCATION" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"
```
其中：
- SAVE_TO_LOCATION 是要儲存物件的位置路徑。例如：Desktop/dog.png。
- BUCKET_NAME 是包含要下載物件的值區名稱。例如：my-bucket。
- OBJECT_NAME 是您要下載的物件名稱，並經過 URL 編碼。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。

XML API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 透過 GET 物件要求呼叫 XML API：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -o "SAVE_TO_LOCATION" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
其中：
- SAVE_TO_LOCATION 是要儲存物件的位置路徑。例如：Desktop/dog.png。
- BUCKET_NAME 是包含要下載物件的值區名稱。例如：my-bucket。
- OBJECT_NAME 是您要下載的物件名稱，並經過 URL 編碼。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。

如要更有效率地下載值區或子目錄中的所有物件，請使用 gcloud storage cp 指令或用戶端程式庫：

gcloud storage cp --recursive gs://BUCKET_NAME/FOLDER_NAME .

下載部分物件

如果下載作業中斷，您可以只要求下載剩餘的物件部分，從中斷處繼續下載。請按照下列操作說明下載部分物件。

控制台

Google Cloud 控制台不支援下載物件的部分內容。請改用 gcloud CLI。

指令列

Google Cloud CLI 會自動嘗試繼續下載中斷的下載作業，但執行串流下載時除外。如果下載作業中斷，目的地階層中會顯示部分下載的暫時檔案。再次執行相同的 cp 指令，即可從上次中斷的地方繼續下載。

下載完成後，系統會刪除暫存檔案，並以下載的內容取代。暫存檔案會儲存在可設定的位置，預設位於使用者主目錄的 .config/gcloud/surface_data/storage/tracker_files 下。您可以執行 gcloud config get storage/tracker_files_directory，變更或查看暫存檔案的儲存位置。

用戶端程式庫

C++

詳情請參閱「Cloud Storage C++ API 參考文件」。

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

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::int64_t start, std::int64_t end) {
  gcs::ObjectReadStream stream =
      client.ReadObject(bucket_name, object_name, gcs::ReadRange(start, end));

  int count = 0;
  std::string line;
  while (std::getline(stream, line, '\n')) {
    std::cout << line << "\n";
    ++count;
  }
  if (stream.bad()) throw google::cloud::Status(stream.status());

  std::cout << "The requested range has " << count << " lines\n";
}

C#

詳情請參閱「Cloud Storage C# API 參考文件」。

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


using Google.Apis.Storage.v1;
using Google.Cloud.Storage.V1;
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class DownloadByteRangeAsyncSample
{
    public async Task DownloadByteRangeAsync(
        string bucketName = "your-unique-bucket-name",
        string objectName = "my-file-name",
        long firstByte = 0,
        long lastByte = 20,
        string localPath = "my-local-path/my-file-name")
    {
        var storageClient = StorageClient.Create();

        // Create an HTTP request for the media, for a limited byte range.
        StorageService storage = storageClient.Service;
        var uri = new Uri($"{storage.BaseUri}b/{bucketName}/o/{objectName}?alt=media");

        var request = new HttpRequestMessage { RequestUri = uri };
        request.Headers.Range = new RangeHeaderValue(firstByte, lastByte);

        using var outputFile = File.OpenWrite(localPath);
        // Use the HttpClient in the storage object because it supplies
        // all the authentication headers we need.
        var response = await storage.HttpClient.SendAsync(request);
        await response.Content.CopyToAsync(outputFile, null);
        Console.WriteLine($"Downloaded {objectName} to {localPath}.");
    }
}

Go

詳情請參閱「Cloud Storage Go API 參考文件」。

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

import (
	"context"
	"fmt"
	"io"
	"os"
	"time"

	"cloud.google.com/go/storage"
)

// downloadByteRange downloads a specific byte range of an object to a file.
func downloadByteRange(w io.Writer, bucket, object string, startByte int64, endByte int64, destFileName string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	// startByte := 0
	// endByte := 20
	// destFileName := "file.txt"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*50)
	defer cancel()

	f, err := os.Create(destFileName)
	if err != nil {
		return fmt.Errorf("os.Create: %w", err)
	}

	length := endByte - startByte
	rc, err := client.Bucket(bucket).Object(object).NewRangeReader(ctx, startByte, length)
	if err != nil {
		return fmt.Errorf("Object(%q).NewReader: %w", object, err)
	}
	defer rc.Close()

	if _, err := io.Copy(f, rc); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}

	if err = f.Close(); err != nil {
		return fmt.Errorf("f.Close: %w", err)
	}

	fmt.Fprintf(w, "Bytes %v to %v of blob %v downloaded to local file %v\n", startByte, startByte+length, object, destFileName)

	return nil

}

Java

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

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


import com.google.cloud.ReadChannel;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.io.ByteStreams;
import java.io.IOException;
import java.nio.channels.FileChannel;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;

public class DownloadByteRange {

  public static void downloadByteRange(
      String projectId,
      String bucketName,
      String blobName,
      long startByte,
      long endBytes,
      String destFileName)
      throws IOException {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The name of the blob/file that you wish to modify permissions on
    // String blobName = "your-blob-name";

    // The starting byte at which to begin the download
    // long startByte = 0;

    // The ending byte at which to end the download
    // long endByte = 20;

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

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, blobName);
    try (ReadChannel from = storage.reader(blobId);
        FileChannel to = FileChannel.open(Paths.get(destFileName), StandardOpenOption.WRITE)) {
      from.seek(startByte);
      from.limit(endBytes);

      ByteStreams.copy(from, to);

      System.out.printf(
          "%s downloaded to %s from byte %d to byte %d%n",
          blobId.toGsUtilUri(), destFileName, startByte, endBytes);
    }
  }
}

Node.js

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

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

/**
 * 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 your GCS file
// const fileName = 'your-file-name';

// The starting byte at which to begin the download
// const startByte = 0;

// The ending byte at which to end the download
// const endByte = 20;

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

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

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

async function downloadByteRange() {
  const options = {
    destination: destFileName,
    start: startByte,
    end: endByte,
  };

  // Downloads the file from the starting byte to the ending byte specified in options
  await storage.bucket(bucketName).file(fileName).download(options);

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

downloadByteRange();

PHP

詳情請參閱「Cloud Storage PHP API 參考文件」。

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

use Google\Cloud\Storage\StorageClient;

/**
 * Download a byte range from Cloud Storage and save it as a local file.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param int $startByte The starting byte at which to begin the download.
 *        (e.g. 1)
 * @param int $endByte The ending byte at which to end the download. (e.g. 5)
 * @param string $destination The local destination to save the object.
 *        (e.g. '/path/to/your/file')
 */
function download_byte_range(
    string $bucketName,
    string $objectName,
    int $startByte,
    int $endByte,
    string $destination
): void {
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination, [
        'restOptions' => [
            'headers' => [
                'Range' => "bytes=$startByte-$endByte",
            ],
        ],
    ]);
    printf(
        'Downloaded gs://%s/%s to %s' . PHP_EOL,
        $bucketName,
        $objectName,
        basename($destination)
    );
}

Python

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

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

from google.cloud import storage


def download_byte_range(
    bucket_name, source_blob_name, start_byte, end_byte, destination_file_name
):
    """Downloads a blob from the bucket."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The ID of your GCS object
    # source_blob_name = "storage-object-name"

    # The starting byte at which to begin the download
    # start_byte = 0

    # The ending byte at which to end the download
    # end_byte = 20

    # The path to which the file should be downloaded
    # destination_file_name = "local/path/to/file"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)

    # Construct a client side representation of a blob.
    # Note `Bucket.blob` differs from `Bucket.get_blob` as it doesn't retrieve
    # any content from Google Cloud Storage. As we don't need additional data,
    # using `Bucket.blob` is preferred here.
    blob = bucket.blob(source_blob_name)
    blob.download_to_filename(destination_file_name, start=start_byte, end=end_byte)

    print(
        "Downloaded bytes {} to {} of object {} from bucket {} to local file {}.".format(
            start_byte, end_byte, source_blob_name, bucket_name, destination_file_name
        )
    )

Ruby

詳情請參閱「Cloud Storage Ruby API 參考文件」。

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

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

# file_name = "Name of a file in the Storage bucket"

# The starting byte at which to begin the download
# start_byte = 0

# The ending byte at which to end the download
# end_byte = 20

# The path to which the file should be downloaded
# local_file_path = "/local/path/to/file.txt"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.download local_file_path, range: start_byte..end_byte

puts "Downloaded bytes #{start_byte} to #{end_byte} of object #{file_name} from bucket #{bucket_name}" \
     + " to local file #{local_file_path}."

Rust

use google_cloud_storage::client::Storage;
use google_cloud_storage::model_ext::ReadRange;

pub async fn sample(
    client: &Storage,
    bucket: &str,
    object: &str,
    start: u64,
    end: u64,
) -> Result<(), anyhow::Error> {
    let count = end - start + 1;
    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket}"), object)
        .set_read_range(ReadRange::segment(start, count))
        .send()
        .await?;

    let mut content = Vec::new();
    while let Some(data) = reader.next().await.transpose()? {
        content.extend_from_slice(&data);
    }

    println!(
        "Downloaded {} bytes from {start} to {end} of object {object} in bucket {bucket}.",
        content.len()
    );
    Ok(())
}

REST API

JSON API

在要求中使用 Range 標頭，下載物件的一部分。

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 透過 GET 物件要求呼叫 JSON API：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Range: bytes=FIRST_BYTE-LAST_BYTE" \
  -o "SAVE_TO_LOCATION" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media"
```
其中：
- FIRST_BYTE 是您要下載的位元組範圍中的第一個位元組。例如：1000。
- LAST_BYTE 是您要下載的位元組範圍中的最後一個位元組。例如：1999。
- SAVE_TO_LOCATION 是要儲存物件的位置路徑。例如：Desktop/dog.png。
- BUCKET_NAME 是包含要下載物件的值區名稱。例如：my-bucket。
- OBJECT_NAME 是您要下載的物件名稱，並經過 URL 編碼。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。

XML API

在要求中使用 Range 標頭，下載物件的一部分。

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 透過 GET 物件要求呼叫 XML API：
```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Range: bytes=FIRST_BYTE-LAST_BYTE" \
  -o "SAVE_TO_LOCATION" \
  "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
```
其中：
- FIRST_BYTE 是您要下載的位元組範圍中的第一個位元組。例如：1000。
- LAST_BYTE 是您要下載的位元組範圍中的最後一個位元組。例如：1999。
- SAVE_TO_LOCATION 是要儲存物件的位置路徑。例如：$HOME/Desktop/dog.png。
- BUCKET_NAME 是包含要下載物件的值區名稱。例如：my-bucket。
- OBJECT_NAME 是您要下載的物件名稱，並經過 URL 編碼。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。

後續步驟

歡迎試用

如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用 Cloud Storage 平台的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

免費試用 Cloud Storage

下載物件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要的角色

所需權限

從 bucket 下載物件

控制台

指令列

用戶端程式庫

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

REST API

JSON API

XML API

下載部分物件

控制台

指令列

用戶端程式庫

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

Rust

REST API

JSON API

XML API

後續步驟

歡迎試用

下載物件