处理 API 版本控制

本页介绍如何对您的 API 进行版本控制以及如何部署到多个版本。

关于管理 API 版本的建议

在管理 API 版本时，请考虑以下建议：

  • 如果要引入增量式非重大更改，请保持 API 版本不变，并在现有 API 上进行部署。
  • 如果要对 API 引入重大更改，请递增 API 版本。
  • 如果要获得额外保护，也请递增 App Engine 应用版本，然后将新 API 版本部署到新的 App Engine 应用版本。这样，您就可以利用 App Engine 内置的灵活性在各 App Engine 版本之间快速切换，并在遇到意外问题时通过旧工作版本提供服务。

下表展示如何将后端 API 版本级联到不同的 App Engine 应用版本：

应用版本 后端 API 版本
1
  • v1 --> v1 (2) --> v1 (n)
2
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

如上表中所示，对 API v1 引入了增量式非重大更新，并且每次更新都会覆盖之前的版本。引入重大更改时，API 版本递增至 v2，并部署到新的 App Engine 应用版本。这样，您便可以在需要时切换回以前的应用版本。

在上表中，请注意应用版本 2 支持您 API 的最新 v1 版本和新的 v2 版本。如果您没有从项目中删除现有的 v1 代码，则部署项目时，API 的 v2 和 vl (n) 都将部署到应用的版本 2。

部署到多个应用版本

部署后端 API 时，您必须将其部署到您为 API 创建的Google Cloud 项目的 ID，同时还必须指定要部署到的 App Engine 版本。 您可以在 /WEB-INF/appengine-web.xml 文件的 <version> 元素中指定 App Engine 应用版本。App Engine 应用版本与后端 API 版本号不同，后者是在 @Api 注释的 version 属性中指定的。

apiversions

如上图所示，您可以将多个 API 版本部署到同一个 App Engine 版本，并且您可以为一个应用提供多个 App Engine 版本。

访问部署到服务版本的 API 版本

将 API 部署到的第一个 App Engine 版本即为服务版本。此版本的运行网址为 http://YOUR_PROJECT_ID.appspot.com，其中 YOUR_PROJECT_ID 代表您的 Google Cloud项目 ID。您可以通过该网址访问部署到该 App Engine 应用版本的所有 API 版本。

除非您在 Google Cloud Console 中明确更改了服务版本，否则此版本保持不变。

访问部署到非服务应用版本的 API 版本

如果您需要访问的 API 版本未部署到当前提供服务的 App Engine 版本，请使用特定于版本的网址，如下所示：

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

请将 VERSION 替换为您的 App Engine 版本，并将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如，假设您的 App Engine 服务版本为 1，但您想要访问部署到版本 2 的 API 版本，可以使用以下网址：https://2-dot-YOUR_PROJECT_ID.appspot.com。

如需了解详情，请参阅 App Engine 文档。

访问部署到非使用中服务（之前称作模块）的 API 版本

如果您需要访问的 API 版本未部署到默认 App Engine 服务，则您可以使用采用 dot 语法的特定于服务的网址，如下所示：

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

如需了解详情，请参阅 App Engine 文档。