教程:发布 API 的多个版本Tutorial: Publish multiple versions of your API

有时,让 API 的所有调用方都使用完全相同的版本是不切实际的。There are times when it's impractical to have all callers to your API use exactly the same version. 如果调用方想要升级到更高版本,他们会希望采用一种易于理解的方法来实现此目的。When callers want to upgrade to a later version, they want an approach that's easy to understand. 如本教程所示,可以在 Azure API 管理中提供多个版本。As shown in this tutorial, it is possible to provided multiple versions in Azure API Management.

有关背景知识,请参阅版本与修订For background, see Versions & revisions.

在本教程中,你将了解如何执行以下操作:In this tutorial, you learn how to:

  • 将新版本添加到现有 APIAdd a new version to an existing API
  • 选择版本方案Choose a version scheme
  • 将版本添加到产品Add the version to a product
  • 浏览开发人员门户以查看版本Browse the developer portal to see the version

Azure 门户中显示的版本

必备条件Prerequisites

添加新版本Add a new version

  1. Azure 门户,导航到 API 管理实例。In the Azure portal, navigate to your API Management instance.
  2. 选择“API”。Select APIs.
  3. 从 API 列表中选择“演示会议 API”。Select Demo Conference API from the API list.
  4. 选择“演示会议 API”旁边的上下文菜单 。Select the context menu (...) next to Demo Conference API.
  5. 选择“添加版本”。Select Add version.

API 上下文菜单 - 添加版本

提示

创建新 API 时也可启用版本。Versions can also be enabled when you create a new API. 在“添加 API”屏幕上,选择“对此 API 进行版本控制?” 。On the Add API screen, select Version this API?.

选择版本控制方案Choose a versioning scheme

在 Azure API 管理中,可通过选择“版本控制方案”来选择调用方指定 API 版本的方式:路径、标头或查询字符串 。In Azure API Management, you choose how callers specify the API version by selecting a versioning scheme: path, header, or query string. 在下面的示例中,路径用作版本控制方案。In the following example, path is used as the versioning scheme.

输入下表中的值。Enter the values from the following table. 然后选择“创建”以创建版本。Then select Create to create your version.

“添加版本”窗口

设置Setting “值”Value 说明Description
NameName demo-conference-api-v1demo-conference-api-v1 API 管理实例中的唯一名称。Unique name in your API Management instance.

因为某个版本实际上是一个基于 API 修订版的新 API,所以此设置为新 API 的名称。Because a version is in fact a new API based off an API's revision, this setting is the new API's name.
版本控制方案Versioning scheme 路径Path 调用方指定 API 版本的方式。The way callers specify the API version.
版本标识符Version identifer v1v1 特定于方案的版本指示符。Scheme-specific indicator of the version. 对于“路径”,其标识符应为 API URL 路径的后缀。For Path, the suffix for the API URL path.

如果选择“标头”或“查询字符串”,请输入附加的值:标头或查询字符串参数的名称。 If Header or Query string is selected, enter an additional value: the name of the header or query string parameter.

将显示一个用法示例。A usage example is displayed.
产品Products 不受限制Unlimited (可选)与 API 版本关联的一个或多个产品。Optionally, one or more products that the API version is associated with. 若要发布 API,必须将其与某个产品相关联。To publish the API, you must associate it with a product. 稍后还可将版本添加到产品You can also add the version to a product later.

创建版本后,它现在显示在 API 列表中的“演示会议 API”下。After creating the version, it now appears underneath Demo Conference API in the API List. 现在会看到两个 API:“原始”和“v1” 。You now see two APIs: Original, and v1.

Azure 门户中 API 下面列出的版本

现在,可以编辑和配置“v1”使其作为与“原始”API 不同的独立 API。 You can now edit and configure v1 as an API that is separate from Original. 对一个版本进行更改不会影响另一个版本。Changes to one version do not affect another.

备注

如果为不受版本控制的 API 添加了版本,还会自动创建“原始”API。If you add a version to a non-versioned API, an Original is also automatically created. 此版本是对默认 URL 的响应。This version responds on the default URL. 创建“原始”版本可确保所有现有调用方不会被添加版本的过程中断。Creating an Original version ensures that any existing callers are not broken by the process of adding a version. 如果在一开始就启用了版本的情况下创建新 API,则不会创建“原始”API。If you create a new API with versions enabled at the start, an Original isn't created.

将版本添加到产品Add the version to a product

要使调用方看到新版本,必须将该版本添加到 产品In order for callers to see the new version, it must be added to a product. 如果尚未将版本添加到产品,可以随时将其添加到产品。If you didn't already add the version to a product, you can add it to a product at any time.

例如,若要将版本添加到“不受限制”产品:For example, to add the version to the Unlimited product:

  1. 在 Azure 门户,导航到 API 管理实例。In the Azure portal, navigate to your API Management instance.
  2. 选择“产品” > “不受限制” > “API” > “+ 添加” 。Select Products > Unlimited > APIs > + Add.
  3. 选择“演示会议 API”、版本“v1”。 Select Demo Conference API, version v1.
  4. 单击“选择”。Click Select.

向产品添加版本

使用版本集Use version sets

创建多个版本时,Azure 门户会创建一个版本集,它表示单个逻辑 API 的一组版本。When you create multiple versions, the Azure portal creates a version set, which represents a set of versions for a single logical API. 选择具有多个版本的 API 的名称。Select the name of an API that has multiple versions. Azure 门户会显示其版本集。The Azure portal displays its Version set. 你可以自定义虚拟集的名称和说明 。You can customize the Name and Description of a virtual set.

你可以通过使用 Azure CLI 直接与版本集交互:You can interact directly with version sets by using the Azure CLI:

  • 如果需要,请安装 Azure CLI 来运行 CLI 参考命令。If you prefer, install the Azure CLI to run CLI reference commands.

    • 如果使用的是本地安装,请使用 az login 命令登录到 Azure CLI。If you're using a local installation, sign in to the Azure CLI by using the az login command. 若要完成身份验证过程,请遵循终端中显示的步骤。To finish the authentication process, follow the steps displayed in your terminal. 有关其他登录选项,请参阅登录 Azure CLIFor additional sign-in options, see Sign in with the Azure CLI.

    • 出现提示时,请在首次使用时安装 Azure CLI 扩展。When you're prompted, install Azure CLI extensions on first use. 有关扩展详细信息,请参阅使用 Azure CLI 的扩展For more information about extensions, see Use extensions with the Azure CLI.

    • 运行 az version 以查找安装的版本和依赖库。Run az version to find the version and dependent libraries that are installed. 若要升级到最新版本,请运行 az upgradeTo upgrade to the latest version, run az upgrade.

若要查看所有版本集,请运行 az apim api versionset list 命令:To see all your version sets, run the az apim api versionset list command:

az apim api versionset list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

当 Azure 门户为你创建一个版本集时,它会分配一个字母数字名称并显示在列表的“名称”列中。When the Azure portal creates a version set for you, it assigns an alphanumeric name, which appears in the Name column of the list. 在其他 Azure CLI 命令中使用此名称。Use this name in other Azure CLI commands.

若要查看有关版本集的详细信息,请运行 az apim api versionset show 命令:To see details about a version set, run the az apim api versionset show command:

az apim api versionset show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

有关版本集的详细信息,请参阅 Azure API 管理中的版本For more information about version sets, see Versions in Azure API Management.

浏览开发人员门户以查看版本Browse the developer portal to see the version

如果已试用开发人员门户,可在此处查看 API 版本。If you've tried the developer portal, you can see API versions there.

  1. 在顶部菜单中选择“开发人员门户”。Select Developer Portal from the top menu.
  2. 依次选择“API”、“演示会议 API”。Select APIs, and then select Demo Conference API.
  3. 可在 API 名称旁边看到一个含有多个版本的下拉列表。You should see a dropdown with multiple versions next to the API name.
  4. 选择“v1”。Select v1.
  5. 请注意列表中第一个操作的“请求 URL”。Notice the Request URL of the first operation in the list. 其中显示 API URL 路径包含“v1”。It shows that the API URL path includes v1.

后续步骤Next steps

在本教程中,你了解了如何执行以下操作:In this tutorial, you learned how to:

  • 将新版本添加到现有 APIAdd a new version to an existing API
  • 选择版本方案Choose a version scheme
  • 将版本添加到产品Add the version to a product
  • 浏览开发人员门户以查看版本Browse the developer portal to see the version

转到下一教程:Advance to the next tutorial: