使用修訂項目安全地進行不間斷的變更Use revisions to make non-breaking changes safely

當您的 API 已準備就緒,且開發人員也已準備好使用時,您就必須對該 API 進行變更,同時避免中斷 API 呼叫者的作業。When your API is ready to go and starts to be used by developers, you eventually need to make changes to that API and at the same time not disrupt callers of your API. 這對於讓開發人員了解您所做的更改也相當有用。It's also useful to let developers know about the changes you made. 我們可以使用修訂在 Azure API 管理中進行此動作。We can do this in Azure API Management using revisions. 如需詳細資訊,請參閱版本與修訂使用 Azure API 管理的 API 版本設定For more information, see Versions & revisions and API Versioning with Azure API Management.

在本教學課程中,您了解如何:In this tutorial, you learn how to:

  • 新增修訂Add a new revision
  • 對您的修訂進行不間斷變更Make non-breaking changes to your revision
  • 請讓您的修訂為最新版本,並新增變更記錄項目Make your revision current and add a change log entry
  • 瀏覽開發人員入口網站,以查看變更與變更記錄檔Browse the developer portal to see changes and change log

開發人員入口網站上的變更記錄檔

必要條件Prerequisites

新增修訂Add a new revision

新增 API 修訂

  1. 選取 [API] 頁面。Select APIs page.

  2. 從 API 清單中選取 [Demo Conference API] (或其他您要新增修訂的 API)。Select Demo Conference API from the API list (or other API to which you want to add revisions).

  3. 從頁面頂端附近的功能表按一下 [修訂] 索引標籤。Click the Revisions tab from the menu near the top of the page.

  4. 選取 [+ 新增修訂] Select + Add Revision

    提示

    您也可以在 API 上選擇操作功能表 ( ... ) 中的 [新增修訂] 。You can also choose Add Revision in the context menu (...) of the API.

  5. 提供新修訂的描述,以協助您記住其用途。Provide a description for your new revision, to help remember what it will be used for.

  6. 選取 [建立] Select Create

  7. 現在已建立新的修訂。Your new revision is now created.

    注意

    原始的 API 會保留在修訂 1Your original API remains in Revision 1. 這是您的使用者將繼續呼叫的修訂,直到您選擇進行其他修訂為止。This is the revision your users continue to call, until you choose to make a different revision current.

對您的修訂進行不間斷變更Make non-breaking changes to your revision

修改修訂

  1. 從 API 清單中選取 [Demo Conference API] 。Select Demo Conference API from the API list.

  2. 選取畫面頂端附近的 [設計] 索引標籤。Select the Design tab near the top of the screen.

  3. 請注意,修訂選取器 (在 [設計] 索引標籤的正上方) 會顯示目前已選取修訂 2Notice that the revision selector (directly above the design tab) shows Revision 2 as currently selected.

    提示

    使用修訂選取器在您要進行的修訂之間切換。Use the revision selector to switch between revisions that you wish to work on.

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

  5. 將您的新作業設定為 POST,並將作業的「名稱、顯示名稱和 URL」設定為測試Set your new operation to be POST, and the Name, Display Name and URL of the operation as test.

  6. 儲存您的新作業。Save your new operation.

  7. 現在,我們已對修訂 2 進行變更。We have now made a change to Revision 2. 使用頁面頂端附近的 [修訂選取器] ,即可切換回修訂 1Use the Revision Selector near the top of the page to switch back to Revision 1.

  8. 請注意,新的作業不會出現在修訂 1Notice that your new operation does not appear in Revision 1.

請讓您的修訂為最新版本,並新增變更記錄項目Make your revision current and add a change log entry

  1. 從頁面頂端附近的功能表選取 [修訂] 索引標籤。Select the Revisions tab from the menu near the top of the page.

    修訂畫面上的 [修訂] 功能表。

  2. 針對修訂 2 開啟操作功能表 ( ... )。Open the context menu (...) for Revision 2.

  3. 選取 [設為最新] 。Select Make Current.

  4. 如果您想要發佈這項變更的相關注意事項,請核取 [發佈到此 API 的公用變更記錄檔] 。Check Post to Public Change log for this API, if you want to post notes about this change. 提供讓開發人員查看的變更說明,例如:測試修訂。已新增「測試」作業。Provide a description for your change that developers see, for example: Testing revisions. Added new "test" operation.

  5. 修訂 2 目前為最新狀態。Revision 2 is now current.

瀏覽開發人員入口網站,以查看變更與變更記錄檔Browse the developer portal to see changes and change log

  1. 在 Azure 入口網站中,選取 [API] 。In the Azure portal, select APIs.

  2. 從頂端功能表選取 [開發人員入口網站] 。Select Developer Portal from the top menu.

  3. 選取 [API] ,然後選取 [Demo Conference API] 。Select APIs, and then select Demo Conference API.

  4. 請注意,您現在可以使用新的測試作業。Notice your new test operation is now available.

  5. 從 API 名稱下方選取 [API 變更記錄] 。Select API Change History from below the API name.

  6. 請注意,您的變更記錄項目會出現在此清單中。Notice that your change log entry appears in this list.

    開發人員入口網站

後續步驟Next steps

在本教學課程中,您已了解如何:In this tutorial, you learned how to:

  • 新增修訂Add a new revision
  • 對您的修訂進行不間斷變更Make non-breaking changes to your revision
  • 請讓您的修訂為最新版本,並新增變更記錄項目Make your revision current and add a change log entry
  • 瀏覽開發人員入口網站,以查看變更與變更記錄檔Browse the developer portal to see changes and change log

前進到下一個教學課程:Advance to the next tutorial: