Migration zum gcloud-CLI-basierten Gradle-Plug-in
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Wenn Sie zuvor das Java App Engine SDK-basierte Plug-in (com.google.appengine.appengine-gradle) verwendet haben und zur neuen Google Cloud CLI wechseln möchten, migrieren Sie zum gcloud CLI-basierten Plug-In (com.google.cloud.tools.appengine-gradle).
Vorteile des gcloud CLI-basierten Plug-ins
Ein Upgrade auf das neue Plug-in bietet folgende Vorteile:
Verwendung derselben Anmeldedaten für die Authentifizierung wie bei allen anderen gcloud CLI-basierten Befehlen, die im Rahmen des standardmäßigengcloud auth login-Ablaufs erstellt werden.
Unterstützung der flexiblen App Engine-Umgebung
Automatische Aktualisierung des lokalen Entwicklungsservers im Rahmen des standardmäßigen gcloud CLI-Aktualisierungsablaufs.
Unterstützung der Bereitstellung von Konfigurationen für App Engine-Dienste (cron, queues, dos, dispatch) unabhängig von Ihrem Dienst
Wichtige Unterschiede
Berücksichtigen Sie vor der Migration folgende wichtige Unterschiede:
- Abhängigkeit von gcloud CLI
- Mit Ausnahme von Java wird das alte Plug-in ohne spezifische lokale Umgebungsabhängigkeiten ausgeführt. Allerdings erfordert das neue Plug-in die Installation der gcloud CLI.
- Keine Generierung von Endpoints-Discovery-Dokumenten
- Das neue Plug-in generiert keine Endpoints-Discovery-Dokumente. Dieses Feature ist in einem separaten Plug-in verfügbar. Zur Ausführung des Endpoints-Back-Ends muss diese Datei nicht mehr in einem Build-Schritt generiert werden. Dies übernimmt der Server zur Laufzeit. Sie sollten das neue Plug-in nur verwenden, wenn Sie Clientbibliotheken generieren müssen, etwa für iOS oder Android. Weitere Informationen zu den neuen Plug-ins finden Sie in der Anleitung Zu Endpoints Frameworks für App Engine migrieren.
- Das EAR-Dateiformat wird nicht mehr unterstützt
- Das EAR-Dateiformat zum gleichzeitigen Ausführen und Bereitstellen mehrerer Dienste wird im neuen Plug-in nicht mehr unterstützt.
- Neuer Bereitstellungsbefehl
- Im alten Plug-in muss zur Bereitstellung von Anwendungen der Befehl
appcfg aufgerufen werden. Im neuen Plug-in erfolgt dies über die neue gcloud CLI.
- JPA/JDO-DataNucleus-Erweiterung muss manuell konfiguriert werden
- Wenn in Ihrem Projekt die JPA/JDO-Datanucleus-Erweiterung von
gradle-appengine-plugin verwendet wird, müssen Sie die Datanucleus-Erweiterung nach dem Wechsel zum gcloud CLI-basierten Plug-in manuell konfigurieren. Siehe Stackoverflow-Beispiel.
- Android Studio wird nicht unterstützt
- Sie können Ihr Android Studio-Projekt auf die Verwendung des neuen Plug-ins umstellen, allerdings funktionieren der App Engine-Entwicklungsserver für Android Studio und die Bereitstellungsunterstützung nicht mit dem neuen Plug-in. Sie müssen Gradle direkt aufrufen, um Ihre Anwendung auszuführen und bereitzustellen.
Die Verwendung von XML-Konfigurationsdateien wird unterstützt, jedoch nicht YAML.
Zum neuen Plug-in migrieren
Entfernen Sie die alte gradle-appengine-plugin-Konfiguration und die Importe aus der build.gradle-Datei.
Fügen Sie das neue Plug-in in den classpath des Abschnitts buildscript Ihrer build.gradle-Datei ein:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
}
}
Führen Sie im Stammverzeichnis Ihres Dienstes folgenden Befehl aus, um zu prüfen, ob Sie Ihre Anwendung lokal ausführen können:
gradle appengineRun
Konfigurieren Sie im Abschnitt buildscript der Datei build.gradle Ihre Bereitstellung. Geben Sie dazu Ihre Projekt-ID und Version an:
appengine {
deploy {
version = 'v1'
project = "your GCP project ID"
}
}
Das neue Tool ignoriert die Anwendungs- und Versionselemente in der Datei appengine-web.xml.
Führen Sie im Stammverzeichnis Ihres Dienstes folgenden Befehl aus, um zu prüfen, ob Sie Ihre Anwendung bereitstellen können:
gradle appengineDeploy
EAR-basierte Konfigurationen für mehrere Dienste migrieren
Das neue Plug-in unterstützt keine EAR-Paketerstellung. Stattdessen wird die lokale Ausführung mehrerer Dienste ohne spezielle Paketerstellungsschritte unterstützt.
So migrieren Sie Ihr EAR-basiertes Gradle-Projekt:
Wählen Sie einen primären Dienst aus, der für die Ausführung der übrigen Dienste zuständig ist. Sie sollten Ihren Standarddienst auswählen, es kann aber auch jeder andere Dienst sein, der zusammen mit den anderen ausgeführt wird.
Ändern Sie in der appengine-Konfiguration den Eintrag run.services dahingehend, dass alle Dienste eingeschlossen sind, die vom lokalen Entwicklungsserver ausgeführt werden sollen.
Eine Beispielprojektstruktur:
../{projectRoot}/
build.gradle
settings.gradle (includes default-service & secondary-service)
{your-default-service}/build.gradle {includes appengine-gradle-plugin}
….
{your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml
{your-secondary-service}build.gradle {includes appengine-gradle-plugin}
….
{your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml
Ein Beispiel für ein build.gradle-Build-Skript:
appengine {
run {
// configure the app to point to the right service directories
services = [
projectAsService(project),
projectAsService(":another-module")
]
}
}
// helper method to obtain correct directory and set up dependencies
def getExplodedAppDir(Project serverProject) {
// if not 'this' module, then do some setup.
if (serverProject != project) {
// make sure we evaluate other modules first so we get the right value
evaluationDependsOn(serverProject.path)
// make sure we build "run" depends on the other modules exploding wars
project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar
}
return serverProject.tasks.explodeWar.explodedAppDirectory
}
App Engine SDK-basierte und gcloud-CLI-basierte Gradle-Befehle im Vergleich
Die folgende Tabelle zeigt verschiedene Möglichkeiten zum Aufrufen des Gradle-Plug-ins, je nachdem, ob Sie das App Engine SDK-basierte Gradle-Plug-in oder das gcloud CLI-basierte Gradle-Plug-in verwenden.
| Aktion |
App Engine SDK-basiert |
gcloud CLI-basiert |
| Anwendung lokal ausführen |
appengine:devserver |
appengineRun |
| Stellt neue Anwendung, neue Version oder neuen Dienst bereit. |
appengine:update |
appengineDeploy |
| Legt die Standardversion der Anwendung fest. |
appengine:set_default_version |
gcloud app services set-traffic oder gcloud app versions migrate |
| Aktualisiert die Cronjobs der Anwendung. |
appengine:update_cron |
appengineDeployCron |
| Aktualisiert die Weiterleitungskonfiguration der Anwendung. |
appengine:update_dispatch |
appengineDeployDispatch |
| Aktualisiert die DoS-Schutzkonfiguration der Anwendung. |
appengine:update_dos |
appengineDeployDos |
| Aktualisiert Aufgabenwarteschlangen-Definitionen der Anwendung. |
appengine:update_queues |
appengineDeployQueue |
| Aktualisiert Datenspeicherindexe. |
appengine:update_indexes |
appengineDeployIndex |
| Löscht nicht verwendete Indizes aus der Anwendung. |
appengine:vacuum_indexes |
Bereinigung von gcloud-Datenspeicherindexen |
| Startet die angegebene Modulversion. |
appengine:start_module_version |
gcloud app versions start |
| Stoppt die angegebene Modulversion. |
appengine:stop_module_version |
gcloud app versions stop |
| Führt für ein laufendes Update ein Rollback aus. |
appengine:rollback |
gcloud app versions start, gcloud app versions stop |
Weitere Informationen
Sofern nicht anders angegeben, sind die Inhalte dieser Seite unter der Creative Commons Attribution 4.0 License und Codebeispiele unter der Apache 2.0 License lizenziert. Weitere Informationen finden Sie in den Websiterichtlinien von Google Developers. Java ist eine eingetragene Marke von Oracle und/oder seinen Partnern.
Zuletzt aktualisiert: 2025-09-04 (UTC).
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eMigrate from the Java App Engine SDK-based plugin (\u003ccode\u003ecom.google.appengine.appengine-gradle\u003c/code\u003e) to the gcloud CLI-based plugin (\u003ccode\u003ecom.google.cloud.tools.appengine-gradle\u003c/code\u003e) for enhanced benefits, including unified authentication, flexible environment support, and automatic updates.\u003c/p\u003e\n"],["\u003cp\u003eThe new gcloud CLI-based plugin requires the gcloud CLI to be installed and no longer supports Endpoints discovery doc generation within the plugin, as it's now handled at runtime, nor does it support the EAR file format for multiple services.\u003c/p\u003e\n"],["\u003cp\u003eManual configuration of Datanucleus enhancement is necessary if your project uses JPA/JDO, and Android Studio's built-in App Engine support is incompatible, requiring direct Gradle invocation.\u003c/p\u003e\n"],["\u003cp\u003eMigrating from EAR-based multi-service configurations to the new plugin involves selecting a primary service and configuring the \u003ccode\u003erun.services\u003c/code\u003e entry in your \u003ccode\u003ebuild.gradle\u003c/code\u003e to include all services for local development, replacing EAR packaging entirely.\u003c/p\u003e\n"],["\u003cp\u003eThe gcloud CLI-based plugin uses new Gradle commands like \u003ccode\u003eappengineRun\u003c/code\u003e for local development and \u003ccode\u003eappengineDeploy\u003c/code\u003e for deployment, replacing the old SDK-based commands such as \u003ccode\u003eappengine:devserver\u003c/code\u003e and \u003ccode\u003eappengine:update\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Migrating to the gcloud CLI-based Gradle plugin\n\nIf you previously used the Java App Engine SDK-based plugin\n(`com.google.appengine.appengine-gradle`) and want to move to the new\n[Google Cloud CLI](/sdk/downloads), migrate to the gcloud CLI-based\n(`com.google.cloud.tools.appengine-gradle`) plugin.\n\nBenefits of the gcloud CLI-based plugin\n---------------------------------------\n\nUpgrading to the new plugin provides the following benefits:\n\n- Uses the same authentication credentials as all other gcloud CLI\n -based commands, which are produced from the standard `gcloud auth login`\n flow.\n\n- Supports the App Engine flexible environment.\n\n- Updates the local development server automatically as part of the standard\n gcloud CLI update flow.\n\n- Supports deploying App Engine service (cron, queues, dos, dispatch)\n configurations, independently from your service.\n\nNotable differences\n-------------------\n\nBefore you migrate, be aware of these notable differences:\n\ngcloud CLI dependency\n: The old plugin runs without any specific local environment dependencies,\n besides Java, but the new plugin requires that you have the\n gcloud CLI installed.\n\nNo Endpoints discovery doc generation\n: The new plugin does not generate Endpoints discovery docs, a\n feature available in a separate plugin. Running your Endpoints\n backend no longer requires generating this file in a build step as the server\n now generates it at runtime. You should use the new plugin only if you need\n to generate client libraries such as for iOS or Android. Learn more about the\n new plugins by reviewing the [Migrating to Endpoints Frameworks for\n App Engine](/endpoints/docs/frameworks/legacy/v1/java/migrating)\n guide.\n\nEAR file format no longer supported\n: The new plugin no longer supports the\n EAR file format for running and deploying multiple services at the same time.\n\nNew deployment command\n: The old plugin calls the `appcfg` command to deploy\n applications, while the new plugin deploys using the new gcloud CLI.\n\nJPA/JDO Datanucleus enhancement must be manually configured\n: If your project\n uses the `gradle-appengine-plugin`'s JPA/JDO Datanucleus enhancement, you must\n manually configure Datanucleus enhancement after switching to the\n gcloud CLI-based plugin. See an [example from Stackoverflow](https://stackoverflow.com/questions/29279503/how-can-i-run-datanucleus-enhancer-from-gradle).\n\nAndroid Studio is not supported\n: You can switch your Android Studio project to use the new plugin, but the\n Android Studio App Engine development server and deployment support\n does not work with this new plugin. To run and deploy your app, you have to\n invoke Gradle directly.\n\nUse of XML configuration files is supported, but not YAML.\n\nMigrating to the new plugin\n---------------------------\n\n1. Remove the old `gradle-appengine-plugin` configuration and imports from your\n `build.gradle` file.\n\n2. Add the new plugin to the `classpath` of your `build.gradle` file's\n `buildscript` section:\n\n buildscript {\n repositories {\n mavenCentral()\n }\n\n dependencies {\n classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'\n }\n }\n\n3. At the root of your service, run the following command to verify that you can\n run your app locally:\n\n gradle appengineRun\n\n4. In your `build.gradle` file's `buildscript` section, configure your\n deployment by specifying your project ID and version:\n\n appengine {\n deploy {\n version = 'v1'\n project = \"your GCP project ID\"\n }\n }\n\n The new tooling ignores the application and version elements in your\n `appengine-web.xml` file.\n5. At the root of your service, run the following command to verify that you can\n deploy your application:\n\n gradle appengineDeploy\n\nMigrating EAR based multi-service configurations\n------------------------------------------------\n\nThe new plugin does not support EAR packaging. Instead, it supports running\nmultiple services locally without any special packaging steps.\n\nTo migrate your EAR-based Gradle project:\n\n1. Pick a primary service that will be responsible for running the rest of the\n services. You should select your default service, but it can be any of the\n services that are run together.\n\n2. In your `appengine` configuration, modify the `run.services` entry to include\n all the services that should be run by the local development server.\n\n An example project structure: \n\n ../{projectRoot}/\n build.gradle\n settings.gradle (includes default-service & secondary-service)\n {your-default-service}/build.gradle {includes appengine-gradle-plugin}\n ....\n {your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml\n {your-secondary-service}build.gradle {includes appengine-gradle-plugin}\n ....\n {your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml\n\n An example `build.gradle` buildscript: \n\n appengine {\n run {\n // configure the app to point to the right service directories\n services = [\n projectAsService(project),\n projectAsService(\":another-module\")\n ]\n }\n }\n\n // helper method to obtain correct directory and set up dependencies\n def getExplodedAppDir(Project serverProject) {\n // if not 'this' module, then do some setup.\n if (serverProject != project) {\n // make sure we evaluate other modules first so we get the right value\n evaluationDependsOn(serverProject.path)\n // make sure we build \"run\" depends on the other modules exploding wars\n project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar\n }\n return serverProject.tasks.explodeWar.explodedAppDirectory\n }\n\nApp Engine SDK-based vs gcloud CLI-based Gradle commands\n--------------------------------------------------------\n\nThe following table shows the different ways you invoke the Gradle plugin,\ndepending on whether you use the App Engine SDK-based Gradle plugin or\nthe [gcloud CLI-based Gradle](/appengine/docs/legacy/standard/java/using-gradle)\nplugin.\n\nWhat's next\n-----------\n\n- Now that you have migrated to the new plugin successfully, you can [test](/appengine/docs/legacy/standard/java/using-gradle#testing_gradle_app) and [deploy](/appengine/docs/legacy/standard/java/using-gradle#deploying_gradle_app) your application."]]
