位置端點

本頁面說明如何使用位置端點存取 Cloud Storage。使用位置端點有助於確保靜態資料留在管轄範圍內，以符合資料落地規定。

總覽

位置端點是要求端點，只有在受影響的資源位於端點指定的位置時，才會允許要求繼續執行。舉例來說，如果您在刪除 bucket 要求中使用端點 https://us-central1-storage.googleapis.com，只有在 bucket 位於 US-CENTRAL1 時，要求才會繼續執行。

全域端點處理要求的位置可能與資源所在位置不同，但位置端點可確保要求只會在端點指定的位置 (即資源所在位置) 處理。

使用位置端點可確保：

  • 儲存在 Cloud Storage 的資料不會離開指定位置。

  • 從地端部署環境傳輸至 Google Cloud時，資料會在端點指定的區域終止 TLS。

使用位置端點時，您必須承擔下列責任：

  • 如要取得資料落地保證，向位置端點發出的要求必須來自端點指定的相同位置。舉例來說，如果您使用 Compute Engine 虛擬機器，透過 us-central1-storage.googleapis.com 端點向 US-CENTRAL1 中的 bucket 提出要求，虛擬機器也必須位於 US-CENTRAL1。

  • 只有在執行支援的操作時，才能使用位置端點。執行不支援的操作會導致錯誤。

位置端點支援地端部署與 Google Cloud 之間透過互連網路或 VPN 傳輸的流量，以及 Google Cloud 服務之間 (例如從 BigQuery 到 Cloud Storage) 傳輸的流量。不支援網際網路流量。

支援的作業

下表彙整了可透過位置端點執行的作業，以及無法執行的作業。一般來說，位置端點可執行位置內作業，但無法執行跨位置作業。

如果嘗試使用位置端點執行不支援的操作，Cloud Storage 會傳回 400 HTTP 錯誤代碼，並顯示以下訊息：「This endpoint does not implement this operation. 請使用全域端點。」

作業 修改物件資料 支援與位置端點搭配使用
objects compose 是 有1
刪除物件 否 有1
物件取得 是 有1
物件插入 是 有1
物件清單 否 有1
objects patch 否 有1
objects copy 是 是4
物件重寫 是 是4
buckets insert 否 是2
刪除 bucket 否 是3
buckets get 否 是2
buckets patch 否 是2
更新 bucket 否 是2
buckets getIamPolicy 否 是2
buckets setIamPolicy 否 是2
buckets testIamPermissions 否 是2
buckets lockRetentionPolicy 否 是2
buckets BucketAccessControls 否 是2
buckets DefaultObjectAccessControls 否 是2
buckets ObjectAccessControls 否 是2
HMAC 金鑰作業 否 否
服務帳戶作業 否 否
Pub/Sub 通知作業 依作業而異 否
批次作業 依作業而異 否

1 如要使用位置端點執行這項作業，含有受影響物件的 bucket 必須存在於端點指定的位置。舉例來說，向 us-central1-storage.googleapis.com 提出的物件刪除要求，只能用於刪除位於 US-CENTRAL1 區域 bucket 中的物件。如果嘗試刪除的位置並非 US-CENTRAL1，作業會傳回 NOT_FOUND 錯誤。

2 如要使用位置端點執行這項作業，bucket 必須位於端點指定的位置。舉例來說，向 us-central1-storage.googleapis.com 發出的 bucket 建立要求只能用來在 US-CENTRAL1 區域中建立 bucket。如果嘗試在 US-CENTRAL1 以外的位置建立 bucket，作業會傳回 INVALID_ARGUMENT 錯誤。

3 如要使用位置端點執行這項作業，bucket 必須位於端點指定的位置。舉例來說，對 us-central1-storage.googleapis.com 提出的 bucket 刪除要求只能用於刪除 US-CENTRAL1 區域中的 bucket。如果嘗試刪除非 US-CENTRAL1 位置中的 bucket，作業會傳回 NOT_FOUND 錯誤。

4 如要使用位置端點執行這項作業，來源和目的地 bucket 都必須位於端點指定的位置。舉例來說，如果兩個 bucket 位於相同位置，您可以使用位置端點將物件從一個 bucket 複製到另一個 bucket。不過，如果 bucket 位於不同位置，您就無法使用位置端點將物件從一個 bucket 複製到另一個 bucket。如果來源或目的地 bucket 所在位置與端點指定的位置不同，作業會傳回 NOT_FOUND 錯誤。

支援的地區

所有美國區域、US多區域和NAM4預先定義的雙區域都支援區域端點。如要進一步瞭解可指定的區域，請參閱「值區位置」。

發出要求

控制台

為確保符合 ITAR 規定，您有責任使用管轄區 Google Cloud 控制台。詳情請參閱「Cloud Storage 的 ITAR 控制套件」。

指令列

如要設定 Google Cloud CLI 以搭配使用區域端點，請按照下列步驟操作：

  1. 將 api_endpoint_overrides/storage 屬性設為要使用的位置端點：

    gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/

設定這項屬性後，您就能照常使用 gcloud CLI 指令。

或者，您也可以在每個指令中設定 CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE 環境變數，為個別指令使用位置端點。例如：

CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket

用戶端程式庫

Cloud Storage 用戶端程式庫會自動管理要求端點，但您也可以手動設定位置端點。如要瞭解如何設定位置端點，請參閱使用要求端點的用戶端程式庫程式碼範例。

REST API

JSON API

向位置端點發出要求時，請使用下列 URI：

  • 如要提出一般 JSON API 要求 (不含物件上傳)，請使用下列端點：

    https://LOCATION-storage.googleapis.com

    將 LOCATION 替換為支援的值區位置。例如：us-central1。

  • 如要上傳 JSON API 物件，請使用下列端點：

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

    更改項目：

    • LOCATION 位於支援的值區位置。例如：us-central1。

    • BUCKET_NAME 替換為要上傳物件的 bucket 名稱。例如：my-example-bucket。

  • 如要下載 JSON API 物件，請使用下列端點：

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

    更改項目：

    • LOCATION 位於支援的值區位置。例如：us-central1。

    • 將 BUCKET_NAME 替換為含有要下載物件的 bucket 名稱。例如：my-example-bucket。

    • 將 OBJECT_NAME 替換為要下載的物件名稱。例如：waterfall.png。

請注意，JSON API 端點僅支援 HTTPS 要求。

XML API

使用 XML API 向特定位置的端點提出要求時，您可以採用虛擬主機樣式的端點或路徑樣式的端點：

  • 虛擬主機樣式端點：

    https://BUCKET_NAME.LOCATION-storage.googleapis.com

  • 路徑樣式端點：

    https://LOCATION-storage.googleapis.com/BUCKET_NAME

對於這兩種端點類型，請替換下列項目：

  • LOCATION 位於支援的值區位置。例如：us-central1。

  • BUCKET_NAME 替換成有效的 bucket 名稱。例如：my-example-bucket。

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

正確設定要求格式

為確保要求與 Cloud Storage 工具相容，請採取下列做法：

已知限制

不支援 mTLS 端點。

限制全域 API 端點用量

如要強制使用特定位置的端點，您可以使用 constraints/gcp.restrictEndpointUsage 組織政策限制，封鎖對全域 API 端點的要求。詳情請參閱「限制端點用量」說明文件。