このページでは、API のバージョニングの方法と、複数バージョンへのデプロイ方法について説明します。
API のバージョン管理に関する推奨事項
API バージョンを管理する際には、次の推奨事項を念頭に置きます。
- 増分的かつ非破壊的な変更を行う場合、API バージョンの一貫性を失わないように既存の API にデプロイするようにします。
- API に互換性に影響する変更を導入する場合には API バージョンを 1 つ上げます。
- 保護を強化するには、App Engine アプリケーションのバージョンも 1 つ上げて、その新しい App Engine アプリケーション バージョンに新しい API をデプロイします。これにより App Engine に備わった柔軟性を利用し、予測外の問題が発生した場合に App Engine バージョンを速やかに切り替えて、正常に動作していた古いバージョンからサービスを提供できます。
次の表に、App Engine アプリケーション バージョンとバックエンド API バージョンの対応関係を段階的に示しています。
アプリケーションのバージョン | バックエンド API のバージョン |
---|---|
1 |
|
2 |
|
3 |
|
この表に示されているように、API の v1 に対する増分的で互換性を損なわない更新では、それぞれが直前のバージョンを上書きします。互換性に影響する変更が導入されると、API のバージョンは v2 に更新され、新しいバージョンの App Engine アプリケーションにデプロイされます。これにより、必要に応じて前のアプリケーション バージョンに戻すことができます。
この表から、バージョン 2 のアプリケーションが API の最新の v1 バージョンと新しい v2 バージョンの両方をサポートすることがわかります。このため、既存の v1 コードをプロジェクトから削除しなければ、プロジェクトをデプロイしたときに、v2
と vl
(n) 両方の API がバージョン 2 のアプリケーションにデプロイされます。
複数のアプリケーション バージョンへのデプロイ
バックエンド API をデプロイするときには、その API 用に作成した Google Cloud プロジェクトのプロジェクト ID にそれをデプロイします。また、デプロイ先の App Engine バージョンを指定する必要もあります。/WEB-INF/appengine-web.xml
ファイルの <version>
要素に App Engine アプリのバージョンを指定します。App Engine アプリのバージョンは、@Api
アノテーションの version
属性で指定するバックエンド API のバージョン番号と同じものではありません。
上の図に示されているように、同一の App Engine バージョンに対して複数のバージョンの API をデプロイできます。さらに、1 つのアプリケーションに複数のバージョンの App Engine を使用することもできます。
提供バージョンにデプロイされている API バージョンへのアクセス
API を最初にデプロイした App Engine バージョンが提供バージョンとなります。このバージョンは、URL http://YOUR_PROJECT_ID.appspot.com
で実行されます。ここで、YOUR_PROJECT_ID
は Google Cloud プロジェクト ID を表します。この URL を使用することで、この App Engine アプリケーションのバージョンにデプロイされているすべての API バージョンにアクセスできます。
提供バージョンは、Google Cloud Console で明示的に変更しない限り変わりません。
提供バージョン以外のアプリケーション バージョンにデプロイされた API バージョンへのアクセス
現在の App Engine の提供バージョンにデプロイされているのではない API バージョンにアクセスする必要がある場合は、次に示すようなバージョン固有の URL を使用します。
https://VERSION-dot-YOUR_PROJECT_ID.appspot.com
VERSION
を App Engine バージョンに、YOUR_PROJECT_ID
をプロジェクト ID に置き換えます。たとえば、App Engine の提供バージョンが 1 であるものの、バージョン 2 にデプロイされている API バージョンにアクセスしたいとします。その場合に使用する URL は https://2-dot-YOUR_PROJECT_ID.appspot.com
になります。
詳細については、App Engine のドキュメントをご覧ください。
非提供サービス(以前のモジュール)にデプロイされた API バージョンへのアクセス
デフォルトの App Engine サービスにデプロイされているのではない API バージョンにアクセスする必要がある場合は、次のようにドット構文を使用したサービス固有の URL を使用します。
https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...
詳細については、App Engine のドキュメントをご覧ください。