教程:使用修订安全地进行非中断性 API 变更Tutorial: Use revisions to make non-breaking API 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 Management 中,使用修订进行非中断性 API 变更,以便可以安全地对变更进行建模和测试。In Azure API Management, use revisions to make non-breaking API changes so you can model and test changes safely. 准备就绪后,可以将修订设为当前版本并替换当前的 API。When ready, you can make a revision current and replace your current API.

有关背景知识,请参阅版本和修订使用 Azure API Management 进行 API 版本控制For background, 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

Azure 门户中的 API 修订

先决条件Prerequisites

添加新的修订版Add a new revision

  1. 登录到 Azure 门户,并导航到 API Management 实例。Sign in to the Azure portal, and navigate to your API Management instance.

  2. 选择“API”。Select APIs.

  3. 从 API 列表中选择“演示会议 API”(或想要添加修订的其他 API)。Select Demo Conference API from the API list (or another API to which you want to add revisions).

  4. 选择“修订”选项卡。Select the Revisions tab.

  5. 选择“+ 添加修订”。Select + Add revision.

    添加 API 修订版本

    提示

    也可以在 API 上的上下文菜单 (…) 中选择“添加修订” 。You can also select Add revision in the context menu (...) of the API.

  6. 提供新修订版的说明,帮助记住其用途。Provide a description for your new revision, to help remember what it will be used for.

  7. 选择“创建”,Select Create,

  8. 现已创建新的修订版。Your new revision is now created.

    备注

    原始 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.

    提示

    使用修订版选择器可在要使用的修订版之间切换。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”进行了更改。You've now made a change to Revision 2. 使用靠近页面顶部的“修订版选择器”切换回到“修订版 1” 。Use 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 的公共变更日志”复选框。Select the Post to Public Change log for this API checkbox, 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

如果已尝试使用开发人员门户,则可以查看 API 变更和这里的变更日志。If you've tried the developer portal, you can review the API changes and change log there.

  1. 在 Azure 门户中,选择“API”。In the Azure portal, select APIs.
  2. 在顶部菜单中选择“开发人员门户”。Select Developer portal from the top menu.
  3. 在开发人员门户中,选择“API”,然后选择“演示会议 API” 。In the developer portal, select APIs, and then select Demo Conference API.
  4. 请注意,新的“测试”操作现已显示。Notice your new test operation is now available.
  5. 选择 API 名称旁边的“Changelog”。Select Changelog near 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: