教程：发布 API 的多个版本
适用于：所有 API 管理层级
有时，让 API 的所有调用方都使用完全相同的版本是不切实际的。 如果调用方想要升级到更高版本，他们会希望采用一种易于理解的方法来实现此目的。 如本教程所示，可以在 Azure API 管理中提供多个版本。
本教程介绍如何执行下列操作：
- 将新版本添加到现有 API
- 选择版本方案
- 将版本添加到产品
- 浏览开发人员门户以查看版本
先决条件
- 了解 Azure API 管理术语。
- 完成以下快速入门：创建一个 Azure API 管理实例。
- 此外，请完成以下教程：导入并发布第一个 API。
添加新版本
- 在 Azure 门户，导航到 API 管理实例。
- 选择“API”。
- 从 API 列表中选择“演示会议 API”。
- 选择“演示会议 API”旁边的上下文菜单 。
- 选择“添加版本”。
提示
创建新 API 时也可启用版本。 在“添加 API”屏幕上，选择“对此 API 进行版本控制?” 。
选择版本控制方案
在 Azure API 管理中，可通过选择“版本控制方案”来选择调用方指定 API 版本的方式：路径、标头或查询字符串 。 在下面的示例中，路径用作版本控制方案。
输入下表中的值。 然后选择“创建”以创建版本。
| 设置 | 值 | 描述 |
|---|---|---|
| Name | demo-conference-api-v1 | API 管理实例中的唯一名称。 因为某个版本实际上是一个基于 API 修订版的新 API，所以此设置为新 API 的名称。 |
| 版本控制方案 | 路径 | 调用方指定 API 版本的方式。 |
| 版本标识符 | v1 | 特定于方案的版本指示符。 对于“路径”，其标识符应为 API URL 路径的后缀。 如果选择“标头”或“查询字符串”，请输入附加的值：标头或查询字符串参数的名称。 将显示一个用法示例。 |
| 产品 | 不受限制 | （可选）与 API 版本关联的一个或多个产品。 若要发布 API，必须将其与某个产品相关联。 稍后还可将版本添加到产品。 |
创建版本后，它现在显示在 API 列表中的“演示会议 API”下。 现在会看到两个 API：“原始”和“v1” 。
注意
如果为不受版本控制的 API 添加了版本，还会自动创建“原始”API。 此版本是对默认 URL 的响应。 创建“原始”版本可确保所有现有调用方不会被添加版本的过程中断。 如果在一开始就启用了版本的情况下创建新 API，则不会创建“原始”API。
编辑版本
添加版本后，现在可以将其编辑并配置为独立于原始版本的 API。 对一个版本进行更改不会影响另一个版本。 例如，添加或移除 API 操作，或编辑 OpenAPI 规范。 有关详细信息，请参阅编辑 API。
将版本添加到产品
要使调用方看到新版本，必须将该版本添加到产品。 如果尚未将版本添加到产品，可以随时将其添加到产品。
例如，若要将版本添加到“不受限制”产品：
- 在 Azure 门户，导航到 API 管理实例。
- 选择“产品”>“不受限制”>“API”>“+ 添加” 。
- 选择“演示会议 API”、版本“v1”。
- 单击“选择”。
使用版本集
创建多个版本时，Azure 门户会创建一个版本集，它表示单个逻辑 API 的一组版本。 选择具有多个版本的 API 的名称。 Azure 门户会显示其版本集。 你可以自定义虚拟集的名称和说明 。
你可以通过使用 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 versionset list 命令：
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --output table
当 Azure 门户为你创建一个版本集时，它会分配一个字母数字名称并显示在列表的“名称”列中。 在其他 Azure CLI 命令中使用此名称。
若要查看有关版本集的详细信息，请运行 az apim api versionset show 命令：
az apim api versionset show --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
有关版本集的详细信息，请参阅 Azure API 管理中的版本。
浏览开发人员门户以查看版本
如果已试用开发人员门户，可在此处查看 API 版本。
- 在顶部菜单中选择“开发人员门户”。
- 依次选择“API”、“演示会议 API”。
- 可在 API 名称旁边看到一个含有多个版本的下拉列表。
- 选择“v1”。
- 请注意列表中第一个操作的“请求 URL”。 其中显示 API URL 路径包含“v1”。
后续步骤
在本教程中，你了解了如何执行以下操作：
- 将新版本添加到现有 API
- 选择版本方案
- 将版本添加到产品
- 浏览开发人员门户以查看版本
转到下一教程：