要求端點

本頁說明您可以用來存取 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./storage/v1/PATH_TO_RESOURCE

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

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

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

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

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

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

JSON API 端點只接受 HTTPS 要求。

注意： JSON API 也支援 https://www. 端點，並會傳回物件的 selfLink 中繼資料欄位，但 https://storage. 是較好的端點，可提供更優異的效能和可用性。同樣地，系統支援用於下載的 https://content-storage. 端點，並會傳回物件的 mediaLink 中繼資料欄位，但我們不建議使用。

XML API

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

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

• 虛擬託管型端點：

  https://BUCKET_NAME.storage./OBJECT_NAME

• 路徑樣式端點：

  https://storage./BUCKET_NAME/OBJECT_NAME

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

gRPC

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

如要使用 gRPC 與 Cloud Storage 互動，請在 Cloud Client Libraries 中啟用這項功能。

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

• C++ 用戶端程式庫

• Java 用戶端程式庫

• Go 用戶端程式庫

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

對網址路徑部分進行編碼

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

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

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

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

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

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

Google Cloud 控制台端點

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

資源	網址
專案的 bucket 清單	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}"

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(())
}

已驗證的瀏覽器下載作業

經驗證的瀏覽器下載作業會使用 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./BUCKET_NAME/OBJECT_NAME

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

支援雙向傳輸層安全標準 (TLS)

相互傳輸層安全標準 (mTLS) 是業界標準通訊協定，可讓用戶端與伺服器相互驗證。Cloud Storage 支援下列 mTLS 端點：

• JSON API 要求：storage.mtls.

• XML API 要求：storage.mtls.

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

後續步驟

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