Azure API 管理中的修訂

  • 發行項

適用於：所有 API 管理 層

修訂可讓您以受控且安全的方式變更 API。 當您想要進行變更時，請建立新的修訂。 接著，您可以編輯和測試 API，而不會干擾您的 API 取用者。 準備就緒後，請您接著讓修訂變成最新狀態。 同時，您可以選擇性地將項目張貼至變更記錄，讓您的 API 取用者隨時掌握已變更的項目。 變更記錄會發佈至開發人員入口網站。

注意

使用層不提供開發人員入口網站。

有了修訂，您就可以：

  • 安全地變更 API 定義和原則，而不會干擾生產 API。
  • 在發佈變更之前先試用看看。
  • 記錄您所做的變更，讓開發人員可以了解最新的變更。
  • 在發現問題時復原。

依照我們的逐步解說開始使用修訂。

存取特定修訂

您可以使用特殊格式的 URL 來存取 API 的每個修訂。 請在 API URL 的結尾附加 ;rev={revisionNumber} (但要在查詢字串之前)，以存取該 API 的特定修訂。 例如，您可以使用此 URL 來存取 customers API 的修訂 3：

https://apis.contoso.com/customers;rev=3/leads?customerId=123

根據預設，每個修訂都有與目前修訂相同的安全性設定。 如果想要針對每個修訂套用不同的安全性，您可以刻意變更特定修訂的原則。 例如，您可能會想要新增 IP 篩選原則，以防止外部呼叫端存取仍在開發中的修訂。

注意

;rev={id} 必須附加至 API 識別碼，而不是 URI 路徑。

目前的修訂

單一的修訂可以設定為目前的修訂。 當 API 要求未在 URL 中明確指定修訂編號時，就會使用此修訂。 您可以復原至先前的修訂，方法是將其設定為目前的修訂。

您可以使用 Azure 入口網站，將修訂設定為目前的修訂。 如果您使用 PowerShell，則可以使用 New-AzApiManagementApiRelease Cmdlet。

修訂描述

當您建立修訂時，您可以設定自己追蹤用途的描述。 系統不會對您的 API 使用者顯示描述。

當您將修訂設定為目前修訂時，也可以選擇性地指定公用變更記錄檔附註。 開發人員入口網站中會包含變更記錄檔，可供您的 API 使用者來檢視。 您可以使用 Update-AzApiManagementApiRelease PowerShell Cmdlet 來修改變更記錄檔附註。

警告

如果您正在編輯 API 的非目前修訂，則無法變更下列屬性：

  • 名稱
  • 類型​​
  • Description
  • 需要訂用帳戶
  • API 版本
  • API 版本描述
  • 路徑
  • 通訊協定

這些屬性只能在目前的修訂中變更。 如果您的編輯變更非目前修訂的任何上述屬性，則會顯示錯誤訊息 Can't change property for non-current revision。

使修訂離線

修訂離線時，呼叫端便無法存取，即使呼叫端嘗試透過其 URL 來存取修訂也是不行。 您可以使用 Azure 入口網站將修訂標示為離線。

注意

建議您在未使用修訂時使其離線看看，做為測試。

版本和修訂

版本和修訂是不同的功能。 每個版本可以有多個修訂，就像非版本化 API 一樣。 您可以使用修訂而不使用版本，或反向操作。 一般而言，版本用來區隔具有重大變更的 API 版本，而修訂則用於 API 的次要和非重大變更。

如果您發現修訂有重大變更，或是您想要正式將修訂轉換成 Beta/測試版本，您可以從修訂建立版本。 使用 Azure 入口網站，在 [修訂] 索引標籤上的修訂操作功能表中按一下 [從修訂建立版本]。