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 版本。

版本的呈現方式

Azure 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 的所有版本。 顯示沒有版本識別碼的 Original 版本。

API 管理 開發人員入口網站，其中顯示 API 的詳細數據和該 API 的版本清單

提示

API 版本必須先新增至產品，才能顯示在開發人員入口網站上。