要求端點

本頁面說明您可以用來存取 Cloud Storage 的不同要求端點。Cloud Storage 支援 HTTP/1.1、HTTP/2 和 HTTP/3 通訊協定。端點是可存取 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_NAMEOBJECT_NAME 替換為適當的值:

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

JSON API 端點只接受 HTTPS 要求。

XML API

直接向 Cloud Storage 發出 XML API 要求時,請使用虛擬主機樣式路徑樣式端點,並將 BUCKET_NAMEOBJECT_NAME 替換為適當的值:

  • 虛擬託管型端點:

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

  • 路徑樣式端點:

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

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

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

對網址路徑部分進行編碼

除了值區命名物件命名的一般考量外,為確保 Cloud Storage 工具之間的相容性,請在物件名稱或要求網址的查詢字串中出現以下字元時,對這些字元進行編碼:

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

舉例來說,如果您要針對值區 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 控制台端點

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

資源 網址
專案的值區清單 https://console.cloud.google.com/storage/browser?project=PROJECT_ID
值區的物件清單 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}"

自訂網域

如果您擁有自己的網域,可以將其 URI 對應至一或多個Google Cloud 服務,包括 Cloud Storage 值區。有時會使用「bucket-bound hostname」一詞來描述這個 Cloud Storage 要求端點。如要將自訂網域連結至 Cloud Storage 值區,您可以在 DNS 記錄中建立 ACNAME 重新導向。

A 筆記錄

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

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

使用 A 記錄的缺點是需要額外設定,並使用額外的 Google Cloud 資源。如要瞭解如何使用含有 A 記錄的自訂網域,請參閱「設定負載平衡器和 SSL 憑證」一文。

CNAME 筆記錄

將自訂網域連結至 Cloud Storage 值區時,您可以使用 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 的值區,然後在 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_NAMEOBJECT_NAME 替換為適當的值:

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

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

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

成功登入後,系統會將您重新導向至要求的內容。這類內容的網址開頭為英數字元序列,並包含 /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

如需詳細資訊及範例,請參閱「存取公開資料」。

支援相互傳輸層安全性

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

後續步驟