Azure API 管理中的版本

适用于：所有 API 管理层级

版本使你能够向开发人员呈现相关 API 组。 你可以使用版本安全地处理 API 中的重大更改。 客户端可以选择在准备就绪时使用新的 API 版本，而现有客户端将继续使用较旧的版本。 版本通过版本标识符（即你选择的任何字符串值）进行区分，版本控制方案允许客户端标识要使用的 API 版本。 本文介绍如何在 API 管理中使用版本。

在大多数情况下，可以将每个 API 版本视为其自身的独立 API。 两个不同的 API 版本可能具有不同的操作集和不同的策略。

通过版本，您可以：

• 同时发布多个版本的 API。
• 使用路径、查询字符串或标头区分版本。
• 使用任意字符串值来标识你的版本。 可以是数字、日期或名称。
• 在开发人员门户中显示分组的 API 版本。
• 创建现有（非版本控制）API 的新版本，而不会影响现有客户端。

通过完成演练开始使用版本。

版本控制方案

不同的 API 开发人员对版本控制有不同的要求。 Azure API 管理没有规定单一版本控制方法，而是提供多个选项。

基于路径的版本控制

使用路径版本控制方案时，需要在任何 API 请求的 URL 路径中包含版本标识符。

例如，https://apis.contoso.com/products/v1 和 https://apis.contoso.com/products/v2 可以引用相同的 products API，但分别引用版本 v1 和 v2。

使用基于路径的版本控制时，API 请求 URL 的格式为 https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}。

基于标头的版本控制

使用标头版本控制方案时，需要在任何 API 请求的 HTTP 请求标头中包含版本标识符。 可以指定 HTTP 请求标头的名称。

例如，您可以创建一个名为Api-Version的自定义标头，客户可以在此标头的值中指定v1或v2。

查询基于字符串的版本控制

使用查询字符串版本控制方案时，需要将版本标识符包含在任何 API 请求的查询字符串参数中。 可以指定查询字符串参数的名称。

使用基于查询字符串的版本控制时，API 请求 URL 的格式为 https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}。

例如，https://apis.contoso.com/products?api-version=v1 和 https://apis.contoso.com/products?api-version=v2 可能指的是相同的 products API，但指的是版本 v1 和 v2。

原始版本

如果将版本添加到非版本控制 API， Original 版本将自动创建，并在默认 URL 上响应，但未指定版本标识符。 该 Original 版本可确保任何现有调用方不受添加版本的过程的影响。 如果您在创建新 API 时启用版本，则不会创建 Original 版本。

如何表示版本

API 管理维护名为 版本集的资源，该资源表示单个逻辑 API 的一组版本。 版本集包含版本控制 API 的显示名称和用于将请求定向到指定版本的 版本控制方案 。

API 的每个版本都作为自己的 API 资源进行维护，并与版本集相关联。 版本集可能包含具有不同作或策略的 API。 你可能在一个系列的版本之间做出重大更改。

Azure 门户会为你创建版本集。 可以在 Azure 门户中修改版本集的名称和说明。

删除最终版本时，会自动删除版本集。

可以使用 Azure CLI、 Azure PowerShell、 资源管理器模板或 Azure 资源管理器 API 直接查看和管理版本集。

将无版本 API 迁移到有版本的 API

使用 Azure 门户在现有 API 上启用版本控制时，对 API 管理资源进行了以下更改：

• 将创建一个新版本集。
• 现有版本将保留并 配置为 Original API 版本。 API 链接到版本集，但不需要指定版本标识符。
• 新版本作为新 API 创建，并链接到版本集。 版本控制方案和标识符必须用于访问新 API。

版本和修订

版本和修订是不同的功能。 每个版本可以有多个修订，就像非版本控制 API 一样。 可以在不使用版本的情况下使用修订，也可以以其他方式使用修订。 通常，版本用于分隔具有重大更改的 API 版本，而修订可用于 API 的次要和非中断性变更。

如果你发现修订版有重大更改，或者想要将其正式转换为 beta /测试版本，则可以从修订版中创建一个版本。 在 Azure 门户中，选择“修订版”选项卡上的修订版上下文菜单 (...) 中的“从此修订版创建版本”。

开发人员门户

开发人员门户单独列出 API 的每个版本：

在 API 的详细信息中，还可以查看 API 的所有版本的列表。 一个Original版本在显示时没有版本标识符。