このページでは、既存の Cloud Endpoints バージョン 1.0 アプリケーションを、Java の App Engine 用 Endpoints Frameworks に移行する方法について説明します。
利点
新しいフレームワークには数多くの利点があります。
- リクエスト レイテンシの短縮
- App Engine の機能(カスタム ドメインなど)との統合強化
- Guice 構成の正式サポート
- 新しい API 管理機能(オプション)
Endpoints Frameworks バージョン 2.0 に移行しても、API のインターフェースには影響しません。既存のクライアントは、クライアント側コードを変更しなくても、移行後も引き続き動作します。
現時点で利用できない機能とツール
現在、以下の機能はご利用いただけません。これらのいずれかが必要な場合は、機能のリクエストを送信してください。
- JSON-RPC プロトコル。レガシー iOS クライアントで必要になります。Endpoints Frameworks バージョン 2.0 API 用の iOS クライアントを作成する際には、REST API 用の Google API Objective-C クライアント ライブラリを使用することをおすすめします。
- 自動 ETag
- 自動 kind フィールド
- IDE との統合
fields
部分応答- PATCH API メソッドの自動作成
また、Endpoints バージョン 1.0 用の Android Studio サポートは、現在のところバージョン 2.0 には対応していません。
Endpoints Frameworks バージョン 2.0 への移行
Endpoints Frameworks バージョン 2.0 は、グループ com.google.endpoints
の Maven アーティファクトに移動しました。必要な基本 JAR は endpoints-framework
アーティファクトに含まれています。Guice 構成を使用するには、endpoints-framework-guice
アーティファクトを追加してください。
以下の手順は、ディスカバリ ドキュメントを使用して Endpoints Frameworks バージョン 1.0 から Endpoints Frameworks バージョン 2.0 に移行する方法の一例です。
- Google Cloud CLI をダウンロードして初期化します。
- 次のコマンドを実行します。
- gcloud CLI が、Google Cloud にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。
gcloud auth login
- 次のアプリケーションのデフォルト認証情報を使用します。
gcloud auth application-default login
- Google Cloud SDK
app-engine-java
のコンポーネントをインストールします。gcloud components install app-engine-java
- Google Cloud SDK とすべてのコンポーネントを最新バージョンに更新します。
gcloud components update
- gcloud CLI が、Google Cloud にある対象のデータとサービスにアクセスできるよう許可されていることを確認します。
Maven または Gradle を使用した移行
Maven
- 従来の依存関係(
appengine-endpoints
アーティファクト)を削除します。 - 新しい Endpoints Frameworks 依存関係を追加します。
- 新しい Endpoints Frameworks プラグインを追加し、生成するディスカバリ ドキュメントのホスト名を定義します。
- 新しい App Engine Maven プラグインを追加します。
- プロジェクトの
web.xml
ファイルで API のエントリ ポイントを更新します。SystemServiceServlet
をすべてEndpointsServlet
に変更します。- パス
/_ah/spi/
をすべて新しい必須パス/_ah/api/
に置き換えます。
移行前後の
web.xml
の内容を次に示します。移行前
Endpoints Frameworks バージョン 1.0web.xml
:移行後
Endpoints Frameworks バージョン 2.0web.xml
: - 依存関係を変更した後、プロジェクトをクリーンアップします。
mvn clean
- ディスカバリ ドキュメントを生成します。
mvn endpoints-framework:discoveryDocs
Maven Endpoints Frameworks プラグインのゴールについては、こちらをご覧ください。 - プロジェクトをデプロイします。
mvn appengine:deploy
Maven App Engine プラグインの目標については、プラグインのゴールをご覧ください。
Gradle
- 従来の依存関係(
appengine-endpoints
アーティファクト)を削除します。compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
- 新しい Endpoints Frameworks 依存関係を追加します。
- 新しい App Engine プラグインと新しい Endpoints Frameworks プラグインを追加します。
- 新しい App Engine プラグインと新しい Endpoints Frameworks プラグインを適用します。
- 生成するディスカバリ ドキュメントのホスト名エンドポイントを定義します。
- プロジェクトの
web.xml
ファイルで API のエントリ ポイントを更新します。SystemServiceServlet
をすべてEndpointsServlet
に変更します。- パス
/_ah/spi/
をすべて新しい必須パス/_ah/api/
に置き換えます。
移行前後の
web.xml
の内容を次に示します。移行前
Endpoints Frameworks バージョン 1.0web.xml
:移行後
Endpoints Frameworks バージョン 2.0web.xml
: - 依存関係を変更した後、次のコマンドでプロジェクトをクリーンアップします。
gradle clean
- ディスカバリ ドキュメントを生成するには、次のコマンドを使用します。
gradle endpointsDiscoveryDocs
Gradle Endpoints Frameworks プラグインのタスクについては、こちらをご覧ください。 - プロジェクトをデプロイするには、次のコマンドを使用します。
gradle appengineDeploy
Gradle App Engine プラグインのタスクについては、プラグインのタスクをご覧ください。
Guice を使用した Java 用 Endpoints Frameworks の構成
Guice を使用する場合:
- 新しい Endpoints Frameworks Guice 依存関係を追加します。
Maven
Gradle
EndpointsModule
を拡張する新しいモジュールを宣言し、次のように構成します。
新しいデプロイの確認
新しいフレームワークでトラフィックが処理されていることを確認できます。
- 新しいデプロイにリクエストをいくつか送信します。
Google Cloud コンソールで、[Logging] > [ログ エクスプローラ] ページに移動します。
パスが
/_ah/api
で始まるリクエストがログに含まれている場合は、Endpoints Frameworks バージョン 2.0 が API を処理していることを示しています。パスが/_ah/spi
で始まるリクエストがログに含まれていてはいけません。そのようなリクエストが含まれている場合は、Endpoints Frameworks バージョン 1.0 プロキシがリクエストを処理していることを示しています。
Endpoints API 管理の追加
Endpoints Frameworks バージョン 2.0 では、次のような API 管理機能を有効にすることもできます。
- API キー管理
- API 共有
- ユーザー認証
- API 指標
- API ログ
これらの機能の使用にあたっては、API 管理の追加をご覧ください。
トラブルシューティング
このセクションでは、Endpoints Frameworks バージョン 2.0 への移行で発生する一般的なエラーと推奨される解決方法について説明します。
API から 404
エラーが返されるが、API Explorer では API が正しくリストされる
Endpoints Frameworks バージョン 2.0 に移行するときには、古い Endpoints Frameworks バージョン 1.0 の構成を削除する必要があります。古い構成がアプリケーション構成に残っていると、Endpoints サービスはアプリを引き続きバージョン 1.0 アプリとして扱います。/_ah/spi
に送信されたリクエストが App Engine ログに記録されている場合、これはクライアントに HTTP 404
エラーが返されたことを示します。
このようなエラーが発生した場合は、
web.xml
ファイルから次の行を削除します。<servlet> <servlet-name>SystemServiceServlet</servlet-name> <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class> <init-param> <param-name>services</param-name> <param-value>...</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>SystemServiceServlet</servlet-name> <url-pattern>/_ah/spi/*</url-pattern> </servlet-mapping>
web.xml
ファイルに次の記述が含まれていることを確認します。<servlet-mapping> <servlet-name>EndpointsServlet</servlet-name> <url-pattern>/_ah/api/*</url-pattern> </servlet-mapping>
API からのリフレクション エラー
endpoints-framework
アーティファクトのみをアプリケーションにパッケージ化する必要があります。古い appengine-endpoints
JAR は使用しません。両方の JAR が含まれるアプリケーションをデプロイすると、NoClassDefFoundError
、NoSuchMethodError
、ClassCastException
などのリフレクション エラーまたはランタイム エラーが発生する場合があります。このようなエラーが発生した場合は、ビルドファイルから次の行を削除します。
Maven
Gradle
compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
また、Guava の古いバージョンと依存関係がある場合は、欠落している TypeToken
メソッドとして現れることもあります。この場合、Guava v19 を使用するか、依存関係をシャドウする endpoints-framework-all
アーティファクトを使用します。
クライアント ライブラリ ソースがコンパイルされない
method does not override or implement a method
from a supertype
や cannot find symbol method setBatchPath(String)
などのエラーが発生する場合は、クライアント アプリケーションが古いバージョンの Google Java クライアント ライブラリに依存している可能性があります。google-api-client
アーティファクトを 1.23.0
以降にする必要があります。
Maven
<dependency> <groupId>com.google.api-client</groupId> <artifactId>google-api-client</artifactId> <version>1.23.0</version> </dependency>
Gradle
compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'
JPA/JDO Datanucleus エンハンスメントに関する問題
Maven
新しい Google Cloud CLI ベースの App Engine Maven プラグインは、どのようなタイプの Datanucleus エンハンスメントもサポートしていません。プロジェクトで古いプラグインによる Datanucleus JDO または JPA のエンハンスメント サポートを使用している場合は、移行する際に、サードパーティの Datanucleus Maven プラグインを個別に構成する必要があります。詳しくは以下をご覧ください。
Gradle
プロジェクトで gradle-appengine-plugin
の JPA / JDO Datanucleus エンハンスメントを使用している場合は、gcloud CLI ベースの Gradle プラグインへの切り替え後に、Datanucleus エンハンスメントを手動で構成する必要があります。Stack Overflow の例をご覧ください。