要求端點

本頁說明可用於存取 Cloud Storage 的不同要求端點。Cloud Storage 支援 HTTP/1.1、HTTP/2 和 HTTP/3 通訊協定。端點是 Cloud Storage 的存取位置，以網址形式表示。

注意： 本頁所述的 Cloud Storage 網址可能會有異動。

一般 API 要求

JSON API

直接向 Cloud Storage 提出 JSON API 要求時，請使用下列端點：

• 如要傳送一般 JSON API 要求 (不含物件上傳)，請使用下列端點，並將 PATH_TO_RESOURCE 替換為適當的值：

  https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

• 如要上傳 JSON API 物件，請使用下列端點，並將 BUCKET_NAME 替換為適當的值：

  https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

• 如要批次要求，請使用下列端點，並將 PATH_TO_RESOURCE 替換為適當的值：

  https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

• 如要下載 JSON API 物件，可以視需要使用下列端點，並將 BUCKET_NAME 和 OBJECT_NAME 替換成適當的值：

  https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

JSON API 端點只接受 HTTPS 要求。

注意： JSON API 也支援 https://www.googleapis.com 端點，並在物件的 selfLink 中繼資料欄位中傳回，但建議使用 https://storage.googleapis.com 端點，以獲得更佳的效能和可用性。同樣地，https://content-storage.googleapis.com 端點支援下載，並會在物件的 mediaLink 中繼資料欄位中傳回，但我們也不建議使用。

XML API

重要事項：如要透過瀏覽器提供內容，請注意 XML API 會從與要求端點相同的來源提供內容。如果您需要從專屬的來源提供內容，請考慮使用 JSON API 或透過經驗證的瀏覽器下載作業。

直接向 Cloud Storage 提出 XML API 要求時，請使用虛擬主機樣式或路徑樣式端點，並將 BUCKET_NAME 和 OBJECT_NAME 替換為適當的值：

• 虛擬主機樣式端點：

  https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME

• 路徑樣式端點：

  https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

注意： 虛擬主機樣式端點無法用於存取網域名稱 bucket。請改用路徑樣式的端點或重新導向。

XML API 端點支援安全資料傳輸層 (SSL) 加密，也就是說，您可以使用 HTTP 或 HTTPS。建議使用 HTTPS，尤其是使用 OAuth 2.0 向 Cloud Storage 驗證時。

gRPC

您可以使用 gRPC 與 Cloud Storage 互動。gRPC 是由 Google開發的高效能開放原始碼通用 RPC 架構。gRPC 用戶端會連線至服務端點。如果是 Cloud Storage 等Google Cloud 服務，這通常是 googleapis.com 網域上的 DNS 位址 (例如 storage.googleapis.com)，並使用 443 等標準安全通訊埠。使用 gRPC 可提升效能，並提供高效的串流功能。

如要使用 gRPC 與 Cloud Storage 互動，您必須在 Cloud 用戶端程式庫中啟用 gRPC。

使用下列任一支援的語言，在用戶端程式庫上啟用 gRPC：

• C++ 用戶端程式庫

• Java 用戶端程式庫

• Go 用戶端程式庫

如為透過 Proxy 進行連線，請參閱疑難排解主題來瞭解推薦的做法。

編碼網址路徑部分

除了 bucket 命名和物件命名的一般考量事項外，為確保 Cloud Storage 工具之間的相容性，如果要求網址的物件名稱或查詢字串中出現下列字元，請務必進行編碼：

!、#、$、&、'、(、)、*、+、,、/、:、;、=、?、@、[、]和空格字元。

舉例來說，如果您針對 bucket example-bucket 中名為 foo??bar 的物件傳送 JSON API GET 要求，則要求網址應為：

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

請注意，並非所有列出的字元都必須在每個情境中編碼。 此外，編碼通常由用戶端程式庫 (例如 Cloud Storage 用戶端程式庫) 處理，因此您在使用這類工具時可以傳遞原始物件名稱。

如要進一步瞭解如何使用百分比編碼，請參閱 RFC 3986 的第 3.3 節「路徑」。

Google Cloud console 端點

使用 Google Cloud 控制台時，您可以使用下列網址存取不同資源：

資源	網址
專案的值區清單	https://console.cloud.google.com/storage/browser?project=PROJECT_ID
bucket 的物件清單	https://console.cloud.google.com/storage/browser/BUCKET_NAME
物件詳情	https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
物件的資料	請參閱「已驗證的瀏覽器下載內容」

gcloud endpoints

gcloud storage 指令會使用 JSON API 端點。gcloud CLI 會代為管理端點用量。

用戶端程式庫端點

Cloud Storage 用戶端程式庫會自動管理要求端點。您也可以手動設定要求端點。如果您想使用特定端點或進行測試 (例如使用本機模擬器)，這項功能就非常實用：

C++

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

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

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

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

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

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

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/option"
)

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1/"
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	client.Bucket("bucket-name").Attrs(ctx)
	return nil
}

Java

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

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

import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = "https://storage.googleapis.com"

    Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).setHost(endpoint).build().getService();

    System.out.println(
        "Storage Client initialized with endpoint " + storage.getOptions().getHost());
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The custom endpoint to which requests should be made
// const apiEndpoint = 'https://yourcustomendpoint.com';

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

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,
});

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a custom endpoint for storage client.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. 'https://storage.googleapis.com')
 */
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,
    ]);

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);
}

Python

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

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

from google.cloud import storage


def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = 'https://storage.googleapis.com'

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client

Ruby

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

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

# api_endpoint = "https://storage.googleapis.com"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  endpoint: api_endpoint
)

puts "Client initiated with endpoint #{storage.service.service.root_url}"

Rust

use google_cloud_storage::client::Storage;
use google_cloud_storage::client::StorageControl;

pub async fn sample(bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "hello-world.txt";
    let client = Storage::builder()
        .with_endpoint("https://www.googleapis.com")
        .build()
        .await?;
    // Use the `Storage` client as usual:
    let reader = client
        .read_object(format!("projects/_/buckets/{bucket_id}"), NAME)
        .send()
        .await?;
    println!("Object highlights: {:?}", reader.object());

    let control = StorageControl::builder()
        .with_endpoint("https://www.googleapis.com")
        .build()
        .await?;
    // Use the `StorageControl` client as usual:
    let bucket = control
        .get_bucket()
        .set_name(format!("projects/_/buckets/{bucket_id}"))
        .send()
        .await?;
    println!("Bucket {bucket_id} metadata is {bucket:?}");

    Ok(())
}

自訂網域

如果您擁有自己的網域，可以將網域的 URI 對應至一或多個Google Cloud 服務，包括 Cloud Storage bucket。有時會使用「bucket 繫結主機名稱」一詞，描述這個 Cloud Storage 要求端點。如要將自訂網域連結至 Cloud Storage bucket，請在 DNS 記錄中建立 A 或 CNAME 重新導向。

A 筆記錄

將自訂網域連結至 Cloud Storage bucket 時，通常應使用 A 記錄。

• A 記錄支援 HTTPS 要求。
• A記錄可用於將來自單一主機名稱的流量傳送至多個 bucket，以及其他 Google Cloud 服務。
• A 記錄不會對 bucket 名稱設下任何限制。

使用 A 記錄的缺點是需要額外設定，並使用額外的 Google Cloud 資源。如需使用自訂網域和 A 記錄的指南，請參閱「設定負載平衡器和 SSL 憑證」。

CNAME 筆記錄

將自訂網域連結至 Cloud Storage bucket 時，您可以使用 CNAME 記錄，但請注意，這樣做有特定限制：

• CNAME 記錄僅支援 HTTP 要求。
• CNAME 記錄只能將特定主機名稱的流量導向單一值區。
• CNAME 記錄的主機名稱和相關聯的 bucket 名稱必須相符，且您必須驗證 bucket 名稱。
• CNAME 記錄只能用於子網域 (例如 www.mydomain.com)，不能用於頂層網域 (例如 mydomain.com)。

使用 CNAME 記錄時，CNAME 記錄的主機名稱部分必須設為下列項目：

c.storage.googleapis.com.

舉例來說，假設您的網域是 example.com，而您想為客戶提供旅遊地圖。您可以在 Cloud Storage 中建立名為 travel-maps.example.com 的 bucket，然後在 DNS 中建立 CNAME 記錄，將來自 travel-maps.example.com 的要求重新導向至 Cloud Storage URI。如要完成這項操作，請發布下列 DNS 中的 CNAME 記錄：

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

如此一來，您的客戶就可以使用下列網址存取巴黎的地圖：

http://travel-maps.example.com/paris.jpg

您應該可以使用網域註冊服務來管理網域，包括新增 CNAME 資源記錄。舉例來說，如果您使用 Cloud DNS，可以在「新增、修改及刪除記錄」頁面找到新增資源記錄的操作說明。

已驗證的瀏覽器下載作業

經驗證的瀏覽器下載作業會使用 Cookie 型驗證程序。Cookie 驗證會要求使用者登入使用者帳戶，以確認身分。指定的帳戶必須具備下載物件的適當權限。舉例來說，如果您使用 Identity and Access Management 控制物件存取權，使用者帳戶應具備 storage.objects.viewer 權限，這項權限會授予「Storage 物件檢視者」角色。

如要使用 Cookie 驗證下載物件，請使用下列網址，並將 BUCKET_NAME 和 OBJECT_NAME 替換為適當的值：

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

例如，如果從值區 example-maps 分享圖片 london.jpg，其網址就會是：

https://storage.cloud.google.com/example-maps/london.jpg

成功登入後，系統會將你重新導向至要求的內容。這項內容的網址格式為 https://ALPHANUMERIC_SEQUENCE-apidata.googleusercontent.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME。

執行經過驗證的瀏覽器下載作業時，必須使用 HTTPS；嘗試使用 HTTP 會重新導向至 HTTPS。

存取公開物件

所有傳送至 storage.cloud.google.com URI 的要求都必須經過驗證。即使 allUsers 有權存取物件，這項限制仍適用。如要讓使用者下載可匿名存取的物件，而不必驗證，請使用 XML API 路徑樣式端點：

https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

如需詳細資料和範例，請參閱「存取公開資料」。

支援雙向 TLS

相互傳輸層安全標準 (mTLS) 是業界標準通訊協定，用於在用戶端和伺服器之間進行雙向驗證。Cloud Storage 支援下列 mTLS 端點：

• JSON API 要求：storage.mtls.googleapis.com

• XML API 要求：storage.mtls.googleapis.com

• 已驗證的瀏覽器下載項目：storage.mtls.cloud.google.com

後續步驟

• 將檔案上載至 Cloud Storage。
• 從 Cloud Storage 下載檔案。
• 託管靜態網站。
• 瞭解控制您資料存取權有哪些選項。