Apache Maven und das (App Engine SDK-basierte) App Engine-Plug-in verwenden

Auf dieser Seite erfahren Sie, wie Sie ein App Engine-Projekt mit Apache Maven verwalten, einem Tool zum Verwalten und Nachvollziehen von Softwareprojekten. Dieses Tool ist in der Lage, WAR-Dateien zur Bereitstellung in App Engine zu erstellen. Google stellt ein Plug-in und Maven-Archetypen zur Verfügung, die in Maven 3.5 enthalten sind.

Wenn Sie Maven verwenden, müssen Sie die Java-Bibliotheken nicht manuell aus dem App Engine SDK herunterladen. Maven lädt bei Bedarf automatisch die entsprechenden Bibliotheken herunter. Außerdem können Sie Ihre Anwendung mit Maven lokal testen und in der App Engine-Produktionsumgebung bereitstellen.

Maven einrichten

Java konfigurieren

  1. Laden Sie Java herunter und installieren und konfigurieren Sie es, sofern nicht bereits geschehen.
  2. Legen Sie die Compiler-Flags in pom.xml fest, um den Bytecode von Java 8 anzugeben.
    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 installieren

Mit dem folgenden Befehl können Sie prüfen, ob Maven installiert ist und wenn ja, welche Version:

 mvn -v

Falls nicht die richtige Version von Maven installiert ist, gehen Sie wie folgt vor:

  1. Gehen Sie zur Maven-Website und laden Sie Maven 3.5 herunter.
  2. Installieren Sie Maven 3.5 auf Ihrem lokalen Rechner.

Cloud-Projekt einrichten und validieren

Sie müssen Ihr Cloud-Projekt einrichten und das App Engine SDK installieren:

  1. Verwenden Sie die Google Cloud Console, um Ihr Cloud-Projekt zu erstellen und einzurichten:

    Zu App Engine

    1. Wählen Sie ein Cloud-Projekt aus oder erstellen Sie ein neues.
    2. Wenn Sie eine App Engine-Anwendung für Ihr Projekt erstellen müssen, werden Sie zur Auswahl einer Region aufgefordert, in der sich die App Engine-Anwendung befinden soll.
    3. Das Dashboard wird geöffnet, nachdem die App Engine-Anwendung in Ihrem Projekt erstellt wurde.

  2. Installieren Sie das App Engine SDK für Java und fügen Sie das Verzeichnis Ihrem PATH hinzu.

Maven verwenden

App Engine-Plug-in in ein vorhandenes Projekt aufnehmen (optional)

Damit Sie das Maven-Plug-in für Google App Engine in einem vorhandenen Maven-Projekt verwenden können, fügen Sie Folgendes in den Abschnitt plugins der Projektdatei pom.xml ein:

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

Archetyp auswählen

Mit Maven-Archetypen können Nutzer Maven-Projekte mit Vorlagen erstellen, die allgemeine Szenarien abdecken. App Engine verwendet dieses Maven-Feature, um einige nützliche App Engine-Archetypen auf Maven Central zur Verfügung zu stellen. Wählen Sie einen geeigneten App Engine-Archetypen für Ihre Anwendung aus:

Anwendungstyp Artefakt Beschreibung
App Engine-App guestbook-archetype Generiert das Gästebuch-Demobeispiel vollständig, sodass Sie es ausführen und testen können.
App Engine-App appengine-skeleton-archetype Erstellt ein neues, leeres App Engine-Projekt mit den erforderlichen Dateien und Verzeichnissen, einsatzbereit für Ihre eigenen Klassen und Ressourcen.

Neues Projekt erstellen

Bei der Projekterstellung werden Sie von Maven aufgefordert, groupId, artifactId, version und das package für das Projekt anzugeben.

Begriff Bedeutung
groupId Ein Namespace in Maven, um Ihre Artefakte zu erfassen. Wenn Nutzer Ihr Projekt in ihrem eigenen Maven-Projekt verwenden, dient er als Attribut der Abhängigkeit, die die Nutzer letztendlich angeben.
artifactId Der Name Ihres Projekts in Maven. Er wird auch von Nutzern Ihres Projekts angegeben, wenn ihre eigenen Maven-Projekte von Ihrem Projekt abhängig sind.
version Die ursprüngliche Maven-Version, mit der Ihr Projekt generiert werden soll. Es empfiehlt sich, version mit dem Suffix -SNAPSHOT zu versehen, da dies im Maven-Release-Plug-in Unterstützung für Versionen bietet, die sich in der Entwicklung befinden. Weitere Informationen finden Sie in der Maven-Anleitung zur Verwendung des Release-Plug-ins.
package Das während der Generierung erstellte Java-Paket.

Im Folgenden wird beschrieben, wie App Engine-Maven-Archetypen zum Erstellen einer App Engine-Anwendung verwendet werden.

So erstellen Sie eine App Engine-Anwendung:

  1. Wechseln Sie in das Verzeichnis, in dem Sie das Projekt erstellen möchten.

  2. Rufen Sie den folgenden Maven-Befehl auf:

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

    Stellen Sie -Dappengine-version auf die neueste Version des App Engine SDK für Java und application-id auf die ID Ihres Cloud-Projekts.

    Legen Sie -Djava8=true fest, um das Projekt in der Java 8-Laufzeit bereitzustellen.

    Legen Sie -DCloudSDK_Tooling=false fest, um das App Engine SDK für Java-Tooling zu verwenden.

  3. Wenn Sie zur Auswahl eines Archetyps aufgefordert werden, wählen Sie für den App Engine-Skeleton-Archetyp den Wert 2 aus. Dadurch wird ein leeres Projekt erstellt, in dem die erforderliche Verzeichnisstruktur und die erforderlichen Dateien enthalten sind.

  4. Wenn Sie zur Angabe der Version aufgefordert werden, drücken Sie die Eingabetaste, um die neueste Standardversion auszuwählen.

  5. Geben Sie bei der Aufforderung Define value for property 'groupId' den gewünschten Namespace für Ihre Anwendung an. Beispiel: com.mycompany.myapp.

  6. Geben Sie bei der Aufforderung Define value for property 'artifactId' den Projektnamen an. Beispiel: myapp.

  7. Übernehmen Sie den Standardwert (Define value for property 'version'), wenn Sie zur Bestätigung Ihrer Auswahl aufgefordert werden.

  8. Geben Sie bei der Aufforderung Define value for property 'package' Ihren bevorzugten Paketnamen an (oder übernehmen Sie den Standardwert). Die generierten Java-Dateien übernehmen den hier angegebenen Paketnamen.

  9. Übernehmen Sie den Standardwert (Y), wenn Sie zur Bestätigung Ihrer Auswahl aufgefordert werden.

  10. Warten Sie, bis das Projekt die erforderlichen Verzeichnisse und Dateien erstellt hat. Wechseln Sie dann in das neue Projektverzeichnis, beispielsweise myapp/.

    Wenn das Projekt erfolgreich erstellt wurde, sehen Sie eine Nachricht wie diese:

    [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. Bevor Sie mit dem Codieren Ihrer eigenen Klassen für die Anwendung beginnen, sollten Sie sich mit dem grundlegenden Projektlayout und den erforderlichen Projektdateien vertraut machen. Im Verzeichnis, in dem Sie das Projekt erstellt haben, ist ein Unterverzeichnis namens myapp. Es umfasst die Datei pom.xml, das Unterverzeichnis src/main/java und das Unterverzeichnis src/main/webapp/WEB-INF:

    Maven-Projektlayout

    • Sie fügen Ihre eigenen Java-Anwendungsklassen unter src/main/java/... hinzu.
    • Konfigurieren Sie Ihre Anwendung mit der Datei src/main/webapp/WEB-INF/appengine-web.xml.
    • Konfigurieren Sie die Anwendungsbereitstellung mit der src/main/webapp/WEB-INF/web.xml-Datei

  12. Erstellen Sie Ihre Java-Anwendungsklassen und fügen Sie sie unter src/main/java/... hinzu. Weitere Informationen finden Sie unter Anwendung in App Engine erstellen.

  13. Fügen Sie die UI hinzu, die Sie Ihren Anwendungsnutzern zur Verfügung stellen möchten. Weitere Informationen finden Sie unter Umgang mit Formulardaten.

  14. Das Artefakt, mit dem Sie das Projekt erstellt haben, hat die grundlegende Konfiguration in src/main/webapp/WEB-INF/appengine-web.xml für Sie erledigt. Wenn Sie die Konfiguration jedoch erweitern möchten, müssen Sie diese Datei unter Umständen bearbeiten. Weitere Informationen finden Sie unter Mit appengine-web.xml konfigurieren.

  15. Bearbeiten Sie die src/main/webapp/WEB-INF/web.xml-Datei, um URLs Ihren Anwendungs-Handlern zuzuordnen, die Authentifizierung und Filter anzugeben usw. Dies wird unter Der Deployment-Deskriptor detailliert beschrieben.

Maven-Projekt verwalten

Projekt kompilieren und erstellen

So erstellen Sie eine Anwendung, die mit App Engine-Maven-Archetypen generiert wurde:

  1. Wechseln Sie zum Hauptverzeichnis des Projekts, beispielsweise guestbook/.

  2. Rufen Sie Maven auf:

    mvn clean package

  3. Warten Sie, bis das Projekt erstellt ist. Wenn das Projekt erfolgreich erstellt wurde, sehen Sie eine Nachricht wie diese:

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

  4. Testen Sie die Anwendung wahlweise anhand des folgenden Verfahrens.

Anwendung mit dem Entwicklungsserver testen

Sie können Ihre Anwendung in der Entwicklungsphase jederzeit auf dem Entwicklungsserver ausführen und testen, wenn Sie das Maven-Plug-in für App Engine aufrufen. Die Vorgehensweise variiert geringfügig je nach dem Artefakt, das zur Erstellung des Projekts verwendet wurde.

So testen Sie Ihre Anwendung:

  1. Erstellen Sie gegebenenfalls Ihre Anwendung (mvn clean package).

  2. Wechseln Sie zum Verzeichnis der obersten Ebene Ihres Projekts, beispielsweise myapp, und rufen Sie Maven auf:

    mvn appengine:devserver

    Warten Sie, bis der Server gestartet wurde. Wenn er vollständig gestartet wurde und Ihre Anwendung ausgeführt wird, sehen Sie eine Nachricht ähnlich der Folgenden:

    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. Rufen Sie mit Ihrem Browser http://localhost:8080/ auf, um auf Ihre Anwendung zuzugreifen.

  4. Beenden Sie die Anwendung und den Entwicklungsserver, indem Sie im Windows/Linux-Terminalfenster, in dem Sie den Server gestartet haben, Strg + C oder auf dem Mac cmd + C drücken.

Port für lokale Tests angeben

Wenn Sie Ihre Anwendung auf dem lokalen Entwicklungsserver ausführen, ist der Standardport 8080. Sie können diese Standardeinstellung ändern, indem Sie den Plug-in-Eintrag für appengine-maven-plugin anpassen (oder ihn hinzufügen, falls er nicht vorhanden ist). Beispielsweise geben wir Port und Adresse im folgenden <plugin>-Eintrag in <plugins> in der pom.xml-Hauptdatei der Anwendung an (myapp/pom.xml):

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

Beachten Sie, dass <port> den hier angegebenen Port auf 8181 setzt und als Adresse 0.0.0.0 angegeben wird. Das bedeutet, dass der Entwicklungsserver Anfragen vom lokalen Netzwerk entgegennimmt.

Anwendung bereitstellen

Informationen hierzu finden Sie in der Anleitung zum Bereitstellen der Anwendung.

Referenz: Verfügbare Ziele

Sobald das Maven-Plug-in für App Engine der pom.xml-Datei des Projekts hinzugefügt wurde, sind mehrere App Engine-spezifische Maven-Ziele verfügbar. Um alle verfügbaren Ziele anzuzeigen, rufen Sie folgenden Befehl auf:

 mvn help:describe -Dplugin=appengine

Die Ziele des Maven-Plug-ins für App Engine können als Entwicklungsserverziele, Anwendungs- und Projektverwaltungsziele sowie Endpoints-Ziele kategorisiert werden.

Entwicklungsserverziele

Im Folgenden sind die Entwicklungsserverziele aufgeführt:

appengine:devserver

Führt den App Engine-Entwicklungsserver aus. Bei Ausführung des Servers wird regelmäßig geprüft, ob sich appengine-web.xml geändert hat. Wenn dies der Fall ist, führt der Server einen Hot Reload der Anwendung durch. Daher müssen Sie Ihre Anwendung aufgrund von Änderungen an appengine-web.xml nicht beenden oder neu starten. Folgende Parameter sind verfügbar:

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

Um die Ausführung des Servers beispielsweise im Debug-Modus an Port 8000 ohne Sperrung zur Startzeit zu ermöglichen, können Sie folgende Flags verwenden:

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

Das <fullScanSeconds>-Flag ist standardmäßig auf 5 Sekunden eingestellt. Das bedeutet, dass der Server alle fünf Sekunden auf Änderungen in den Webanwendungsdateien prüft und die Anwendung automatisch neu lädt. Dies ist in IDEs nützlich, die die Funktion zum Speichern bei Kompilierung unterstützen, wie zum Beispiel NetBeans. Um dieses Feature nutzen zu können, müssen Sie den <build>-Abschnitt konfigurieren:

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

Führt für den Entwicklungsserver einen asynchronen Start aus und kehrt dann zur Befehlszeile zurück. Die Ausführung dieses Ziels ist mit der Ausführung des Ziels devserver identisch, mit dem Unterschied, dass Maven weiter Ziele verarbeitet und beendet wird, wenn der Server ausgeführt wird.

appengine:devserver_stop

Stoppt den Entwicklungsserver. Ist nur verfügbar, wenn Sie den Entwicklungsserver mit appengine:devserver_start gestartet haben.

Anwendungsverwaltungsziele

Die Ziele für die Anwendungs- und Projektverwaltung sind in der folgenden Tabelle aufgeführt:

Ziel Beschreibung Entsprechender gcloud-Befehl
appengine:backends_stop Damit wird jeder laufende Entwicklungsserver gestoppt, der den in Ihrer pom.xml-Datei konfigurierten Port abhört. Dieses Ziel kann in Verbindung mit dem Befehl devserver_start verwendet werden, um Integrationstests mit dem Maven-Plug-in durchzuführen.
appengine:backends_configure Konfiguriert das angegebene Back-End.
appengine:backends_delete Löscht das angegebene Back-End.
appengine:backends_rollback Führt für ein zuvor laufendes Update ein Rollback aus.
appengine:backends_start Startet das angegebene Back-End.
appengine:backends_update Aktualisiert das angegebene Back-End oder alle Back-Ends, wenn kein Back-End angegeben ist.
appengine:enhance Führt die Datanucleus JDO-Erweiterung von App Engine aus.
appengine:rollback Führt für ein laufendes Update ein Rollback aus. gcloud app versions start, gcloud app versions stop
appengine:set_default_version Legt die Standardversion der Anwendung fest. gcloud app services set-traffic
appengine:update Erstellt oder aktualisiert eine Anwendungsversion. gcloud app deploy
appengine:update_cron Aktualisiert die Cronjobs der Anwendung. gcloud app deploy
appengine:update_dispatch Aktualisiert die Weiterleitungskonfiguration der Anwendung. gcloud app deploy
appengine:update_dos Aktualisiert die DoS-Schutzkonfiguration der Anwendung. gcloud app deploy
appengine:update_indexes Aktualisiert Anwendungsindizes. gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues Aktualisiert Aufgabenwarteschlangen-Definitionen der Anwendung. gcloud app deploy
appengine:vacuum_indexes Löscht nicht verwendete Indizes aus der Anwendung. gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version Startet die angegebene Modulversion. gcloud app versions start
appengine:stop_module_version Stoppt die angegebene Modulversion. gcloud app versions stop

Fehlerbehebung bei Uploadfehlern

Wenn Sie das Aktualisierungsziel verwenden, kann der Aktualisierungsversuch mit einer Nachricht ähnlich der folgenden fehlschlagen: 404 Not Found This application does not exist (app_id=u'your-app-ID'). Dieser Fehler tritt auf, wenn Sie über mehrere Google-Konten verfügen und das Update mit dem falschen Konto ausführen.

Um dieses Problem zu beheben, wechseln Sie in das Verzeichnis ~, suchen Sie nach der Datei mit dem Namen .appcfg_oauth2_tokens_java und benennen Sie diese um. Wiederholen Sie anschließend das Update.