教程：使用修订安全地进行不破坏性 API 更改

适用于：所有 API 管理层级

当开发者使用你的 API 时，你最终需要对该 API 进行更改，而不影响 API 的调用方。另一种有效的做法是让开发人员知道所做的更改。

在 Azure API 管理中，使用修订进行非中断性 API 更改。可以安全地对更改进行建模和测试。准备就绪后，使修订保持最新状态并替换当前 API。

有关详细信息，请参阅版本和修订。

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

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

先决条件

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

添加新的修订版

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

提示

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

现已创建新的修订版。

注意事项

原始 API 保留在“修订版 1”中。这是用户继续使用的修订，直到你选择将另一个修订设为当前版本。

对修订版进行非重大更改

从 API 列表中选择“Swagger Petstore”。
选择屏幕顶部附近的 “设计 ”。

设计选项卡上方的 修订选择器 显示当前选定的 修订 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 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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

浏览开发人员门户以查看更改与更改日志

如果尝试开发人员门户，可以查看 API 更改并更改日志。

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

访问 API 修订

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

https://apim-hello-world.azure-api.cn/store/pet/1;rev=2/

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

提示

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

总结

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

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

后续步骤

转到下一教程：

发布 API 的多个版本

Last updated on 2026-02-28

共用方式為