教學課程：為您的 API 發佈多個版本
適用於：所有 API 管理 層
有時候，讓 API 的所有呼叫者使用完全相同的版本不太實際。 當呼叫者想要升級至較新版本時，他們需要一個容易了解的方法。 如本教學課程所示，在 Azure API 管理中提供多個版本，是可行的作業。
如需背景知識，請參閱版本 (部分機器翻譯) 與修訂 (部分機器翻譯)。
在本教學課程中，您會了解如何：
- 將新版本新增至現有 API
- 選擇版本配置
- 將版本新增至產品
- 瀏覽開發人員入口網站以查看版本
必要條件
- 了解 Azure API 管理術語。
- 完成下列快速入門：建立 Azure API 管理執行個體。
- 同時也請完成下列教學課程：匯入和發佈您的第一個 API。
加入新版本
- 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
- 選取 [API]。
- 從 API 清單中選取 [Demo Conference API]。
- 選取 Demo Conference API 旁的操作功能表 (...)。
- 選取 [新增版本]。
提示
您也可以在建立新的 API 時啟用版本。 在 [新增 API] 畫面上，選取 [要為此 API 設定版本嗎？]。
選擇版本設定配置
在 Azure API 管理中，您可以選取下列版本設定配置，以選擇呼叫者指定 API 版本的方式：路徑、標頭或查詢字串。 下列範例使用路徑作為版本設定配置。
從下表中輸入值。 然後，選取 [建立] 以建立您的版本。
| 設定 | 值 | 描述 |
|---|---|---|
| 名稱 | demo-conference-api-v1 | API 管理執行個體中的唯一名稱。 版本實際上是以 API 的修訂為基礎的新 API，因此這項設定就是新的 API 名稱。 |
| 版本設定配置 | 路徑 | 呼叫者指定 API 版本的方式。 |
| 版本識別碼 | v1 | 版本的配置特定指標。 路徑的識別碼為 API URL 路徑的尾碼。 如果選取 [標頭] 或 [查詢字串]，請輸入額外的值：標頭的名稱或查詢字串參數。 請參考顯示的使用範例。 |
| 產品 | 無限制 | (選擇性) 與 API 版本相關聯的一或多個產品。 若要發佈 API，您必須將它與產品產生關連。 您也可於後續將版本新增至產品。 |
建立版本後，版本此時會顯示在 API 清單中的 Demo Conference API 下方。 您現在會看到兩個 API：原始和 v1。
注意
如果您將版本新增至未設定版本的 API，則也會自動建立原始。 此版本會反映在預設 URL 上。 建立原始版本，可確保任何現有的呼叫者都不會因為新增版本的程序而受到干擾。 如果您在開始時建立已啟用版本的新 API，則不會建立「原始」。
編輯版本
新增版本之後，您現在可以編輯並設定為不同於原始的 API。 對某個版本進行變更不會影響另一個版本。 例如，新增或移除 API 作業，或編輯 OpenAPI 規格。 如需詳細資訊，請參閱編輯 API。
將版本新增至產品
為了讓呼叫端看到新的版本，您必須將該版本新增至產品。 如果您尚未將版本新增至產品，可以隨時將其新增至產品。
例如，若要將版本新增至「無限制」產品：
- 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
- 選取 [產品]>[無限制]>[API]>[+ 新增]。
- 選取 [Demo Conference API，版本 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]，然後選取 [Demo Conference API]。
- 您應該會在 API 名稱旁邊看到有多個版本的下拉式清單。
- 選取 [v1]。
- 請注意清單中第一項作業的 [要求 URL]。 它會顯示 API URL 路徑，包含 v1。
下一步
在本教學課程中，您已了解如何：
- 將新版本新增至現有 API
- 選擇版本配置
- 將版本新增至產品
- 瀏覽開發人員入口網站以查看版本
前進到下一個教學課程：