本页介绍如何对您的 API 进行版本控制以及如何部署到多个版本。
关于管理 API 版本的建议
在管理 API 版本时,请考虑以下建议:
- 如果要引入增量式非重大更改,请保持 API 版本不变,并在现有 API 上进行部署。
- 如果要对 API 引入重大更改,请递增 API 版本。
- 如果要获得额外保护,也请递增 App Engine 应用版本,然后将新 API 版本部署到新的 App Engine 应用版本。这样,您就可以利用 App Engine 内置的灵活性在各 App Engine 版本之间快速切换,并在遇到意外问题时通过旧工作版本提供服务。
下表展示如何将后端 API 版本级联到不同的 App Engine 应用版本:
应用版本 | 后端 API 版本 |
---|---|
1 |
|
2 |
|
3 |
|
如上表中所示,对 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
属性中指定的。
如上图所示,您可以将多个 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 控制台中明确更改了服务版本,否则此版本保持不变。
访问部署到非服务应用版本的 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 文档。