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

• 03/17/2021
• • J
  • D

有时，让 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:

必备条件Prerequisites

• 了解 Azure API 管理术语。Learn the Azure API Management terminology.
• 完成以下快速入门：创建 Azure API 管理实例。Complete the following quickstart: Create an Azure API Management instance.
• 此外，请完成以下教程：导入并发布第一个 API。Also, complete the following tutorial: Import and publish your first API.

添加新版本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.

选择版本控制方案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.

创建版本后，它现在显示在 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.

现在，可以编辑和配置“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.

将版本添加到产品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 CLI。For 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 upgrade。To 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:

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