教學課程：使用修訂安全地進行不間斷的 API 變更

適用於：所有 APIM 層

當您的 API 已準備好供開發人員使用時，則須變更該 API，同時避免中斷 API 呼叫者的作業。 這對於讓開發人員了解您所做的更改也相當有用。

在 Azure API 管理中使用修訂進行不間斷的 API 變更，以安全地建立變更的模型及測試變更。 準備就緒後，您即可將修訂設為最新版本，並取代您目前的 API。

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

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

• 新增修訂
• 對您的修訂進行不間斷變更
• 請讓您的修訂為最新版本，並新增變更記錄項目
• 瀏覽開發人員入口網站，以查看變更與變更記錄檔
• 存取 API 修訂

必要條件

• 了解 Azure API 管理術語。
• 完成下列快速入門：建立 Azure API 管理執行個體。
• 同時也請完成下列教學課程：匯入和發佈您的第一個 API。

新增修訂

1. 登入 Azure 入口網站，並瀏覽至您的 API 管理執行個體。

2. 在左側功能表 的 [API] 底下，選取 [API]。

3. 從 API 清單中選取 [Demo Conference API] (或其他要新增修訂的 API)。

4. 選取 [修訂] 索引標籤。

5. 選取 [+ 新增修訂]。

   

   提示

   您也可以在 API 的操作功能表 (...) 中選取 [新增修訂]。

6. 提供新修訂的描述，以便您記得其用途。

7. 選取 建立。

8. 現在已建立新的修訂。

   注意

   原始的 API 會保留在修訂 1。 這是您的使用者將繼續呼叫的修訂，直到您選擇進行其他修訂為止。

對您的修訂進行不間斷變更

1. 從 API 清單中選取 [Demo Conference API]。

2. 選取畫面頂端附近的 [設計] 索引標籤。

3. 請注意，修訂選取器 (在 [設計] 索引標籤的正上方) 會顯示目前已選取修訂 2。

   提示

   使用修訂選取器在您要進行的修訂之間切換。

4. 選取 [+ 新增作業]。

5. 將新作業設定為 POST，並將作業的 [顯示名稱]、[名稱] 和 [URL] 設為 test。

6. 儲存您的新作業。

   

7. 現在，您已對修訂 2 進行變更。 請使用頁面頂端附近的 [修訂選取器] 切換回修訂 1。

8. 請注意，修訂版本 1不會顯示新作業。

請讓您的修訂為最新版本，並新增變更記錄項目

入口網站

1. 從頁面頂端附近的功能表選取 [修訂] 索引標籤。

2. 針對修訂 2 開啟操作功能表 (...)。

3. 選取 [設為目前版本]。

4. 如果您想要發佈這項變更的相關注意事項，請選取 [發佈到此 API 的公用變更記錄] 核取方塊。 提供讓開發人員能夠查看的變更說明，例如：測試修訂。已新增「測試」作業。

5. 修訂 2 目前為最新狀態。

   

Azure CLI

開始使用 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。

使用此程序來建立和更新版本。

1. 執行 az apim api list 命令查看您的 API 識別碼：

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   下一個命令中要使用的 API 識別碼為 Name 值。 API 修訂位於 ApiRevision 資料行。

2. 若要建立含版本附註的版本，請執行 az apim api release create 命令：

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   您所發行的修訂隨即成為目前修訂。

3. 若要查看您的版本，請使用 az apim api release list 命令：

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   變更記錄會顯示於指定的附註。 您可在先前命令輸出中看到附註。

4. 建立版本時，--notes 參數為選擇性。 您稍後可使用 az apim api release update 命令來新增或變更附註：

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   使用 Name 資料行中的值作為版本識別碼。

您可執行下列 az apim api release delete 命令來移除版本：

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

瀏覽開發人員入口網站，以查看變更與變更記錄檔

如果您嘗試開發人員入口網站，則可在該處檢閱 API 變更並變更記錄。

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左側功能表 的 [API] 底下，選取 [API]。
3. 從頂端功能表中選取 [開發人員入口網站]。
4. 在開發人員入口網站中選取 [API]，然後選取 [Demo Conference API]。
5. 請注意，您現在可以使用新的測試作業。
6. 選取 API 名稱附近的 [變更記錄]。
7. 請注意，您的變更記錄項目會顯示於清單。

存取 API 修訂

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

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

您可以在 Azure 入口網站的 [修訂] 索引標籤上，找到 API 修訂的 URL 路徑。

提示

除了將 附加至 API 路徑的完整 URL 之外，您還可使用不含 ;rev 字串的 API 路徑，存取 API 的「目前」;rev={revisionNumber}修訂。

摘要

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

• 新增修訂
• 對您的修訂進行不間斷變更
• 請讓您的修訂為最新版本，並新增變更記錄項目
• 瀏覽開發人員入口網站，以查看變更與變更記錄檔
• 存取 API 修訂

下一步

前進到下一個教學課程：

為您的 API 發佈多個版本