教程：发布 API 的多个版本

2025/07/11

适用于：所有 API 管理层级

在某些情况下，所有 API 使用者都使用相同的版本是不切实际的。当使用者准备好升级到较新版本时，他们更喜欢一种简单且易于理解的方法。如本教程所示，Azure API 管理支持公开多个 API 版本以满足此需求。

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

本教程中，您将学习如何：

将新版本添加到现有 API
选择版本方案
将版本添加到产品
在开发人员门户中查看版本

先决条件

添加新版本

在 Azure 门户，导航到 API 管理实例。
在左侧菜单中的 “API ”部分，选择 API。
在 API 列表中找到 Swagger Petstore - OpenAPI 3.0 。选择“Swagger Petstore - OpenAPI 3.0”旁边的省略号 (...)，然后选择“添加版本”。在下一部分中，你将向生成的窗口添加值。

提示

还可以在创建新 API 时启用版本。在“添加 API”屏幕上，选择“对此 API 进行版本控制?”。

选择版本控制方案

在 API 管理中，通过选择 版本控制方案，选择调用方如何指定 API 版本：路径、标头或 查询字符串。在以下示例中， Path 用作版本控制方案。

在 “创建新 API 作为版本 ”窗口中，输入下表中的值。然后选择“创建”以创建版本。

设置	价值	DESCRIPTION
版本标识符	v1	特定于方案的版本指示符。对于“路径”，其标识符应为 API URL 路径的后缀。
版本控制方案	路径	调用方指定 API 版本的方式。如果选择 “标头 ”或 “查询”字符串，请输入另一个值：标头或查询字符串参数的名称。将显示一个用法示例。
完整 API 版本名称	swagger-petstore-openapi-3-0-v1	API 管理实例中的唯一名称。由于版本实际上是基于 API 修订的新 API，因此此值是新 API 的名称。
产品	无限制（在某些服务层级中提供）	（可选）与 API 版本关联的一个或多个产品。若要发布 API，必须将其与某个产品相关联。稍后还可将版本添加到产品。

创建版本后，它会显示在 API 列表中的 Swagger Petstore - OpenAPI 3.0 下。现在会看到两个 API：原始 API 和 v1：

备注

如果将版本添加到非版本控制 API，也会自动创建原始版本。此版本在默认的 URL 上响应。原始版本可确保从现有调用方发出的调用在添加版本后仍然有效。如果在一开始就启用了版本的情况下创建新 API，则不会创建“原始”API。

编辑版本

添加版本后，可以编辑并将其配置为独立于原始版本的 API。针对一个版本的更改不会影响另一个版本（例如，如果添加或删除 API 操作，或编辑 OpenAPI 规范）。有关详细信息，请参阅编辑 API。

将版本添加到产品

要让呼叫者查看新版本，必须将它添加到产品中。如果尚未将版本添加到产品，可随时这样操作。

若要将版本添加到产品，请执行以下操作：

在 Azure 门户，导航到 API 管理实例。
在左窗格中的 API 下，选择“ 产品”。
选择产品，然后在左窗格中选择 API 。
选择 + 添加。
选择 API。
单击“选择”。

使用版本集

创建多个版本时，Azure 门户会创建一个版本集，它表示单个逻辑 API 的一组版本。如果选择具有多个版本的 API 的名称，门户将显示其版本集。可以自定义版本集的名称和说明。

你可以通过使用 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 <resource-group-name> \
    --service-name <API-Management-service-name> --output table

当 Azure 门户为你创建一个版本集时，它会分配一个字母数字名称并显示在列表的“名称”列中。在其他 Azure CLI 命令中使用此名称。

若要查看有关版本集的详细信息，请运行 az apim api versionset show 命令：

az apim api versionset show --resource-group <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

有关版本集的详细信息，请参阅 Azure API 管理中的版本。

在开发人员门户中查看版本

如果使用开发人员门户，可以在其中查看 API 版本。

选择窗口顶部的 开发人员门户 。
选择API，然后选择Swagger Petstore。
应会看到一个下拉列表，其中列出了 API 名称旁边的多个版本。
选择“v1”。
请注意列表中第一个操作的“请求 URL”。这表明 API URL 路径包含v1。

后续步骤

转到下一教程：

自定义开发人员门户页面的样式

通过