你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

适用于：所有 API 管理层级

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

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

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

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

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

先决条件

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

添加新的修订版

1. 登录到 Azure 门户，并转到你的 API 管理实例。

2. 在左侧菜单中的 API 下，选择 API。

3. 从 API 列表中选择“演示会议 API”（或想要添加修订的其他 API）。

4. 选择“修订”选项卡。

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

   

   提示

   也可以在 API 上的上下文菜单 (…) 中选择“添加修订” 。

6. 提供新修订版的说明，帮助记住其用途。

7. 选择创建。

8. 现已创建新的修订版。

   注意

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

对修订版进行非重大更改

1. 从 API 列表中选择“演示会议 API”。

2. 选择靠近屏幕顶部的“设计”选项卡。

3. 请注意，修订版选择器（位于“设计”选项卡正上方）显示“修订版 2”为当前所选项。

   提示

   使用修订版选择器可在要使用的修订版之间切换。

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

5. 将新操作设置为“POST”，将操作的“显示名称”、“名称”和 URL 设置为“test”。

6. 保存新操作。

   

7. 现在，已对“修订版 2”进行了更改。 使用靠近页面顶部的“修订版选择器”切换回到“修订版 1” 。

8. 请注意，新操作不会出现在“修订版 1”中。

将修订版设为当前版本并添加更改日志项目

Portal

1. 在靠近页面顶部的菜单中选择“修订”选项卡。

2. 打开“修订版 2”对应的上下文菜单 (...)。

3. 选择“设为当前版本”。

4. 如果想要发布有关此变更的说明，请选中“发布有关此 API 的公共变更日志”复选框。 提供可让开发人员看到的更改说明，例如：“测试修订。添加了新的‘测试’操作”。

5. 修订版 2 现在是当前版本。

   

Azure CLI

开始使用 Azure CLI：

• 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅 Azure Cloud Shell 中的 Bash 快速入门。

  

• 如需在本地运行 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。

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

1. 运行 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 列中。

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

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

3. 若要查看版本，请使用 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
   

   指定的注释显示在更改日志中。 可以在前一个命令的输出中看到这些注释。

4. 创建版本时，可选用 --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 变更和这里的变更日志。

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

访问 API 修订

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

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

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

提示

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

总结

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

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

后续步骤

转到下一教程：

发布 API 的多个版本