API 版本管理

本頁說明變更 API 版本號碼的詳細設定及部署過程，而使用的過程取決於對 API 的變更是否向下相容。

  • 如果新的 API 版本具有向下相容的變更，例如新增欄位或方法，請參閱向下相容的變更。
  • 如果新的 API 變更現有的方法，而該方法會破壞客戶的客戶端程式碼，請參閱不可向下相容的變更。

詳情和最佳做法請參閱 API 生命週期管理。

向下相容的變更

當您對 API 進行了向下相容現有客戶端程式碼的變更時，最佳做法是，在部署新版本之前增加 API 的次要版本編號。雖然 Cloud Endpoints 一次只執行一個次要版本的 API，但是「Endpoints」>「Services」(服務) 中的圖形和記錄會顯示版本編號。透過在部署前增加次要版本編號，圖形和記錄可提供部署的標籤歷程。

如要增加次要版本編號：

  1. 在 openapi.yaml 中，將 info.version 欄位的次要版本號碼加 1。舉例來說，如果目前的版本是 1.1，請將 info.version 設為 1.2：

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. 使用 Google Cloud CLI 部署 API 設定：

    gcloud endpoints services deploy openapi.yaml

  3. 使用上一步傳回的設定 ID 部署 API 後端。詳情請參閱部署 API 後端。

不可向下相容的變更

當您對 API 進行變更後會破壞客戶的客戶端程式碼時，最佳做法是增加 API 的主要版本編號。Endpoints 可以同時執行多個 API 的主要版本。您可以提供兩個版本的 API，讓客戶選擇他們想要使用的版本，並在遷移到新版本時進行控制。

如要同時執行 API 的現有版本及新版本：

  1. 為您需要提供的每個版本建立單獨的 OpenAPI 設定檔。這個程序使用檔案名稱 openapi-v1.yaml 和 openapi-v2.yaml 做為範例。

  2. 將 openapi-v1.yaml 的內容複製到 openapi-v2.yaml。

  3. 在 openapi-v1.yaml 中設定下列項目：

    • 將 info.version 欄位設為現有版本號碼。
    • 請勿變更 basePath 欄位。

    例如：

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. 在 openapi-v2.yaml 中設定下列項目：

    • 進行回溯不相容的變更。
    • 將 info.version 欄位設為新版本編號。
    • 將 basePath 欄位設為包含新的主要版本編號。
    • 移除 x-google-endpoints 區段。如果您要指定 DNS IP 位址或 allowCors 標記，就需要使用這個部分。使用兩個 yaml 設定檔部署兩個 API 版本時，只有其中一個可以有 x-google-endpoints，但其設定會套用至兩個版本。

    例如：

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. 使用 Google Cloud CLI 部署兩個 API 設定檔：

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. 使用上一步傳回的設定 ID，部署可提供兩個 API 的單一後端。詳情請參閱部署 API 後端。

相關資源