Compute Engine 版本管理指南：API、用戶端程式庫和工具

本指南說明 Compute Engine 如何管理 REST API、用戶端程式庫和 gcloud 指令列工具的版本。本文說明以管道為基礎的版本控管 (CBV) 和以介面為基礎的版本控管 (IBV) 的差異，但主要著重於後者。

事前準備

  • 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：

    選取這個頁面上您打算如何使用範例的分頁：

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，不需要設定驗證。

    gcloud

    1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

      gcloud init

      如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  • 設定預設區域和可用區。

    • REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

以管道為準的版本控管和以介面為準的版本控管

Compute Engine API 支援兩種版本控制機制：以管道為準的版本控制 (CBV) 和以介面為準的版本控制 (IBV)。

  • 在管道導向的版本管理中，發布版本會長期存在，並接收就地更新。Compute Engine 支援 v1、Beta 版和 Alpha 版管道。

  • 在介面式版本管理中，個別介面、方法和資源會進行版本管理，且可逐步獨立演進。

IBV 會取代 CBV。不過，導入 IBV 和新版本不會影響現有的 CBV 實作。如果您偏好使用現有 API 版本，可以繼續使用 CBV。

IBV 可協助您確認 API 行為，以及要求和回應酬載是否符合預期 API 版本。如要使用 IBV，請在要求中指定 API 版本，方法是使用查詢參數或標頭。詳情請參閱「建立 API 要求」。

使用 IBV 可享有以下好處：

  • 提高穩定性：IBV 可讓您指出服務必須回應的 API 版本，藉此保護執行中的應用程式免於變更。
  • 控管變更採用情形：使用 IBV 時，您可以選擇要使用哪個版本來處理要求。您可以按照自己的時間表升級至新服務功能。

如要進一步瞭解版本管理策略，請參閱 API 改進提案 185。

以介面為準的版本控管政策

每個版本的 Compute Engine IBV API 都是一組介面變更，即使介面可能會獨立變更版本，這些變更仍共用相同的服務版本。

Compute Engine IBV API 支援穩定版和預覽版。

穩定版

大多數 API 版本都是穩定版。穩定版會維持嚴格的相容性，如 AIP-180 所定義，也就是說，相同版本的新穩定版不會破壞現有功能，也不需要重寫程式碼。

Compute Engine 會使用 YYYY-MM-DD 格式的標準日期 (例如 2026-09-01) 識別穩定版 API 版本。日期越晚表示版本越新。

Compute Engine 長期支援穩定版本，因此您的生產系統可維持可靠性，不會中斷運作。對大多數應用程式而言，您只需要使用單一穩定版本，即可執行日常工作。

預先發布版

Compute Engine 可能會發布預先發布版本，以便收集使用者對新功能的初步意見回饋。預覽版本會在日期後加上 -preview 標記 (例如 2026-10-01-preview)。

預先發布版包含最新穩定版的所有功能，以及新加入的實驗功能。使用預覽版時，請注意下列事項：

  • 預先發布功能不保證與先前或日後的版本相容。
  • 不建議在執行重要任務的正式環境中使用預覽版。
  • 我們可能會在將搶先版功能升級為穩定版時，變更、改善或移除這些功能。

如要試用新功能，請使用預覽版本，並在穩定版推出後更新程式碼。

在要求中指定 API 版本

如要使用 IBV 呼叫 API，請在要求中透過查詢參數或標頭指定目標版本。如需如何提出 API 要求的範例，請參閱「建立 API 要求」。

Cloud 用戶端程式庫

Cloud 用戶端程式庫可免除建構及剖析原始 REST 呼叫的負擔。每個程式庫版本都會直接連結至特定日期型 API 版本。

如要使用新功能，請將 Cloud Client Libraries 套件更新至最新版本。我們會在發布新的穩定版和預覽版 API 時，一併更新 Cloud 用戶端程式庫。

建議您在穩定版 Cloud 用戶端程式庫上執行正式版應用程式，並將預覽版程式庫隔離到測試環境。

Google Cloud CLI (gcloud)

使用 gcloud CLI 管理 Compute Engine 資源時，不必手動追蹤個別 REST 端點。

gcloud CLI 會將指令分成兩類：

  • 穩定版指令：標準指令 (例如 gcloud compute instances create) 會以穩定版 API 為目標。這些指令完全受到支援，可預測且建議用於正式版指令碼。
  • 預覽指令：搶先體驗版功能使用 gcloud preview 群組 (例如 gcloud preview compute ...)。由於合約可能會在最終版本發布前變更，因此這些指令會顯示簡短警告。

Terraform

Google Cloud Terraform Provider 會抽象化 API 版本管理，並管理基礎 API 互動。Terraform 設定不會公開或要求手動設定版本標頭。

如要使用新功能，請將 Google Cloud Terraform Provider 更新至最新版本。如要使用預先發布版功能，請使用 google-beta 提供者。

常見問題

本節將回答 Compute Engine API 版本管理 的常見問題。

  • 我是否必須從第 1 版 (CBV) 遷移至 IBV？

    不會，現有的 CBV 第 1 版 API 要求仍可照常運作。不過，您將無法存取 IBV API 提供的新功能。

  • IBV API 版本支援期限有多長？

    根據標準 Google Cloud淘汰政策，穩定版會永久維護。

  • 新版 IBV API 的發布頻率為何？

    我們預計每季發布新版 IBV API。預覽版可隨時發布。

  • 我是否需要在 Google Cloud 控制台中啟用任何項目？

    否，啟用 Compute Engine API 時，系統會預設啟用 IBV API。

  • 如果我在要求中未指定版本，會發生什麼情況？

    您的要求預設會傳送至 CBV 第 1 版端點。

  • Cloud 稽核記錄項目中的 API 版本位於何處？

    API 版本會記錄在 protoPayload.requestMetadata.callerSuppliedUserAgent 中，以及要求標頭或查詢參數中。

後續步驟

如要進一步瞭解 Compute Engine API，請參閱下列文件：