教學課程：為您的 API 發佈多個版本
適用於：所有 APIM 層
有時候，讓 API 的所有呼叫者使用完全相同的版本不太實際。 當呼叫者想要升級至較新版本時，他們需要一個容易了解的方法。 如本教學課程所示，可以在 Azure API 管理 中提供多個版本。
如需背景知識，請參閱版本 (部分機器翻譯) 與修訂 (部分機器翻譯)。
在本教學課程中，您會了解如何：
- 將新版本新增至現有 API
- 選擇版本配置
- 將版本新增至產品
- 瀏覽開發人員入口網站以查看版本
必要條件
- 了解 Azure API 管理術語。
- 完成下列快速入門：建立 Azure API 管理執行個體。
- 同時也請完成下列教學課程：匯入和發佈您的第一個 API。
加入新版本
- 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
- 選取 [API]。
- 從 API 清單中選取 Swagger Petstore 。
- 選取 Swagger Petstore 旁邊的操作功能表 （...）。
- 選取 [新增版本]。
提示
您也可以在建立新的 API 時啟用版本。 在 [新增 API] 畫面上，選取 [要為此 API 設定版本嗎？]。
選擇版本設定配置
在 Azure API 管理中，您可以選取下列版本設定配置，以選擇呼叫者指定 API 版本的方式：路徑、標頭或查詢字串。 下列範例使用路徑作為版本設定配置。
從下表中輸入值。 然後，選取 [建立] 以建立您的版本。
| 設定 | 值 | Description |
|---|---|---|
| 版本識別碼 | v1 | 版本的配置特定指標。 路徑的識別碼為 API URL 路徑的尾碼。 |
| 版本設定配置 | 路徑 | 呼叫者指定 API 版本的方式。 如果 已選取 [標頭 ] 或 [查詢字串 ]，請輸入另一個值：標頭或查詢字串參數的名稱。 請參考顯示的使用範例。 |
| 完整 API 版本名稱 | swagger-petstore-v1 | API 管理執行個體中的唯一名稱。 版本實際上是以 API 的修訂為基礎的新 API，因此這項設定就是新的 API 名稱。 |
| 產品 | 沒有限制 （在特定服務層級中提供） | (選擇性) 與 API 版本相關聯的一或多個產品。 若要發佈 API，您必須將它與產品產生關連。 您也可於後續將版本新增至產品。 |
建立版本之後，它現在會出現在 API 清單中的 Swagger Petstore 下方。 您現在會看到兩個 API：原始和 v1。
注意
如果您將版本新增至未設定版本的 API，則也會自動建立原始。 此版本會反映在預設 URL 上。 建立原始版本，可確保任何現有的呼叫者都不會因為新增版本的程序而受到干擾。 如果您在開始時建立已啟用版本的新 API，則不會建立「原始」。
編輯版本
新增版本之後，您現在可以編輯並設定為不同於原始的 API。 對某個版本的變更不會影響另一個版本。 例如，新增或移除 API 作業，或編輯 OpenAPI 規格。 如需詳細資訊，請參閱編輯 API。
將版本新增至產品
為了讓呼叫端看到新的版本，您必須將該版本新增至產品。 如果您尚未將版本新增至產品，可以隨時將其新增至產品。
例如，若要將版本新增至「無限制」產品：
- 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
- 選取 [產品]>[無限制]>[API]>[+ 新增]。
- 選取 [Swagger Petstore]，版本 v1。
- 按一下 [選取]。
使用版本集
當您建立多個版本時，Azure 入口網站會建立「版本集」，代表單一邏輯 API 的一組版本。 選取多版本 API 的名稱。 Azure 入口網站會顯示版本集。 您可以自訂虛擬集的 [名稱] 和 [描述]。
您可以使用 Azure CLI，直接與版本集互動：
在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱使用 Azure CLI 登入。
出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。
若要查看所有版本集，請執行 az apim api versionset list 命令：
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --output table
Azure 入口網站為您建立版本集時會指派英數字元名稱，該名稱出現在清單的 [名稱] 欄。 在其他 Azure CLI 命令中使用此名稱。
若要查看版本集的詳細資料，請執行 az apim api versionset show 命令：
az apim api versionset show --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
如需版本集的詳細資訊，請參閱 Azure API 管理中的版本。
瀏覽開發人員入口網站以查看版本
如果您嘗試使用開發人員入口網站，則可在該處檢視 API 版本。
- 從頂端功能表選取 [開發人員入口網站]。
- 選取 [API]，然後選取 [Swagger Petstore]。
- 您應該會在 API 名稱旁邊看到有多個版本的下拉式清單。
- 選取 [v1]。
- 請注意清單中第一項作業的 [要求 URL]。 它會顯示 API URL 路徑，包含 v1。
下一步
在本教學課程中，您已了解如何：
- 將新版本新增至現有 API
- 選擇版本配置
- 將版本新增至產品
- 瀏覽開發人員入口網站以查看版本
前進到下一個教學課程：