處理 API 版本管理

本頁說明如何進行 API 版本管理以及如何部署至多個版本。

管理 API 版本的建議事項

在管理 API 版本時,請考慮以下建議:

  • 當您要進行非破壞性的累加變更時,請維持 API 版本號碼,並在現有的 API 上進行部署。
  • 當您要對 API 進行破壞性變更時,請增加 API 版本號碼。
  • 如要獲得額外的保護,請同時增加 App Engine 應用程式的版本號碼,然後將新的 API 版本部署至新的 App Engine 應用程式版本。如此可讓您利用 App Engine 內建的彈性,在 App Engine 版本之間快速切換,並在遇到未預期的問題時,從舊的可運作版本提供服務。

下表是將後端 API 版本串聯至不同 App Engine 應用程式版本的圖例:

應用程式版本 後端 API 版本
1
  • v1 --> v1 (2) --> v1 (n)
2
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

如資料表中所示,對 API 的 v1 導入非破壞性的累加更新,每次都會覆寫先前的版本。導入破壞性變更時,API 版本會遞增至 v2,並部署至新的 App Engine 應用程式版本。如此可讓您在必要時切換回先前的應用程式版本。

在資料表中,請注意,應用程式版本 2 支援 API 的最新 v1 版本與新 v2 版本。如果您不刪除專案中的現有 v1 程式碼,部署專案時,就會將 API 的 v2vl (n) 部署至應用程式的版本 2。

部署至多個應用程式版本

部署後端 API 時,您必須將其部署至您為 API 建立的 Google Cloud Platform (GCP) 專案的專案 ID,也必須指定目標 App Engine 版本。請在 /WEB-INF/appengine-web.xml 檔案的 <version> 元素中指定 App Engine 應用程式版本。App Engine 應用程式版本與後端 API 版本編號不同,後端 API 版本編號要在 @Api 註解的 version 屬性中指定。

apiversions

如上圖所示,您可以將多個 API 版本部署至同一個 App Engine 版本。而且,一個應用程式可以有許多 App Engine 版本。

存取部署至提供版本的 API 版本

您第一次部署 API 的 App Engine 版本被稱為提供版本。這個版本在網址 http://YOUR_PROJECT_ID.appspot.com 中執行,其中 YOUR_PROJECT_ID 代表您的 GCP 專案 ID。您可以使用該網址,存取部署至該 App Engine 應用程式版本的所有 API 版本。

提供版本會維持不變,直到您在 Google Cloud Platform 主控台中明確變更為止。

存取部署至非提供版本應用程式的 API 版本

如果您需要存取的 API 版本「並未」部署至 App Engine 目前提供版本,則可使用類似如下的「版本專屬」網址:

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

VERSION 替換為您的 App Engine 版本,並將 YOUR_PROJECT_ID 替換為您的 GCP 專案 ID。例如,假設您的 App Engine 提供版本為 1,但您想存取部署至版本 2 的 API 版本。您將使用以下網址:https://2-dot-YOUR_PROJECT_ID.appspot.com

詳情請參閱 App Engine 說明文件

存取部署至非提供版本服務 (先前為模組) 的 API 版本

如果您需要存取的 API 版本「並未」部署至預設 App Engine 服務,則可使用以下採用 dot 語法的「服務專屬」網址:

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

詳情請參閱 App Engine 說明文件

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁