教程:发布 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.

向产品添加版本

浏览开发人员门户以查看版本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: