Azure API 管理中的版本Versions in Azure API Management

通过版本可向开发人员显示相关 API 组。Versions allow you to present groups of related APIs to your developers. 你可以使用版本安全地处理 API 中的重大更改。You can use versions to handle breaking changes in your API safely. 客户端可以选择在准备就绪时使用新的 API 版本,而现有客户端将继续使用较旧的版本。Clients can choose to use your new API version when they're ready, while existing clients continue to use an older version. 版本通过版本标识符(即你选择的任何字符串值)进行区分,而版本控制方案使客户端能够标识要使用的 API 版本。Versions are differentiated through a version identifier (which is any string value you choose), and a versioning scheme allows clients to identify which version of an API they want to use.

在大多数情况下,可以将每个 API 版本视为其自身的独立 API。For most purposes, each API version can be considered its own independent API. 两个不同的 API 版本可能具有不同的操作集和不同的策略。Two different API versions might have different sets of operations and different policies.

使用版本可执行以下操作:With versions you can:

  • 同时发布 API 的多个版本。Publish multiple versions of your API at the same time.
  • 使用路径、查询字符串或标头来区分版本。Use a path, query string, or header to differentiate between versions.
  • 使用想用来标识版本的任何字符串值,可以是数字、日期或名称。Use any string value you wish to identify your version, which could be a number, a date, or a name.
  • 在开发人员门户上显示组合在一起的 API 版本。Show your API versions grouped together on the developer portal.
  • 采用现有(非版本控制)API,并在不中断现有客户端的情况下创建新版本。Take an existing (non-versioned) API, and create a new version of it without breaking existing clients.

按照我们的演练开始使用版本。Get started with versions by following our walkthrough.

版本控制方案Versioning schemes

不同 API 开发人员对版本控制的要求不同。Different API developers have different requirements for versioning. Azure API 管理不指定特定版本控制方法,而是提供多个选项。Azure API Management doesn't prescribe a single approach to versioning, but instead provides several options.

基于路径的版本控制Path-based versioning

使用路径版本控制方案时,任何 API 请求的 URL 路径中都需要包含版本标识符。When the path versioning scheme is used, the version identifier needs to be included in the URL path for any API requests.

例如,https://apis.contoso.com/products/v1https://apis.contoso.com/products/v2 可以引用相同的 products API,但需要分别引用版本 v1v2For example, https://apis.contoso.com/products/v1 and https://apis.contoso.com/products/v2 could refer to the same products API but to versions v1 and v2 respectively.

使用基于标头的版本控制时,API 请求 URL 的格式为:https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}The format of an API request URL when using header-based versioning is: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

基于标头的版本控制Header-based versioning

使用标头版本控制方案时,任何 API 请求的 HTTP 请求标头中都需要包含版本标识符。When the header versioning scheme is used, the version identifier needs to be included in an HTTP request header for any API requests. 可以指定 HTTP 请求头的名称。You can specify the name of the HTTP request header.

例如,可以创建一个名为 Api-Version 的自定义标头,客户端可以在此标头的值中指定 v1v2For example, you might create a custom header named Api-Version, and clients could specify v1 or v2 in the value of this header.

基于查询字符串的版本控制Query string-based versioning

使用查询字符串版本控制方案时,任何 API 请求的查询字符串参数中都需要包含版本标识符。When the query string versioning scheme is used, the version identifier needs to be included in a query string parameter for any API requests. 可以指定查询字符串参数的名称。You can specify the name of the query string parameter.

使用基于查询字符串的版本控制时,API 请求 URL 的格式为:https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}The format of an API request URL when using query string-based versioning is: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

例如,https://apis.contoso.com/products?api-version=v1https://apis.contoso.com/products/api-version=v2 可以引用相同的 products API,但需要分别引用版本 v1v2For example, https://apis.contoso.com/products?api-version=v1 and https://apis.contoso.com/products/api-version=v2 could refer to the same products API but to versions v1 and v2 respectively.

原始版本Original versions

如果为非版本控制 API 添加了版本,则会自动创建 Original 版本并在不指定版本标识符的情况下对默认 URL 进行响应。If you add a version to a non-versioned API, an Original version will be automatically created and will respond on the default URL, without a version identifier specified. Original 版本可以确保所有现有调用方不会被添加版本的过程中断。The Original version ensures that any existing callers are not broken by the process of adding a version. 如果在一开始就启用了版本的情况下创建新 API,则不会创建 Original 版本。If you create a new API with versions enabled at the start, an Original version isn't created.

如何表示版本How versions are represented

Azure API 管理会维护名为“版本集”的资源,该资源代表单个逻辑 API 的一组版本。Azure API Management maintains a resource called a version set, which represents a set of versions for a single logical API. 使用 Azure 门户管理版本时,你看不到版本集,但如果使用 PowerShell、资源管理器模板或 Azure 资源管理器 API 与 API 管理服务交互,则可以直接查看和管理版本集。When you use the Azure portal to manage versions you don't see the version set, but if you interact with your API Management service using PowerShell, Resource Manager templates, or the Azure Resource Manager API, you can directly view and manage version sets. 版本集包含版本控制 API 的显示名称,以及用于将请求定向到指定版本的版本控制方案A version set contains the display name of the versioned API, as well as the versioning scheme used to direct requests to specified versions.

API 的每个版本都作为其自身的 API 资源进行维护,并将资源与版本集相关联。Each version of an API is maintained as its own API resource, which is then associated with a version set. 版本集可能包含具有不同操作或策略的 API,这反映出不同 API 版本之间可能存在很大的不同。A version set might contain APIs with very different operations or policies, which reflects the fact that you might make significant changes between versions of your API.

将非版本控制 API 迁移到版本控制 APIMigrating a non-versioned API to a versioned API

使用 Azure 门户对现有 API 启用版本控制时,将对 API 管理资源进行以下更改:When you use the Azure portal to enable versioning on an existing API, the following changes are made to your API Management resources:

  • 创建新版本集。A new version set is created.
  • 保留现有版本并配置为 Original API 版本The existing version is maintained and configured as the Original API version. 将该 API 链接到版本集,但不需要指定版本标识符。The API is linked to the version set but doesn't require a version identifier to be specified.
  • 新版本创建为新的 API,并链接到版本集。The new version is created as a new API, and is linked to the version set. 必须使用版本控制方案和标识符访问此新 API。This new API must be accessed using the versioning scheme and identifier.

版本和修订版Versions and revisions

版本和修订版功能不同。Versions and revisions are distinct features. 与非版本控制 API 一样,每个版本都可以有多个修订版。Each version can have multiple revisions, just like a non-versioned API. 你可以使用修订版而不使用版本,或反之亦然。You can use revisions without using versions, or the other way around. 通常,版本用于分离 API 版本和重大更改,而修订版可用于对 API 进行次要和非重大的更改。Typically versions are used to separate API versions with breaking changes, while revisions can be used for minor and non-breaking changes to an API.

如果你发现修订版有重大更改,或者想要将其正式转换为 beta /测试版本,则可以从修订版中创建一个版本。Should you find that your revision has breaking changes, or if you wish to formally turn your revision into a beta/test version, you can create a version from a revision. 使用 Azure 门户,单击“修订版”选项卡上的修订版上下文菜单中的“从修订版创建版本”。Using the Azure portal, click the 'Create Version from Revision' on the revision context menu on the Revisions tab.

开发人员门户Developer portal

开发人员门户分别列出了 API 的每个版本。The developer portal lists each version of an API separately.

显示版本控制 API 列表的 API 管理开发人员门户

API 的详细信息还会显示此 API 的所有版本的列表。The details of an API also show a list of all of the versions of that API. 会显示一个不带版本标识符的 Original 版本。An Original version is displayed without a version identifier.

显示 API 的详细信息和此 API 的版本列表的 API 管理开发人员门户

提示

需要将 API 版本添加到产品中,然后才能在开发人员门户上显示。API versions need to be added to a product before they will be visible on the developer portal.