このページでは、Cloud Endpoints API のバージョニング機能について説明し、Endpoints API のバージョニングとステージングのベスト プラクティスをご紹介します。このページの情報は、OpenAPI 仕様を使用する API に適用されます。App Engine スタンダード環境用の Cloud Endpoints Frameworks を使用する API については、API のバージョニング: Java または API のバージョニング: Python をご覧ください。
API のバージョニングとサービス ステージングについては、Google が使用しているのと同じ基本原則に従うことをおすすめします。
初期バージョンをデプロイする前に、OpenAPI 構成ファイルに以下を含めます。
info.versionフィールドでバージョン番号を設定します。メジャー バージョンとマイナー バージョンを含むバージョン文字列（1.0など）を使用することをおすすめします。- メジャー バージョン番号を含める
basePath（基本パス）フィールドを設定します。文字vの後にメジャー バージョン番号を付加した形式の基本パス（/v1など）を使用することをおすすめします。
新しいメソッドの追加など、下位互換性のある変更が必要な場合は、
info.versionフィールドでマイナー バージョン番号を増分して（たとえば 1.2、1.3）、再デプロイします。詳しくは、API のバージョニングをご覧ください。既存のメソッドに、クライアント コードとの互換性を破る変更を加える必要がある場合は、OpenAPI 構成ファイルのコピーを作成して、以下の変更を行います。
info.versionフィールドでメジャー バージョン番号を増分します（2.0、3.0 など）。basePathフィールドでメジャー バージョン番号を増分します（/v2、/v3 など）。
両方のバージョンの OpenAPI 構成ファイルをデプロイし、バックエンドを再デプロイします。これにより、バックエンドは両方のバージョンのメソッドを持つことになります。詳しくは、API のバージョニングをご覧ください。
API のすべてのメジャー バージョンを 1 つのバックエンドに実装します。この推奨事項には次の効果があります。
- 前述の例のように、特定のバージョンへのリクエストはパスに基づくので、ルーティングが簡素化されます。
- 構成とデプロイが簡素化されます。API のすべてのメジャー バージョンに対して同じ Google Cloud プロジェクトとバックエンドを使用し、API のすべてのバージョンを同時にデプロイします。
- 余分なバックエンドの実行を防ぎ、コストを低く抑えます。
本番環境の Google Cloud プロジェクトにデプロイする前に、別の Google Cloud プロジェクトで API をステージングします。詳しくは、サービスのステージングをご覧ください。
Endpoints のメジャー バージョン番号とマイナー バージョン番号の使用法は、セマンティック バージョニングの定義に対応しています。Endpoints では、バックエンド コードのバグ修正をデプロイする際に OpenAPI 構成ファイルでパッチ バージョン番号を増やして構成をデプロイすることは必須ではありません。ただし、必要に応じて増やすこともできます。
Cloud Endpoints API のバージョニング機能
Extensible Service Proxy（ESP）には、API の複数のメジャー バージョンのパスが重複していない限り、それらのバージョンを単一の Google Cloud プロジェクトとバックエンドで同時に管理するための機能が備わっています。例:
http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo
顧客ユーザーはこの機能を利用して、使用するバージョンを選択したり、新しいバージョンに移行するタイミングを管理したりすることができます。ESP では、バックエンドの該当するメソッドにリクエストをルーティングする前に、各リクエストにバージョン番号がタグ付けされます。各リクエストにバージョン番号がタグ付けされることによって、以下のことが可能になります。
[エンドポイント] > [サービス] のグラフとログに、API のメジャー バージョンごとのリクエスト数と全バージョンのリクエストの合計が表示されます。特定のバージョンで表示をフィルタリングできます。これにより、バージョンごとのトラフィック量を明確に把握できます。また、このログでは、どのクライアントがどのバージョンを使用しているかも確認できます。
マイナー バージョン番号を更新した API を再デプロイすると、それ以降、グラフとログに表示されるアクティビティには、新しいバージョン番号がラベル付けされます。これによって、デプロイのラベル付き履歴を確認できます。
特定のバージョンの API を削除すると、グラフとログには、その API がアクティブだった期間のデータが引き続き表示されます。
API のライフサイクルの例
このセクションでは、サービスの一般的なライフサイクルについて説明します。
バージョン 1
最初に、My Awesome Echo API サービスのバージョン 1 をデプロイします。この API は my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo から提供されます。[エンドポイント] > [サービス] のグラフとログでは、すべてのトラフィックが 1.0 と表示されます。
バージョン 1.1
ユーザーから新機能の要望を受け、新しいメソッドを追加します。OpenAPI 構成ファイルで、新しいメソッドを追加し、info.version フィールドの値を 1.1 に増やします。これはクライアント コードとの互換性を維持する変更なので、マイナー バージョン番号を増分します。ステージング環境に変更をデプロイしてテストし、動作を確認します。
次に、OpenAPI 構成と API バックエンドを本番環境にデプロイします。API は引き続き my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo から提供されますが、呼び出し元は新しいメソッドに対するリクエストを発行できるようになります。古いメソッドに対するインターフェースを変更していないので、顧客ユーザーはクライアントを変更して再デプロイする必要がありません。クライアントは以前と同様に、古いメソッドにリクエストを送信できます。
[エンドポイント] > [サービス] で処理されるトラフィックはバージョン 1.1 になります。以前の期間の表示を選択すると、グラフとログに旧バージョンが表示され、デプロイのラベル付き履歴を確認できます。
バージョン 2.0
既存のメソッドに、下位互換性のない変更を加えることが必要になりました。ユーザーのクライアント コードの動作に支障を及ぼさないことが重要なので、2 つのバージョンの API を維持することにしました。古いメソッドはそのまま残し、新しいバージョンのメソッドを実装します。バージョン 2.0 用に別の OpenAPI 構成ファイルを作成します。また、新しいバージョンは my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo から提供されるように構成します。元の OpenAPI 構成ファイルは引き続き古いバージョンのメソッドを指しますが、新しい OpenAPI 構成ファイルは新しいバージョンのメソッドを指すようになります。
バージョン 1 とバージョン 2 の両方の OpenAPI 構成ファイルを同時にデプロイし、バックエンドを再デプロイします。すると、バックエンドには両方のバージョンのメソッドが含まれることになります 詳しくは、API のバージョニングをご覧ください。
デプロイ後は、2 つのバージョンの API を提供していることが [エンドポイント] > [サービス] に示され、各バージョンのトラフィック量を確認できます。v1 クライアントは引き続き /v1 を呼び出せますが、/v2 を呼び出して新しいバージョンのメソッドを使うこともできます。バックエンド コードでバージョニングをどのように扱うかは、ご使用の API フレームワークによって異なります。サーブレットを使用する例については、複数バージョンを使用する Endpoints ＆ Java のサンプルをご覧ください。
バージョン 1 の無効化
クライアントの移行が進み、v1 へのトラフィックが一切なくなったら、v1 の提供を終了することができます。API のバージョン 1 を削除するには、バージョン 2 の OpenAPI 構成ファイルのみをデプロイし、バックエンドを再デプロイします。こうすると、バージョン 1 を実装したコードをバックエンドから安全に削除できるようになります。 [エンドポイント] > [サービス] には、バージョン 1.x からの履歴データが維持されます。
サービスのステージング
顧客ユーザーに提供する前にサービスをテストする目的で、Endpoints サービスの更新をステージングすることをベスト プラクティスとしておすすめします。また、サービスのステージング用に別個の Google Cloud プロジェクトを作成して、本番環境から隔離することもおすすめします。たとえば、通常、Google の割り当ては 1 つのプロジェクト内のリソース間で共有されます。そのため、本番環境のサービスと同じプロジェクトにステージング サービスを含めると、ループエラーなどがあった場合に本番環境のサービスが停止する可能性があります。
ステージング用の Google Cloud プロジェクトには、その用途を明確に示す名前を付けることをおすすめします。一般的な命名方法として、本番環境用 Google Cloud プロジェクトと同じ名前にして末尾に -staging を付けることができます。さらに、本番環境用プロジェクト名の末尾に -prod を付けると、本番環境サービス用であることが見分けやすくなります。
Google Cloud のサービス名は一意である必要があります。サービス名は OpenAPI 構成ファイルで指定するので、ステージング用プロジェクトと本番環境用プロジェクトで別々の API 構成ファイルを使用するか、API 構成ファイルのセットを 1 つ用意し、デプロイ先プロジェクトの名前に一致するようにサービス名を変更する処理を考え出す必要があります。