使用修订安全做出非重大更改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 列表中选择“演示会议 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

    Tip

    也可以在 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.

    Note

    原始 API 保留在“修订版 1”中。Your 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 列表中选择“演示会议 API”。Select Demo Conference API from the API list.

  2. 选择靠近屏幕顶部的“设计”选项卡。Select the Design tab near the top of the screen.

  3. 请注意,修订版选择器(位于“设计”选项卡正上方)显示“修订版 2”为当前所选项。Notice that the revision selector (directly above the design tab) shows Revision 2 as currently selected.

    Tip

    使用修订版选择器可在要使用的修订版之间切换。Use the revision selector to switch between revisions that you wish to work on.

  4. 选择“+ 添加操作”。Select + Add Operation.

  5. 将新操作设置为“POST”,将操作的“名称”、“显示名称”和 URL 设置为“test”。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. 请注意,新操作未出现在“修订版 1”中。Notice 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”、“演示会议 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: