教程：使用修订安全地进行非中断性 API 更改

项目
09/01/2024

适用于：所有 API 管理层级

当 API 准备就绪并可供开发人员使用时，你最终需要对该 API 进行更改，同时避免干扰 API 的调用方。另一种有效的做法是让开发人员知道所做的更改。

在 Azure API Management 中，使用修订进行非中断性 API 变更，以便可以安全地对变更进行建模和测试。准备就绪后，可以将修订设为当前版本并替换当前的 API。

有关背景知识，请参阅版本和修订。

本教程介绍如何执行下列操作：

添加新的修订版
对修订版进行非重大更改
将修订版设为当前版本并添加更改日志项目
浏览开发人员门户以查看更改与更改日志
访问 API 修订

先决条件

了解 Azure API 管理术语。
完成以下快速入门：创建一个 Azure API 管理实例。
此外，请完成以下教程：导入和发布第一个 API。

添加新的修订版

登录到 Azure 门户，并转到你的 API 管理实例。
在左侧菜单中的 API 下，选择 API。
从 API 列表中选择“演示会议 API”（或想要添加修订的其他 API）。
选择“修订”选项卡。
选择“+ 添加修订”。

提示

也可以在 API 上的上下文菜单 (…) 中选择“添加修订” 。
提供新修订版的说明，帮助记住其用途。
选择创建。
现已创建新的修订版。

注意

原始 API 保留在“修订版 1”中。这是在将其他修订版设为当前版本之前，用户继续调用的修订版。

对修订版进行非重大更改

从 API 列表中选择“演示会议 API”。
选择靠近屏幕顶部的“设计”选项卡。
请注意，修订版选择器（位于“设计”选项卡正上方）显示“修订版 2”为当前所选项。

提示

使用修订版选择器可在要使用的修订版之间切换。
选择“+ 添加操作”。
将新操作设置为“POST”，将操作的“显示名称”、“名称”和 URL 设置为“test”。
保存新操作。
现在，已对“修订版 2”进行了更改。使用靠近页面顶部的“修订版选择器”切换回到“修订版 1” 。
请注意，新操作不会出现在“修订版 1”中。

在靠近页面顶部的菜单中选择“修订”选项卡。
打开“修订版 2”对应的上下文菜单 (...)。
选择“设为当前版本”。
如果想要发布有关此变更的说明，请选中“发布有关此 API 的公共变更日志”复选框。提供可让开发人员看到的更改说明，例如：“测试修订。添加了新的‘测试’操作”。
修订版 2 现在是当前版本。

开始使用 Azure CLI：

可以使用本地 Azure CLI。

如果需要，请安装 Azure CLI 来运行 CLI 参考命令。
本地 Azure 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。

使用此过程创建和更新版本。

运行 az apim api list 命令以查看 API ID：
```
az apim api list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table
```
要在下一个命令中使用的 API ID 是 Name 值。 API 版本位于 ApiRevision 列中。

若要创建版本和发行说明，请运行 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.'

你发布的修订版即为当前修订版。

若要查看版本，请使用 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
```
指定的注释显示在更改日志中。可以在前一个命令的输出中看到这些注释。

创建版本时，可选用 --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 列中的值作为版本 ID。

可以通过运行 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 变更和这里的变更日志。

在 Azure 门户，导航到 API 管理实例。
在左侧菜单中的 API 下，选择 API。
在顶部菜单中选择“开发人员门户”。
在开发人员门户中，选择“API”，然后选择“演示会议 API” 。
请注意，新的“测试”操作现已显示。
选择 API 名称旁边的“Changelog”。
请注意，你的更改日志条目已显示在列表中。

访问 API 修订

可以使用特殊格式的 URL 访问 API 的每个修订版。在 API URL 路径的末尾，但在查询字符串之前添加 ;rev={revisionNumber}，以访问该 API 的特定修订版。例如，可以使用此 URL 访问演示会议 API 的修订版 2：

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

可以在 Azure 门户中的“修订”选项卡上找到 API 修订的 URL 路径。

门户中修订 URL 的屏幕截图。

提示

除了将 ;rev={revisionNumber} 追加到 API 路径的完整 URL 之外，还可以使用不带 ;rev 字符串的 API 路径访问 API 的当前修订。

总结

在本教程中，你了解了如何执行以下操作：

添加新的修订版
对修订版进行非重大更改
将修订版设为当前版本并添加更改日志项目
浏览开发人员门户以查看更改与更改日志
访问 API 修订

后续步骤

转到下一教程：

发布 API 的多个版本

通过