本頁面說明 Cloud Endpoints API 版本管理功能，並提供有關 Endpoints API 版本管理及測試環境的最佳做法。本頁面提供的資訊適用於使用 OpenAPI 規範的 API。若 API 使用 App Engine 標準環境適用的 Cloud Endpoints Frameworks，請參閱「處理 API 版本管理：Java」或「處理 API 版本管理：Python」。
我們建議您參照 Google 用於 API 版本管理與服務測試環境的基本原則：
在您部署初始版本前，請在 OpenAPI 設定檔中加入以下內容：
- 在
info.version欄位中設定版本號碼。建議您使用含有主要版本和次要版本的版本字串，例如1.0。 - 將
basePath欄位設為包含主要版本號碼。建議的基本路徑格式為字母v後面加上主要版本編號，例如/v1。
- 在
如要進行回溯相容的變更 (例如加入新方法)，請遞增
info.version欄位中的次要版本編號 (1.2、1.3 等)，並重新部署。詳情請參閱「API 版本管理」一文。如果您要對現有方法做出的變更會中斷用戶端程式碼，請建立 OpenAPI 設定檔案的複本，並按照以下方式調整：
- 遞增
info.version欄位中的主要版本編號 (2.0、3.0 等)。 - 遞增
basePath欄位中的主要版本編號 (/v2、/v3 等)。
部署兩個 OpenAPI 設定檔案版本，然後重新部署後端，後端現在擁有兩個方法版本。詳情請參閱 API 版本管理一文。
- 遞增
在單一後端中實作所有主要 API 版本。請參考以下建議：
- 請簡化路徑，因為針對特定版本提出的要求是以路徑為基礎，如上述範例所示。
- 請簡化設定和部署。所有的 API 主要版本都使用相同的 Google Cloud專案及後端，而且您會同時部署所有的 API 版本。
- 避免過度執行後端，以降低成本。
在將 API 部署至正式版 Google Cloud 專案之前，請先將 API 暫存在另外的 Google Cloud 專案中。詳情請參閱「準備服務測試環境」一節。
Endpoints 使用的主要和次要版本編號會對應語意化版本中的定義。當您在後端程式碼中部署錯誤修正時，雖然 Endpoints 不會要求您遞增 OpenAPI 設定檔中修補程式版本編號並部署設定，但是您仍可以依據需要進行上述操作。
Cloud Endpoints API 版本管理功能
只要 API 的路徑沒有重疊，可擴充服務 Proxy (ESP) 就可以同時管理 API 在單一 Google Cloud 專案和後端中的多個主要版本。例如：
http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo
這可以讓您的客戶在遷移到新版本時，挑選想要使用和控管的版本。ESP 能夠在將要求轉送到後端中適用的方法前，將每個要求標記版本編號。因為每個要求都會標記版本編號：
「Endpoints」>「Services」(服務) 中的圖表與記錄可顯示來自每個主要 API 版本的要求，以及所有版本的匯總資料。您可以在檢視畫面中套用篩選器，查看特定的版本，有助於您清楚掌握各個版本獲得的流量。此外，記錄還能告知您用戶端所使用的版本。
當您重新部署次要版本編號更新的 API 時，後續的活動會在圖表和記錄中使用新的版本編號標記，藉此可提供部署的標籤歷程。
刪除 API 的某個版本時，圖表和記錄會繼續顯示 API 處於作用狀態的時間範圍內的資料。
API 生命週期範例
本節說明服務常見的演進發展。
第 1 版
您最初部署了版本 1 的 My Awesome Echo API 服務。這個 API 由 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo 提供。在「Endpoints」 >「Services」(服務) 中的圖表與記錄裡，您會看到所有流量的版本都是 1.0。
1.1 版
您的客戶提出新的功能需求，因此您需要加入新方法：在 OpenAPI 設定檔中加入新方法，並將 info.version 欄位值遞增為 1.1。由於這個變更不會中斷用戶端程式碼，因此您可以遞增次要版本編號。您在測試環境中部署及測試變更，確保新版本能正常運作。
接下來，您將 OpenAPI 設定和 API 後端部署至實際工作環境。API 仍然由 my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo 提供，但現在呼叫者可以對新方法提出要求。因為您沒有將介面變更為舊方法，所以客戶不需要更改及重新部署他們的用戶端；用戶端可以比照過去做法，繼續對舊的方法傳送要求。
在「Endpoints」 >「Services」(服務) 中，現在提供的流量是 1.1 版本。如果您選擇顯示更早的時間範圍，系統就會在圖表與記錄中顯示先前版本的資料，藉此可提供部署的標籤歷程。
2.0 版
隨著時間演進，您瞭解到必須對現有方法進行回溯不相容的變更。為了避免破壞客戶的用戶端程式碼，您決定維護兩個 API 版本。您可以保留舊方法，並實作新版本的方法。您可以為版本 2.0 建立另一個 OpenAPI 設定檔，並設定要從 my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo 提供的新版本。原始的 OpenAPI 設定檔仍會指向舊版方法，而新的 OpenAPI 設定檔則會指向新版方法。
您同時部署了版本 1 與版本 2 的 OpenAPI 設定檔，然後重新部署後端，後端現在擁有兩個方法版本 (詳情請參閱「API 版本管理」一文)。
部署完畢後，「Endpoints」>「Services」(服務) 會顯示您提供了兩個 API 版本，您也可以查看各版本獲得的流量。您的 v1 用戶端仍可繼續呼叫 /v1，也能呼叫 /v2 以使用新的方法版本。如何處理後端程式碼的版本管理，將取決於您所使用的 API 架構。如需使用 Servlet 的範例，請參閱多個版本的 Endpoints 與 Java 範例。
停用版本 1
最後，當您的用戶端遷移完成，且您發現 v1 的所有流量均已停止，這時候就可以停止提供該版本。如要移除 API 版本 1，只需部署版本 2 的 OpenAPI 設定檔，並重新部署後端即可。現在您可以放心從後端移除實作版本 1 的程式碼。「Endpoints」>「Services」(服務) 仍會保留 1.x 版的歷史資料。
準備服務測試環境
我們建議的最佳做法是，對 Endpoints 服務的更新準備好測試環境，以便在向客戶提供服務之前進行測試。此外，也建議您建立另外的Google Cloud 專案以用於服務的測試環境，使其與實際工作環境隔離。例如，Google 配額通常是由專案中的資源所共用。因此，如果您將測試環境服務放在與實際工作環境服務相同的專案內，一旦發生問題 (例如迴圈的錯誤)，可能就會導致實際工作環境的服務中斷。
建議您訂出可清楚表示 Google Cloud 專案為測試環境用途的名稱。常見的命名策略是採用與實際工作環境 Google Cloud 專案相同的名稱，但結尾加上 -staging；也可以在實際工作環境專案的名稱結尾加上 -prod，明確表示該專案用於實際工作環境服務。
Google Cloud 上的服務名稱不得重複。由於您是在 OpenAPI 設定檔中指定服務名稱，因此必須採取以下其中一種做法：為測試環境和實際工作環境專案分開提供 API 設定檔；或者只使用一組 API 設定檔，並設計適當程序，只要變更其中的服務名稱，就能與要部署的專案名稱相符。