教學課程：為您的 API 發佈多個版本

適用於：所有 APIM 層

在某些情況下，所有 API 取用者都使用相同的版本是不切實際的。 當取用者準備好升級至較新版本時，他們偏好簡單且可理解的方法。 如本教學課程所示，Azure API 管理支持公開多個 API 版本以符合此需求。

如需背景知識，請參閱版本與修訂。

秘訣

API 小組可以在工作區中使用此功能。 工作區提供 API 及其自有 API 執行階段環境的隔離系統管理存取權。

在本教學課程中，您會了解如何：

• 將新版本新增至現有 API
• 選擇版本配置
• 將版本新增至產品
• 在開發人員入口網站中檢視版本

先決條件

• 瞭解 Azure API 管理術語。
• 完成建立 Azure API 管理實例的快速入門。
• 完成教學課程 匯入並發佈您的第一個 API。

加入新版本

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左側功能表中的 [ API] 區段中，選取 [API]。
3. 在 API 清單中找出 Swagger Petstore - OpenAPI 3.0 。 選取 Swagger Petstore - OpenAPI 3.0 旁邊的省略號 （...），然後選取 [新增版本]。 您將在下一節中將值新增至結果視窗。

秘訣

您也可以在建立新的 API 時啟用版本。 在 [新增 API] 畫面上，選取 [要為此 API 設定版本嗎？]。

選擇版本設定配置

在 [API 管理] 中，您可以選取 版本控制配置來選擇呼叫者如何指定 API 版本： 路徑、 標頭或 查詢字串。 在下列範例中， Path 會作為版本設定配置使用。

在 [ 建立新的 API 作為版本 ] 視窗中，輸入下表中的值。 然後，選取 [建立] 以建立您的版本。

設定	值	說明
版本識別碼	v1	版本的配置特定指標。 路徑的識別碼為 API URL 路徑的尾碼。
版本設定配置	路徑	呼叫者指定 API 版本的方式。 如果您選取 [標頭 ] 或 [ 查詢字串]，請輸入另一個值：標頭或查詢字串參數的名稱。 請參考顯示的使用範例。
完整 API 版本名稱	swagger-petstore-openapi-3-0-v1	API 管理執行個體中的唯一名稱。 因為版本實際上是以 API 修訂為基礎的新 API，因此此值是新的 API 名稱。
產品	沒有限制 （在某些服務層級中提供）	(選擇性) 與 API 版本相關聯的一或多個產品。 若要發佈 API，您必須將它與產品產生關連。 您也可於後續將版本新增至產品。

建立版本之後，它會出現在 API 清單中的 Swagger Petstore - OpenAPI 3.0 底下。 您現在會看到兩個 API： 原始 和 v1：

附註

如果您將版本新增至非版本設定的 API，系統也會自動建立原始版本。 此版本會反映在預設 URL 上。 原始版本可確保現有呼叫端的呼叫在新增版本之後仍可運作。 如果您在開始時建立已啟用版本的新 API，則不會建立原始項目。

編輯版本

新增版本之後，您可以編輯並設定為與原始版本分開的 API。 對某個版本的變更不會影響另一個版本（例如，如果您新增或移除 API 作業，或編輯 OpenAPI 規格）。 如需詳細資訊，請參閱編輯 API。

將版本新增至產品

若要讓來電者查看新版本，必須將它新增至 產品。 如果您尚未將版本新增至產品，您可以隨時執行此動作。

若要將版本新增至產品：

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左窗格中的 [API] 下，選取 [ 產品]。
3. 選取產品，然後選取左窗格中的 [API ]。
4. 選取 [+ 新增]。
5. 選取 API。
6. 按一下 [選取]。

使用版本集

當您建立多個版本時，Azure 入口網站會建立「版本集」，代表單一邏輯 API 的一組版本。 如果您選取具有多個版本的 API 名稱，入口網站會顯示其版本集。 您可以自訂版本集的名稱和描述。

您可以使用 Azure CLI，直接與版本集互動：

• 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱開始使用 Azure Cloud Shell。

  

• 若要在本機執行 CLI 參考命令，請安裝 (部分機器翻譯) Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱如何在 Docker 容器中執行 Azure CLI。

  • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，以完成驗證流程。 如需其他登入選項，請參閱 使用 Azure CLI 向 Azure 進行驗證。

  • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能的詳細資訊，請參閱 使用和管理 Azure CLI 的擴充功能。

  • 執行 az version (部分機器翻譯) 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

若要查看所有版本集，請執行 az apim api versionset list 命令：

az apim api versionset list --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --output table

Azure 入口網站為您建立版本集時會指派英數字元名稱，該名稱出現在清單的 [名稱] 欄。 在其他 Azure CLI 命令中使用此名稱。

若要查看版本集的詳細資料，請執行 az apim api versionset show 命令：

az apim api versionset show --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

如需版本集的詳細資訊，請參閱 Azure API 管理中的版本。

在開發人員入口網站中檢視版本

如果您使用 開發人員入口網站，您可以在該處看到 API 版本。

1. 選取視窗頂端的 [開發人員入口網站 ]。
2. 選取 [API]，然後選取 [Swagger Petstore]。
3. 您應該會看到下拉式清單，其中列出 API 名稱旁的多個版本。
4. 選取 [v1]。
5. 請注意清單中第一項作業的 [要求 URL]。 它會顯示 API URL 路徑，包含 v1。

後續步驟

移至下一個教學課程：

自訂開發人員入口網站頁面的風格