共用方式為

Azure API 管理中的版本

適用於：所有 API 管理層級

版本可讓您向開發人員呈現相關 API 群組。 您可以使用版本安全地處理 API 中的重大變更。 用戶端在準備就緒時可以選擇使用新的 API 版本，而現有的用戶端則繼續使用較舊的版本。 版本會透過版本識別碼來區分（這是您選擇的任何字串值），而版本控制配置可讓客戶端識別他們要使用的 API 版本。 本文說明如何在 API 管理中使用版本。

就多數用途而言，每個 API 版本都可被視為本身的獨立 API。 兩個不同的 API 版本可能會有不同的作業集和不同的原則。

透過使用版本，您可以：

  • 同時發佈多個版本的 API。
  • 使用路徑、查詢字串或標頭來區分版本。
  • 使用您想要識別版本的任何字串值。 它可以是數位、日期或名稱。
  • 在開發人員入口網站上顯示群組在一起的 API 版本。
  • 建立新版的現有 （非版本化） API，而不會影響現有的用戶端。

透過完成操作指南來開始使用版本。

版本控制配置

不同的 API 開發人員對於版本設定有不同的需求。 Azure API 管理不會針對版本設定指定單一方法，而是提供數個選項。

路徑型版本控制

使用路徑版本設定配置時，版本標識碼必須包含在任何 API 要求的 URL 路徑中。

例如， https://apis.contoso.com/products/v1 和 https://apis.contoso.com/products/v2 可以參考相同的 products API，但參考版本 v1 和 v2。

當您使用路徑型版本控制時，API 要求 URL 的格式為 https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}。

基於標頭的版本控制

使用標頭版本設定配置時，版本標識碼必須包含在任何 API 要求的 HTTP 要求標頭中。 您可以指定 HTTP 要求標頭的名稱。

例如，您可以建立名為 Api-Version的自訂標頭，而用戶端可以在此標頭的值中指定 v1 或 v2 。

查詢以字串為基礎的版本控制

使用查詢字串版本設定配置時，版本標識碼必須包含在任何 API 要求的查詢字串參數中。 您可以指定查詢字串參數的名稱。

當您使用查詢字串型版本設定時，API 要求 URL 格式為 https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}。

例如， https://apis.contoso.com/products?api-version=v1 和 https://apis.contoso.com/products?api-version=v2 可以參考相同的 products API，但參考版本 v1 和 v2。

備註

OpenAPI 規格的 屬性中不允許 servers 查詢參數。 如果您從 API 版本匯出 OpenAPI 規格，查詢字串就不會出現在伺服器 URL 中。

原始版本

如果您將版本新增至非版本設定的 API， Original 系統會自動建立版本，並在預設 URL 上回應，而不會指定版本識別碼。 版本 Original 可確保任何現有的呼叫端都不會受到新增版本的程序影響。 如果您一開始建立已啟用版本的新 API，則不會建立 Original 版本。

如何表示版本

API 管理會維護稱為 版本集的資源，代表單一邏輯 API 的一組版本。 版本集合包含版本設定 API 的顯示名稱，以及用來將要求導向至指定版本的 版本設定配置 。

每個 API 版本都會維護為自己的 API 資源，並與版本集相關聯。 版本集合可能包含具有不同作業或原則的 API。 您可能會在集合中的版本之間進行重大變更。

Azure 入口網站會為您建立版本集。 您可以在 Azure 入口網站中修改版本集的名稱和描述。

刪除最終版本時，系統會自動刪除版本集。

您可以使用 Azure CLI、 Azure PowerShell、 Resource Manager 範本或 Azure Resource Manager API，直接檢視和管理版本集合。

備註

版本集合中的所有版本都有相同的版本控制配置。 這是根據您第一次將版本新增至 API 時所使用的版本控制方案。

將非版本化 API 移轉至已建立版本的 API

當您使用 Azure 入口網站在現有的 API 上啟用版本控制時，您的 API 管理資源會進行下列變更：

  • 系統會建立新的版本集合。
  • 現有的版本會維持並 設定為 Original API 版本。 API 會連結至版本集合，但不需要指定版本識別碼。
  • 新版本會建立為新的 API，並連結至版本集合。 版本設定配置和標識碼必須用來存取新的 API。

版本和修訂

版本和修訂是不同的功能。 每個版本都可以有多個修訂，就像非版本化 API 一樣。 您可以使用修訂而不使用版本，或只使用版本而不使用修訂。 一般而言，版本是用來分隔具有重大變更的 API 版本，而修訂可用於 API 的次要和非中斷性變更。

如果您發現修訂有重大變更，或您想要正式將修訂轉換成 Beta/測試版本，您可以從修訂建立版本。 在 Azure 入口網站中的 [修訂] 索引標籤上，選取修訂內容功能表 (…) 中的 [從此修訂建立版本]。

開發人員入口網站

開發人員入口網站會分別列出每個版本的 API：

顯示 API 管理開發人員入口網站中已建立版本 API 清單的螢幕快照。

在 API 的詳細資料中，您也可以查看 API 的所有版本清單。 顯示的版本是沒有版本識別碼的：

顯示 API 詳細資料和 API 管理開發人員入口網站中 API 版本清單的螢幕快照。

小提示

您必須將 API 版本新增至產品，使其顯示在開發人員入口網站中。

  • Last updated on