Apache Maven と App Engine プラグインの使用（App Engine SDK ベース）

このページでは、ソフトウェア プロジェクトの管理および確認ツール Apache Maven を使用して App Engine プロジェクトを管理する方法を説明します。このツールを使って App Engine へのデプロイ用 WAR ファイルをビルドできます。Google は、プラグインと、Maven 3.5 に含まれている Maven アーキタイプを提供しています。

Maven を使用する場合、App Engine SDK から Java ライブラリを手動でダウンロードする必要はありません。Maven は、必要に応じて適切なライブラリを自動的にダウンロードします。Maven を使用して、アプリをローカルでテストしてから、本番環境の App Engine にデプロイすることもできます。

Maven を設定する

Java を構成する

  1. Java がない場合は、Java をダウンロードし、インストールして構成します。
  2. pom.xml でコンパイラ フラグを設定して、Java 8 バイトコードを指定します。
    appengine-standard-java8/helloworld-gae-javasdk-tools/pom.xml 
    <properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Maven 3.5 のインストール

Maven がインストールされているかどうか、どのバージョンがインストールされているかを確認するには、次のコマンドを実行します。

 mvn -v

適切なバージョンの Maven がインストールされていない場合は、次の手順に沿ってインストールします。

  1. Maven ウェブサイトから Maven 3.5 をダウンロードします。
  2. ローカルマシンに Maven 3.5 をインストールします。

Cloud プロジェクトの設定と検証

Cloud プロジェクトをセットアップして、App Engine SDK をインストールする必要があります。

  1. Google Cloud Console を使用して、Cloud プロジェクトを作成して設定します。

    App Engine に移動

    1. 新しい Cloud プロジェクトを選択または作成します。
    2. プロジェクト用の App Engine アプリケーションを作成する必要がある場合は、App Engine アプリケーションを配置するリージョンを選択するように指示されます。
    3. プロジェクトで App Engine アプリケーションが作成されると、ダッシュボードが開きます。

  2. App Engine SDK for Java をインストールして、ディレクトリを PATH に追加します。

Maven を使用する

App Engine プラグインを既存のプロジェクトに追加する（省略可）

既存の Maven プロジェクトに Google App Engine Maven プラグインを追加するには、プロジェクト pom.xml ファイルの plugins セクションに次の内容を追加します。

<plugin>
   <groupId>com.google.appengine</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.9.88</version>
</plugin>

アーキタイプを選択する

Maven アーキタイプを使用すると、一般的な使用事例を想定したテンプレートを使って Maven プロジェクトを作成できます。App Engine では、この Maven の機能を活用するために、便利な App Engine アーキタイプをいくつか Maven Central で提供しています。アプリに適した App Engine アーキタイプを選択してください。

アプリケーションの種類 アーティファクト 説明
App Engine アプリ guestbook-archetype 実行とテストが可能な完成したゲストブックのデモサンプルを生成します。
App Engine アプリ appengine-skeleton-archetype 独自のクラスとリソースを利用できる、必要なファイルとディレクトリが含まれた新しい空の App Engine プロジェクトを生成します。

新しいプロジェクトの作成

Maven でプロジェクトを作成する際、プロジェクトの groupId、artifactId、version、package を指定するよう求められます。

用語 意味
groupId アーティファクトの追跡に使用される、Maven 内での名前空間。プロジェクトが他のユーザーの Maven プロジェクトに使用される場合、依存性を指定する際に属性として使用されます。
artifactId Maven 内でのプロジェクト名。他のユーザーが自分の Maven プロジェクトでこのプロジェクトに依存する場合も、このプロジェクト名が指定されます。
version プロジェクトの生成に使用する Maven の初期バージョン。versionに接尾辞-SNAPSHOTを付けることをおすすめします。これにより、開発中のバージョンの Maven リリース プラグインでサポートされるようになります。詳しくは、Maven Release Plugin の使用方法に関するガイドをご覧ください。
package 生成時に作成される Java パッケージ。

次の手順では、App Engine Maven アーキタイプを使用して App Engine アプリを作成する方法について説明します。

App Engine アプリを作成するには:

  1. プロジェクトをビルドするディレクトリに移動します。

  2. 次の Maven コマンドを実行します。

     mvn archetype:generate -Dappengine-version=1.9.88 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:

    -Dappengine-version を App Engine SDK for Java の最新バージョンに設定し、application-id を Cloud プロジェクトの ID に設定します。

    Java 8 ランタイムにプロジェクトをデプロイするように -Djava8=true を設定します。

    App Engine SDK for Java ツールを使用するように、-DCloudSDK_Tooling=falseを設定します。

  3. アーキタイプの選択を求められたら、App Engine スケルトン アーキタイプの値 2 を選択します。これにより、必要なディレクトリ構造とファイルが含まれている空のプロジェクトが作成されます。

  4. バージョンの入力を求められたら、Enter キーを押して、デフォルトである最新バージョンを選択します。

  5. 「Define value for property 'groupId'」と表示されたら、アプリの名前空間を指定します（com.mycompany.myapp など）。

  6. 「Define value for property 'artifactId'」と表示されたら、プロジェクト名を指定します（myapp など）。

  7. 「Define value for property 'version'」と表示されたら、デフォルト値を受け入れます。

  8. 「Define value for property 'package'」と表示されたら、希望するパッケージ名を指定します（またはデフォルト値を受け入れます）。生成される Java ファイルには、ここで指定するパッケージ名が付けられます。

  9. 選択した内容を確認するよう促されたら、デフォルト値（Y）を受け入れます。

  10. プロジェクトに必要なディレクトリとファイルの作成が完了するのを待ちます。 次に、myapp/ などの新しいプロジェクト ディレクトリに移動します。

    プロジェクトのビルドが正常に終了すると、次のようなメッセージが表示されます。

    [INFO] --------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] --------------------------------------------------
[INFO] Total time: 1:16.656s
[INFO] Finished at: 2017-06-04T16:18:24-07:00
[INFO] Final Memory: 16M/228M
[INFO] --------------------------------------------------

  11. アプリ用のクラスのコードを作成する前に、基本的なプロジェクトのレイアウトと必要なプロジェクト ファイルを確認します。プロジェクトを作成したディレクトリに、myapp というサブディレクトリがあります。これには、pom.xml ファイル、src/main/java サブディレクトリ、およびsrc/main/webapp/WEB-INF サブディレクトリが含まれています。

    Maven プロジェクトのレイアウト

    • 独自のアプリケーション Java クラスを src/main/java/... に追加します。
    • ファイルsrc/main/webapp/WEB-INF/appengine-web.xmlを使用してアプリケーションを設定します
    • ファイルsrc/main/webapp/WEB-INF/web.xmlを使用してアプリケーションデプロイを構成します

  12. アプリケーションの Java クラスを作成して src/main/java/... に追加します。詳細については、App Engine でのアプリのビルドをご覧ください。

  13. アプリのユーザーに提供する UI を追加します。詳細については、フォームデータの処理をご覧ください。

  14. プロジェクトの作成に使用したアーティファクトでは src/main/webapp/WEB-INF/appengine-web.xml の基本的な構成が完了しています。ただし、詳細設定を行うには、このファイルの編集が必要になることがあります。詳しくは、appengine-web.xml を使用して構成するをご覧ください。

  15. ファイル src/main/webapp/WEB-INF/web.xml を編集して、URL をアプリハンドラにマッピングし、認証やフィルタなどを指定します。詳しくはデプロイ記述子をご覧ください。

Maven プロジェクトを管理する

プロジェクトをコンパイルしてビルドする

Maven App Engine アーキタイプを使用して作成したアプリをビルドするには:

  1. ディレクトリをプロジェクトのメインディレクトリに変更します（例：guestbook/）。

  2. Maven を起動します。

    mvn clean package

  3. プロジェクトがビルドされるまで待ちます。プロジェクトのビルドが正常に終了すると、次のようなメッセージが表示されます。

    BUILD SUCCESS
 Total time: 10.724s
 Finished at: Thur Jul 04 14:50:06 PST 2017
 Final Memory: 24M/213M

  4. 必要に応じて、以下の手順でアプリケーションのテストを実行します。

開発サーバーでアプリをテストする

開発フェーズでは、App Engine Maven プラグインを起動して開発サーバーでいつでもアプリを実行してテストできます。手順は、プロジェクトの作成に使用されたアーティファクトによって多少異なります。

アプリをテストするには:

  1. アプリ（mvn clean package）をまだビルドしていない場合はビルドします。

  2. ディレクトリをプロジェクトの最上位（myapp など）に変更し、Maven を起動します。

    mvn appengine:devserver

    サーバーが起動するまで待ちます。サーバーが起動してアプリが実行されると、それを知らせるメッセージが表示されます。

    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
INFO: The server is running at http://localhost:8080/
Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
INFO: The admin console is running at http://localhost:8080/_ah/admin

  3. ブラウザで http://localhost:8080/ にアクセスしてアプリを表示します。

  4. アプリと開発サーバーをシャットダウンします。シャットダウンするには、Windows と Linux の場合は起動元のターミナル ウィンドウで Ctrl+C キー、Mac の場合は command+C キーを押します。

ローカルテスト用のポートを指定する

ローカルの開発サーバーでアプリを実行する場合、デフォルトのポートは 8080 です。このデフォルト値を変更するには、appengine-maven-plugin のプラグイン エントリを変更します（存在しない場合は追加します）。たとえば、メインアプリ ディレクトリ pom.xml ファイル（myapp/pom.xml）内にある <plugins> 内の <plugin> エントリでポートとアドレスを次のように指定します。

 <plugin>
     <groupId>com.google.appengine</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>1.9.88</version>
     <configuration>
         <enableJarClasses>false</enableJarClasses>
         <port>8181</port>
         <address>0.0.0.0</address>
     </configuration>
 </plugin>

なお、上記のように <port> でここでのポートを 8181 に設定します。アドレス 0.0.0.0 が指定されます。つまり、開発用サーバーはローカル ネットワークからのリクエストをリッスンします。

アプリのデプロイ

アプリをデプロイするをご覧ください。

リファレンス: 利用可能なゴール

App Engine Maven プラグインをプロジェクトの pom.xml ファイルに追加すると、App Engine 固有のいくつかの Maven ゴールを使用できるようになります。すべての利用可能なゴールを参照するには、次のコマンドを実行します。

 mvn help:describe -Dplugin=appengine

App Engine Maven プラグインのゴールは、開発サーバーゴール、アプリとプロジェクトの管理ゴール、Endpoints ゴールに分類できます。

開発サーバーゴール

開発サーバーゴールは次のとおりです。

appengine:devserver

App Engine 開発用サーバーを実行します。サーバーの稼働中は、appengine-web.xml が変更されていないかどうか継続的に確認します。変更されている場合、サーバーはアプリケーションをホットリロードします。つまり、appengine-web.xml が変更されてもアプリケーションを停止して再起動する必要はありません。次のパラメータを利用できます。

  • <fullScanSeconds>
  • <address>
  • <disableUpdateCheck>
  • <jvmFlags>
  • <port>
  • <server>

たとえば、起動時に停止せずに、デバッグモードを指定してポート 8000 でサーバーを実行する場合、次のフラグを使用できます。

<jvmFlags>
  <jvmFlag>-Xdebug</jvmFlag>
  <jvmFlag>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n</jvmFlag>
</jvmFlags>

デフォルトでは、<fullScanSeconds> フラグは 5 秒に設定されます。つまり、サーバーはウェブ アプリケーション ファイルの変更を 5 秒ごとに確認し、自動的に再読み込みします。これは、NetBeans のような保存時のコンパイル機能をサポートする IDE で便利です。この機能を使用するには、次のように <build> セクションを構成する必要があります。

<build>
   <outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
   <plugins>
      ....
   </plugins>
</build>
appengine:devserver_start

開発サーバーを非同期で起動して、コマンドラインに戻ります。このゴールが実行された場合の動作は devserver ゴールとほぼ同じですが、Maven がゴールの処理を続けて、サーバーが稼働中になると終了する点が異なります。

appengine:devserver_stop

開発サーバーを停止します。appengine:devserver_start で開発サーバーを起動した場合にのみ、使用できます。

アプリケーション管理ゴール

アプリケーションとプロジェクトの管理ゴールを次の表に示します。

目標 説明 対応する gcloud コマンド
appengine:backends_stop これにより、pom.xmlファイルで設定されているようにポートでリッスンしている実行中の開発サーバーが停止します。このゴールを、devserver_start コマンドと組み合わせて使用し、Maven プラグインとの統合テストを実行できます。
appengine:backends_configure 指定したバックエンドを構成します。
appengine:backends_delete 指定したバックエンドを削除します。
appengine:backends_rollback 前に処理した更新をロールバックします。
appengine:backends_start 指定したバックエンドを起動します。
appengine:backends_update 指定したバックエンドまたは（バックエンドを指定していない場合は）すべてのバックエンドを更新します。
appengine:enhance App Engine DataNucleus JDO Enhancer を実行します。
appengine:rollback 進行中の更新のロールバック gcloud app versions start、gcloud app versions stop
appengine:set_default_version デフォルトのアプリケーション バージョンの設定 gcloud app services set-traffic
appengine:update アプリ バージョンを作成または更新します。 gcloud app deploy
appengine:update_cron アプリケーションの cron ジョブを更新します。 gcloud app deploy
appengine:update_dispatch アプリケーションのディスパッチ構成の更新 gcloud app deploy
appengine:update_dos アプリケーションの DoS 保護設定を更新します。 gcloud app deploy
appengine:update_indexes アプリケーションのインデックスを更新します。 gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues アプリケーションのタスクキュー定義を更新します。 gcloud app deploy
appengine:vacuum_indexes 使用されていないインデックスをアプリケーションから削除します。 gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version 指定したモジュール バージョンを開始します。 gcloud app versions start
appengine:stop_module_version 指定したモジュール バージョンを停止します。 gcloud app versions stop

アップロード エラーのトラブルシューティングを行う

更新ゴールを使用すると、更新試行に失敗した場合に 404 Not Found This application does not exist (app_id=u'your-app-ID') のようなメッセージが表示されることがあります。 このエラーは、複数の Google アカウントがあり、誤ったアカウントを使用して、更新を実行した場合に発生します。

この問題を解決するには、ディレクトリを ~ に変更し、.appcfg_oauth2_tokens_java というファイルを見つけて、その名前を変更します。その後、更新をやり直してください。