API のバージョニング

このページでは、API のバージョニングの方法と、複数バージョンへのデプロイ方法について説明します。

API のバージョン管理に関する推奨事項

API バージョンを管理する際には、次の推奨事項を念頭に置きます。

増分的かつ非破壊的な変更を行う場合、API バージョンの一貫性を失わないように既存の API にデプロイするようにします。
API に互換性に影響する変更を導入する場合には API バージョンを 1 つ上げます。
保護を強化するには、App Engine アプリケーションのバージョンも 1 つ上げて、その新しい App Engine アプリケーションバージョンに新しい API をデプロイします。これにより App Engine に備わった柔軟性を利用し、予測外の問題が発生した場合に App Engine バージョンを速やかに切り替えて、正常に動作していた古いバージョンからサービスを提供できます。

次の表に、App Engine アプリケーションバージョンとバックエンド API バージョンの対応関係を段階的に示しています。

アプリケーションのバージョン	バックエンド 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 コードをプロジェクトから削除しなければ、プロジェクトをデプロイしたときに、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 のバージョン番号と同じものではありません。

apiversions

上の図に示されているように、同一の 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 コンソールで明示的に変更しない限り変わりません。

提供バージョン以外のアプリケーションバージョンにデプロイされた API バージョンへのアクセス

現在の App Engine の提供バージョンにデプロイされているのではない API バージョンにアクセスする必要がある場合は、次に示すようなバージョン固有の URL を使用します。

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

VERSION を App Engine バージョンに、YOUR_PROJECT_ID を Google Cloud プロジェクト 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/...