Referenz für appengine-web.xml

Regions-ID

REGION_ID ist ein abgekürzter Code, den Google anhand der Region zuweist, die Sie beim Erstellen Ihrer Anwendung ausgewählt haben. Der Code bezieht sich nicht auf ein Land oder eine Provinz, auch wenn einige Regions-IDs häufig verwendeten Länder- und Provinzcodes ähneln können. Bei Anwendungen, die nach Februar 2020 erstellt wurden, ist REGION_ID.r in den App Engine-URLs enthalten. Bei Anwendungen, die vor diesem Datum erstellt wurden, ist die Regions-ID in der URL optional.

Hier finden Sie weitere Informationen zu Regions-IDs.

Sie sollten die Datei appengine-web.xml nur zum Konfigurieren Ihrer Anwendung verwenden, wenn Sie eine vorhandene Anwendung von der Java 8-Laufzeit von App Engine zur neuesten unterstützten Java-Version migrieren und die gebündelten Legacy-Dienste verwenden möchten. Wenn Sie in Ihrem Projekt die Datei appengine-web.xml verwenden, wird die Datei app.yaml bei der Bereitstellung automatisch generiert.

App Engine-Java-Anwendungen nutzen eine Konfigurationsdatei mit dem Namen appengine-web.xml. Damit geben Sie Informationen zur Anwendung an und legen fest, welche Dateien im Verzeichnis WAR der Anwendung statische Dateien (z. B. Bilder) und welche Ressourcendateien sind, die von der Anwendung verwendet werden.

Syntax

Das WAR einer Java-Anwendung für App Engine muss eine Datei namens appengine-web.xml im Verzeichnis WEB-INF/ aufweisen. Hierbei handelt es sich um eine XML-Datei mit dem Stammelement <appengine-web-app>.

Sie finden die Dokumenttypdefinition und die Schemaspezifikationen für appengine-web.xml im SDK-Verzeichnis docs/.

Element Beschreibung
<application>

Nicht erforderlich, wenn Sie Ihre Anwendung mit Google Cloud SDK-basierten Tools bereitstellen, wie z. B. dem gcloud app deploy-Befehl, IntelliJ-, Eclipse-, Maven- oder Gradle-Plugins. Die auf Google Cloud SDK basierenden Tools ignorieren dieses Element und rufen die Projekt-ID aus dem Attribut "gcloud config" ab. Beachten Sie, dass Sie die Projekt-ID zwar mithilfe des Befehlszeilentools gcloud überschreiben können, dabei jedoch eine maschinenweite Projekt-ID festgelegt wird, die zu Verwirrung führen kann, falls Sie mehrere Projekte gleichzeitig entwickeln. Das <application>-Element enthält die Projekt-ID der Anwendung. Dies ist die Projekt-ID, die Sie registrieren, wenn Sie Ihr Projekt in der Google Cloud Console erstellen.

<app-engine-apis>

Optional. Wenn Sie die gebündelten Legacy-Dienste von App Engine für Laufzeiten der zweiten Generation verwenden möchten, legen Sie dieses Feld auf true fest.

<entrypoint>

Optional und nur für Laufzeiten der zweiten Generation. Überschreibt den Standardeinstiegspunkt, der die Prozessbefehlszeile ist, die die Java-Anwendung startet. Standardmäßig entspricht der generierte Einstiegspunkt für eine F4-Instanzklasse (Speichereinstellungen werden aus der Instanzklasse berechnet) der folgenden Konfiguration:

  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <entrypoint>
   java
   -showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled
   -XX:+PrintCommandLineFlags
   --add-opens java.base/java.lang=ALL-UNNAMED
   --add-opens java.base/java.nio.charset=ALL-UNNAMED
   --add-opens java.logging/java.util.logging=ALL-UNNAMED
   --add-opens java.base/java.util.concurrent=ALL-UNNAMED
   -Dclasspath.runtimebase=/base/java_runtime
   -Djava.class.path=/base/java_runtime/runtime-main.jar
   -Djava.library.path=/base/java_runtime:
   com/google/apphosting/runtime/JavaRuntimeMainWithDefaults
   --fixed_application_path=/workspace
   /base/java_runtime
  </entrypoint>
</appengine-web-app>

Sie können die Konfiguration ändern, um zusätzliche JVM-Prozess-Flags hinzuzufügen oder einen eigenen Prozess zum Booten zu definieren. Die Anwendung wird im Verzeichnis /workspace bereitgestellt, während sich die Laufzeit-JARs im Verzeichnis /base/java_runtime befinden.

Informationen zum Anpassen des Einstiegspunkts für die Java-Laufzeit mithilfe von Umgebungsvariablen
<async-session-persistence>

Optional. Wenn Sie die Latenz von Anfragen reduzieren möchten, konfigurieren Sie Ihre Anwendung so, dass sie HTTP-Sitzungsdaten asynchron in den Datenspeicher schreibt:

<async-session-persistence enabled="true" />

Wenn die asynchrone Sitzungspersistenz (async-session-persistence) aktiviert ist, sendet App Engine zuerst eine Aufgabe zum Schreiben von Sitzungsdaten in den Datenspeicher an die Aufgabenwarteschlange und schreibt die Daten dann in Memcache. Die Aufgabe wird standardmäßig an die "Standardwarteschlange" gesendet. Wenn Sie eine andere Warteschlange verwenden möchten, fügen Sie das Attribut "queue-name" hinzu:

  <async-session-persistence enabled="true" queue-name="myqueue"/>

Sitzungsdaten werden immer synchron in Memcache geschrieben. Wenn eine Anfrage versucht, die Sitzungsdaten zu lesen, wenn Memcache nicht verfügbar ist (oder die Sitzungsdaten gelöscht wurden), erfolgt ein Failover auf den Datenspeicher, der möglicherweise noch nicht über die neuesten Sitzungsdaten verfügt. Das bedeutet, dass das Aktivieren der asynchronen Sitzungspersistenz dazu führen kann, dass Ihrer Anwendung veraltete Sitzungsdaten angezeigt werden. Bei den meisten Anwendungen überwiegt jedoch der Latenzvorteil das Risiko bei Weitem.

<auto-id-policy> Optional. Wenn Sie Entitätenbezeichner automatisch festlegen, können Sie die verwendete Methode ändern, indem Sie die Richtlinie zur automatischen ID-Vergabe (auto ID policy) einrichten. Folgende Optionen sind gültig:
default
Standard. Verwendet verteilte, automatisch vergebene IDs, bei denen es sich um große, gut verteilte Ganzzahlen handelt, die jedoch klein genug sind, um durch 64-Bit-Gleitkommazahlen dargestellt zu werden.
legacy
Die Legacy-Option wird in einem zukünftigen Release verworfen und früher oder später entfernt. Weitere Informationen finden Sie im Blogpost zur Mitteilung dieser Änderung.
<automatic-scaling>

Optional. Eine ausführliche Erläuterung finden Sie im Abschnitt zur automatischen Skalierung.

<basic-scaling>

Optional. Eine ausführliche Erläuterung finden Sie im Abschnitt zur grundlegenden Skalierung.

<env-variables>

Optional. Die appengine-web.xml-Datei kann Umgebungsvariablen definieren, die festgelegt werden, wenn die Anwendung ausgeführt wird.

<env-variables>
<env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

Zur Vermeidung von Konflikten mit Ihrer lokalen Umgebung legt der Entwicklungsserver Umgebungsvariablen nicht anhand dieser Datei fest. Stattdessen müssen für diese Variablen bereits passende Werte in der lokalen Umgebung angegeben sein.

export DEFAULT_ENCODING="UTF-8"
dev_appserver war

Bei Bereitstellung der Anwendung in App Engine wird die Umgebung mit diesen bereits festgelegten Variablen erstellt.

<inbound-services>

Optional. Bevor eine Anwendung E-Mails empfangen kann, muss sie so konfiguriert werden, dass der entsprechende Dienst aktiviert ist. Sie aktivieren den Dienst für eine Java-Anwendung durch Einfügen des Abschnitts <inbound-services> in die Datei appengine-web.xml.

Der folgende Eingangsdienst ist verfügbar:

mail
Ermöglicht Ihrer Anwendung den Empfang von E-Mails.
<instance-class>

Optional. Die Größe der Instanzklasse für dieses Modul.

Je nachdem, welche Skalierungsoptionen Sie angeben, sind folgende Instanzklassen verfügbar:

automatic_scaling
Für die automatische Skalierung stehen die Instanzklassen F1, F2, F4 und F4_1G zur Verfügung.
Standardeinstellung: Wenn Sie mit dem Element automatic_scaling keine Instanzklasse angeben, wird als Klasse F1 zugewiesen.
basic_scaling
Für die einfache Skalierung stehen die Instanzklassen B1, B2, B4, B4_1G und B8 zur Verfügung.
Standardeinstellung: Wenn Sie keine Instanzklasse mit dem Element basic_scaling angeben, wird die Klasse B2 zugewiesen.
manual_scaling
Für die manuelle Skalierung stehen die Instanzklassen B1, B2, B4, B4_1G und B8 zur Verfügung.
Standardeinstellung: Wenn Sie keine Instanzklasse mit dem Element manual_scaling angeben, wird die Klasse B2 zugewiesen.

Hinweis: Wenn instance-class auf F2 oder höher eingestellt ist, können Sie Ihre Instanzen optimieren, indem Sie max-concurrent-requests auf einen höheren Wert als den Standardwert von 10 setzen. Zum Ermitteln des optimalen Werts erhöhen Sie ihn schrittweise und überwachen die Leistung Ihrer Anwendung.

<manual-scaling>

Optional. Eine ausführliche Erklärung finden Sie im Abschnitt zur manuellen Skalierung.

<precompilation-enabled>

Optional. App Engine verwendet einen Vorkompilierungsprozess mit dem Java-Bytecode einer Anwendung, um deren Leistung in der Java-Laufzeitumgebung zu verbessern. Der vorkompilierte Code funktioniert ebenso wie der ursprüngliche Bytecode.

Wenn Sie aus irgendwelchen Gründen für Ihre Anwendung keine Vorkompilierung verwenden möchten, können Sie diese Funktion deaktivieren. Fügen Sie hierzu Folgendes zu Ihrer appengine-web.xml-Datei hinzu:

<precompilation-enabled>false</precompilation-enabled>
<module>

Hinweis: Module heißen jetzt Dienste und Dienste werden weiterhin in appengine-web.xml-Dateien als Module deklariert, z. B. <module>service_name</module>.

Erforderlich, wenn Sie einen Dienst erstellen. Optional für den Standarddienst. Jeder Dienst und jede Version muss einen Namen haben. Ein Name kann Zahlen, Buchstaben und Bindestriche enthalten. Er darf maximal 63 Zeichen lang sein und darf nicht mit einem Bindestrich beginnen oder enden oder den String "-dot" enthalten. Wählen Sie für jeden Dienst und jede Version einen eindeutigen Namen. Verwenden Sie Namen von Diensten und Versionen nicht doppelt.

Weitere Informationen finden Sie unter Dienst.

<public-root>

Optional. <public-root> ist ein Verzeichnis in Ihrer Anwendung, das die statischen Dateien für Ihre Anwendung enthält. Wenn eine Anfrage für eine statische Datei gestellt wird, wird <public-root> für die Anwendung dem Anfragepfad vorangestellt. Auf diese Weise wird der Pfad einer Anwendungsdatei angegeben, die den angeforderten Inhalt enthält.

Der Standardwert von <public-root> ist /.

Im folgenden Beispielcode wird der URL-Pfad /index.html dem Anwendungsdateipfad /static/index.html zugeordnet:

<public-root>/static</public-root>
<resource-files>

Optional. Auf die im Element <resource-files> aufgelisteten Dateien kann mithilfe des Dateisystems und des Anwendungscodes zugegriffen werden. Im Gegensatz dazu, wie statische Dateien gespeichert und bereitgestellt werden, werden diese Dateien zusammen mit der Anwendung auf den Anwendungsservern gespeichert.

Das <resource-files>-Element kann folgende Elemente enthalten:

<include>
Ein <include>-Element legt die Dateien als Ressourcendateien fest, die für Ihren Anwendungscode verfügbar sind. Für Ihren Code sind die Dateien jedoch nur schreibgeschützt verfügbar und können daher nicht zur Traffic-Verarbeitung verwendet werden. Dateien ein- und ausschließen.
<exclude>

Dateien und Verzeichnisse, die mit <exclude>-Mustern übereinstimmen, werden weder hochgeladen noch stehen sie für Ihren Anwendungscode zur Verfügung. Diese Dateien und Verzeichnisse sind für Ihre Anwendung aber weiterhin zugänglich, wenn diese auf dem lokalen Entwicklungsserver ausgeführt wird. Weitere Informationen finden Sie unter Dateien ein- und ausschließen.

Beispiel:
<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

In diesem Beispiel wird gezeigt, wie Sie alle .xml-Dateien mit Ausnahme der Dateien im feeds/-Verzeichnis und allen zugehörigen Unterverzeichnissen als Ressourcendateien festlegen können.

App Engine-Ressourcendateien werden mit java.io.File oder javax.servlet.ServletContext.getResource/getResourceAsStream gelesen. Auf sie kann nicht über Class.getResourceAsStream() zugegriffen werden.

<runtime>

Wenn Sie die neueste unterstützte Java-Version verwenden möchten, müssen Sie für diesen Eintrag den Wert java21 angeben.

Beispiel:
<runtime>java21</runtime>
<service>

Dienste wurden früher als Module bezeichnet.

Derzeit wird die Definition eines Dienstes als <service>service_name</service > nur von gcloud app-Befehlen unterstützt.

<service-account>

Optional. Mit dem Element <service-account> können Sie ein vom Nutzer verwaltetes Dienstkonto als Identität für die Version angeben. Das angegebene Dienstkonto wird verwendet, wenn Sie auf andere Google Cloud-Dienste zugreifen und Aufgaben ausführen.

Beispiel:
<service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account>
<sessions-enabled>

Optional. App Engine enthält eine Implementierung von Sitzungen, welche die Servlet-Sitzungsschnittstelle verwendet. Die Implementierung speichert Sitzungsdaten zu Persistenzzwecken im Datenspeicher und verwendet Memcache, um die Geschwindigkeit zu erhöhen. Wie bei den meisten anderen Servlet-Containern werden auch hier die Sitzungsattribute, die während der Anfrage mithilfe von "session.setAttribute()" festgelegt werden, am Ende der Anfrage beibehalten.

Diese Funktion ist standardmäßig deaktiviert. Fügen Sie zur Aktivierung appengine-web.xml Folgendes hinzu:

Beispiel:
<sessions-enabled>true</sessions-enabled>

Die Implementierung erstellt Datastore-Einheiten vom Typ _ah_SESSION sowie Memcache-Einträge unter Verwendung von Schlüsseln mit dem Präfix _ahs. Sie können diese Entitäten mithilfe der Dataflow-Vorlage löschen.

Hinweis: Da App Engine Sitzungsdaten in Datastore und in Memcache speichert, müssen alle in der Sitzung gespeicherten Werte die Schnittstelle java.io.Serializable implementieren.

Weitere Informationen zum Verringern der Latenz beim Speichern von Sitzungsdaten finden Sie unter async-session-persistence.

<ssl-enabled>

Optional. Nutzer können standardmäßig jede URL über HTTP oder HTTPS aufrufen. Sie können eine Anwendung in der Einrichtungsbeschreibung so konfigurieren, dass für bestimmte URLs HTTPS erforderlich ist. Siehe Bereitstellungsdeskriptor: Sichere URLs.

Wenn Sie die Nutzung von HTTPS für die Anwendung nicht gestatten möchten, geben Sie Folgendes in der appengine-web.xml-Datei an:

<ssl-enabled>false</ssl-enabled>

In der Java-Laufzeitumgebung ist es nicht möglich, HTTPS nur für bestimmte URL-Pfade nicht zuzulassen.

<static-error-handlers>

Optional. Bei bestimmten Fehlern wird von App Engine eine allgemeine Fehlerseite angezeigt. Sie können Ihre Anwendung so konfigurieren, dass anstelle dieser allgemeinen Fehlerseiten eine benutzerdefinierte statische Datei bereitgestellt wird, wenn die Größe der benutzerdefinierten fehlerbezogenen Daten weniger als 10 Kilobyte beträgt. Sie können für jeden unterstützten Fehlercode jeweils verschiedene statische Dateien einrichten, indem Sie die Dateien in der appengine-web.xml-Datei Ihrer Anwendung angeben. Wenn Sie benutzerdefinierte Fehlerseiten bereitstellen möchten, fügen Sie Ihrer appengine-web.xml einen Abschnitt <static-error-handlers> hinzu, wie im folgenden Beispiel beschrieben:

<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

Warnung: Der Pfad zur Fehlerantwortdatei darf sich nicht mit den Handler-Pfaden für statische Dateien überschneiden.

Jeder file-Eintrag gibt eine statische Datei an, die anstelle der allgemeinen Fehlerantwort angezeigt werden soll. Der error-code gibt an, bei welchem Fehlercode die zugehörige Datei angezeigt werden soll. Die folgenden Fehlercodes werden unterstützt:

over_quota
Zeigt an, dass die Anwendung ein Ressourcenkontingent überschritten hat.
timeout
Zeigt an, dass die Frist für das Senden einer Antwort durch Ihre Anwendung abgelaufen ist.

Der error-code ist optional. Bei fehlender Angabe bildet die angegebene Datei die Standardfehlerantwort für Ihre Anwendung.

Optional können Sie einen mime-type angeben, der beim Anzeigen der benutzerdefinierten Fehlerantwort verwendet werden soll. Wenn Sie möchten, können Sie sich eine vollständige Liste der MIME-Typen ansehen.

<static-files>

Optional. Das <static-files>-Element gibt Muster an, die Dateipfaden entsprechen, die in die Liste der statischen Dateien aufgenommen oder daraus entfernt werden sollen. Dadurch wird das Standardverhalten überschrieben oder geändert. Statische Dateien werden von dafür vorgesehenen Servern und Caches bereitgestellt, die sich von den Anwendungsservern unterscheiden und sich für die Bereitstellung von statischen Inhalten wie Bildern, CSS-Stylesheets oder JavaScript-Dateien eignen.

Das <static-files>-Element kann folgende Elemente enthalten:

<include>

Ein <include>-Element überschreibt das Standardverhalten, bei dem alle Dateien bis auf JSP-Dateien einbezogen werden. Mithilfe des Elements <include> können HTTP-Header festgelegt werden, die beim Antworten auf eine Anfrage für die angegebenen Ressourcen verwendet werden. Weitere Informationen finden Sie unter Dateien ein- und ausschließen.

Sie können den standardmäßig statischen Cache-Ablauf überschreiben, indem Sie das Attribut expiration für das Element „include” angeben. Der Wert ist ein String aus Zahlen und Einheiten, die durch Leerzeichen getrennt sind. Als Einheiten können d für Tage, h für Stunden, m für Minuten und s für Sekunden verwendet werden. Beispielsweise legt "4d 5h" den Cache-Ablauf auf 4 Tage und 5 Stunden nach der ersten Anforderung der Datei fest. Weitere Informationen finden Sie unter Cache-Ablauf.

<exclude>
Dateien und Verzeichnisse, die mit <exclude>-Mustern übereinstimmen, werden beim Bereitstellen Ihrer Anwendung in App Engine nicht hochgeladen. Diese Dateien und Verzeichnisse sind für Ihre Anwendung aber weiterhin zugänglich, wenn diese auf dem lokalen Entwicklungsserver ausgeführt wird. Weitere Informationen finden Sie unter Dateien ein- und ausschließen.
Beispiel
<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

Optional. Die appengine-web.xml-Datei kann die Systemeigenschaften und Umgebungsvariablen definieren, die beim Ausführen der Anwendung festgelegt werden.

<system-properties>
  <property name="myapp.maximum-message-length" value="140" />
  <property name="myapp.notify-every-n-signups" value="1000" />
  <property name="myapp.notify-url"
            value="http://www.example.com/signupnotify" />
</system-properties>

<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

Optional. Sie können einen HTTP-Connector zur Verbesserung der CPU- und Speicherauslastung konfigurieren.

  <system-properties>
    <property name="appengine.use.httpconnector" value="true"/>
  </system-properties>

Ab Java 21 können Sie Ihren Java-Webserver so konfigurieren, dass er virtuelle Threads verwendet. Beispiel:

  <system-properties>
    <property name="appengine.use.virtualthreads" value="true"/>
  </system-properties>
Weitere Informationen zur Thread-Unterstützung finden Sie unter Jetty 12 – Unterstützung für virtuelle Threads.
<url-stream-handler>

Optional. Mögliche Werte sind native oder urlfetch.

Der Standardwert ist native. Das bedeutet, dass Standard-Java-Netzwerkklassen den standardmäßigen Java HTTP(S)-Transport verwenden. Um diese Einstellung zu verwenden, müssen Sie die Abrechnung für Ihre Anwendung aktivieren. Andernfalls erhalten Sie Ausnahmen, die unter Ausgabe von Anfragen dokumentiert sind.

Wenn Sie url-stream-handler auf urlfetch setzen, verwenden URL.openConnection und die zugehörigen Methoden den URL-Abruf für http- und https-Transporte.

<url-stream-handler>urlfetch</url-stream-handler>
<version>

Das <version>-Element enthält die Versions-ID der aktuellsten Version des Anwendungscodes. Die Versionskennung kann Kleinbuchstaben, Zahlen und Bindestriche enthalten. Sie darf jedoch nicht mit dem Präfix "ah-" beginnen. Außerdem sind die Namen "default" und "latest" reserviert und können daher nicht verwendet werden.

Versionsnamen sollten mit einem Buchstaben beginnen, damit sie sich von numerischen Instanzen unterscheiden, welche immer mit einer Zahl benannt werden. Damit wird das Problem der Mehrdeutigkeit umgangen, das bei URLs wie 123.my-module.uc.r.appspot.com vorliegt. Diese URL kann nämlich auf zwei Arten interpretiert werden: Wenn die Version "123" existiert, ist das Ziel die Version "123" des jeweiligen Moduls. Wenn diese Version nicht existiert, ist das Ziel die Instanz mit der Nummer 123 der Standardversion des Moduls.

<warmup-requests-enabled>

Optional. Standardeinstellung: true. Aufwärmanfragen sind für Java-Anwendungen standardmäßig aktiviert.

Wenn Aufwärmanfragen aktiviert sind, sendet die App Engine-Infrastruktur GET-Anfragen an /_ah/warmup und initialisiert <load-on-startup>-Servlets, ServletContextListeners und benutzerdefinierte Aufwärm-Servlets, mit denen Sie den Code Ihrer Anwendung nach Bedarf initialisieren können. Je nach verwendeter Methode müssen Sie möglicherweise einen eigenen Handler für /_ah/warmup implementieren.

Zum Deaktivieren von Aufwärmanfragen geben Sie für dieses Element den Wert false an:

<warmup-requests-enabled>false</warmup-requests-enabled>
<vpc-access-connector>

Optional. Konfiguriert Ihre Anwendung für die Verwendung eines Connectors für serverlosen VPC-Zugriff, damit sie Anfragen an interne Ressourcen in Ihrem VPC-Netzwerk senden kann. Geben Sie im <name>-Element den vollständig qualifizierten Namen eines Connectors an:

<vpc-access-connector>
  <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>

Weitere Informationen finden Sie unter Verbindung zu einem VPC-Netzwerk herstellen.

Elemente skalieren

In der folgenden Tabelle sind die Optionen aufgeführt, mit denen Sie festlegen können, wie eine Anwendung skaliert werden soll.

Einen Vergleich der Leistungsmerkmale der Skalierungstypen finden Sie unter Dynamische Instanzen skalieren.

Element Beschreibung
<automatic-scaling>

Optional. Die automatische Skalierung gilt standardmäßig mit der Standardinstanzklasse F1, sofern nicht anders angegeben.

Mit dem Element automatic_scaling werden Mindest- und Höchstwerte für die Anzahl der Instanzen, Latenz und gleichzeitigen Verbindungen für ein Modul festgelegt.

Dieses Element kann folgende Elemente enthalten:

<target-cpu-utilization>
Optional. Geben Sie einen Wert zwischen 0,5 und 0,95 an.

Dieser Parameter gibt den Schwellenwert für die CPU-Nutzung an, ab dem neue Instanzen zur Verarbeitung des Traffics gestartet werden. Dadurch erreichen Sie ein ausgeglichenes Kosten-Leistungs-Verhältnis, wobei mit niedrigeren Werten die Leistung und die Kosten erhöht, bei höheren Werten die Leistung verringert, aber auch die Kosten gesenkt werden. Ein Wert von 0,7 bedeutet beispielsweise, dass neue Instanzen gestartet werden, sobald die CPU-Auslastung 70 % erreicht hat.

<target-throughput-utilization>
Optional. Geben Sie einen Wert zwischen 0,5 und 0,95 an.

Wird mit max-concurrent-requests verwendet, um festzulegen, wann eine neue Instanz aufgrund von gleichzeitigen Anfragen gestartet wird. Wenn die Anzahl der gleichzeitigen Anfragen den Wert max-concurrent-requests mal target-throughput-utilization erreicht, startet der Planer eine neue Instanz.

<max-instances>
Optional. Die maximale Anzahl von Instanzen, die für diese Anwendungsversion von App Engine erstellt werden sollen. Diese Beschränkung ist nützlich, um die Kosten eines Moduls zu begrenzen. Geben Sie einen Wert zwischen 0 und 2.147.483.647 an.
<min-instances>
Optional. Die minimale Anzahl von Instanzen, die von App Engine für diese Modulversion erstellt werden sollen. Diese Instanzen stellen Traffic bereit, wenn Anfragen eintreffen, und leiten den Traffic auch dann weiter, wenn zusätzliche Instanzen gestartet werden, die für die Verarbeitung des Traffics erforderlich sind.

Geben Sie einen Wert zwischen 0 und 1.000 an. Sie können den Parameter auf den Wert 0 setzen, um eine Skalierung auf 0 Instanzen zu ermöglichen und die Kosten zu senken, wenn gerade keine Anfragen verarbeitet werden. Ihnen wird die angegebene Anzahl von Instanzen in Rechnung gestellt, unabhängig davon, ob sie Traffic empfangen oder nicht.

<max-concurrent-requests>

Optional. Die Anzahl gleichzeitiger Anfragen, die eine Instanz mit automatischer Skalierung zulassen kann, bevor der Planer eine neue Instanz erzeugt (Standardeinstellung: 10, Höchstwert: 80).

Wenn für diese Einstellung ein zu hoher Wert gewählt wird, kann es zu einer erhöhten API-Latenz kommen. Der Planer erzeugt möglicherweise eine neue Instanz, bevor die maximal zulässige Anzahl an Anfragen erreicht wird.

Hinweis: Wenn instance-class auf F2 oder höher eingestellt ist, können Sie Ihre Instanzen optimieren, indem Sie max-concurrent-requests auf einen höheren Wert als den Standardwert von 10 setzen. Zum Ermitteln des optimalen Werts erhöhen Sie ihn schrittweise und überwachen die Leistung Ihrer Anwendung.

<max-idle-instances>

Die maximale Anzahl inaktiver Instanzen, die App Engine für diese Version beibehalten soll. Der Standardwert ist "automatic". Beachten Sie Folgendes:

  • Ein hoher Höchstwert führt dazu, dass die Anzahl inaktiver Instanzen bei der Rückkehr zum normalen Lastniveau nach einem Lastanstieg langsamer reduziert wird. Dies ermöglicht der Anwendung, bei einem schwankenden Anfrageaufkommen gleichbleibend hohe Leistung zu erbringen. Allerdings erhöhen sich dadurch in Zeiträumen hoher Auslastung auch die Anzahl inaktiver Instanzen und die sich daraus ergebenden laufenden Kosten.
  • Mit einem niedrigen Höchstwert sind die laufenden Kosten niedriger. Schwankende Lastniveaus können dann jedoch zu Leistungseinbußen führen.

Hinweis: Wenn nach einem Lastanstieg wieder das normale Lastniveau erreicht wird, kann die Anzahl inaktiver Instanzen vorübergehend über dem angegebenen Höchstwert liegen. Es werden Ihnen jedoch nicht mehr Instanzen als die von Ihnen angegebene maximale Anzahl berechnet.

<max-pending-latency>

Der Zeitraum, den eine Anfrage maximal in der Warteschlange für ausstehende Anfragen verbleiben kann, bevor App Engine zusätzliche Instanzen zur Verarbeitung von Anfragen startet, um die Latenzzeit für ausstehende Anfragen zu reduzieren.

  • Ein niedriger Maximalwert bedeutet, dass App Engine zum Verarbeiten ausstehender Anfragen schneller neue Instanzen startet. Somit wird zwar die Leistung verbessert, die laufenden Kosten steigen jedoch.
  • Ein hoher Maximalwert bedeutet, dass Nutzer möglicherweise länger auf das Verarbeiten ihrer Anfragen warten müssen, wenn ausstehende Anfragen vorhanden sind, aber keine inaktiven Instanzen, um diese zu verarbeiten. Jedoch kostet das Ausführen Ihrer Anwendung bei dieser Einstellung weniger.
<min-idle-instances>

Die Anzahl der Instanzen, die ausgeführt und zur Verarbeitung von Traffic bereitgehalten werden sollen. Diese Einstellung gilt nur für die Version, die den Großteil des Traffics empfängt. Beachten Sie Folgendes:

  • Ein niedriger Mindestwert ermöglicht Ihnen, die laufenden Kosten bei Inaktivität gering zu halten, sorgt aber möglicherweise auch dafür, dass bei einem plötzlichen Anstieg des Lastniveaus weniger Instanzen unmittelbar verfügbar sind.
  • Ein hoher Mindestwert ermöglicht Ihnen, die Anwendung auf sprunghafte Anstiege des Lastniveaus vorzubereiten. App Engine führt immer die zur Verarbeitung eingehender Anfragen erforderliche Mindestanzahl von Instanzen aus. Die Instanzen werden Ihnen unabhängig davon in Rechnung gestellt, ob diese Anfragen verarbeiten oder nicht. Achten Sie darauf, dass Aufwärmanfragen aktiviert sind und Ihre Anwendung Aufwärmanfragen verarbeitet, damit diese Funktion korrekt funktioniert.

    Wenn Sie eine Mindestanzahl inaktiver Instanzen festlegen, wirkt sich die Latenzzeit der Warteschlange für ausstehende Anfragen weniger stark auf die Leistung der Anwendung aus. Da App Engine inaktive Instanzen in Reserve hält, ist es unwahrscheinlich, dass Anfragen in der Warteschlange landen, außer bei extrem starken Anstiegen des Lastniveaus. Sie müssen Ihre Anwendung in Bezug auf das zu erwartende Traffic-Volumen testen, um die ideale Anzahl von Instanzen zu ermitteln, die in Reserve gehalten werden sollen.

<min-pending-latency>

Die Zeit, die eine Anfrage mindestens in der Warteschlange verbringen muss, bevor App Engine eine neue Instanz zur Verarbeitung startet. Geben Sie einen Wert zwischen 0,01 und 15 an.

  • Ein niedriger Mindestwert bedeutet, dass Anfragen weniger Zeit in der Warteschlange verbringen, wenn alle vorhandenen Instanzen aktiv sind. Das verbessert die Leistung der Anwendung, erhöht aber auch die Ausführungskosten.
  • Ein hoher Mindestwert bedeutet, dass Anfragen mehr Zeit in der Warteschlange verbringen, wenn alle vorhandenen Instanzen aktiv sind. Dadurch sinken die laufenden Kosten, aber die Nutzer müssen länger darauf warten, dass ihre Anfragen verarbeitet werden.
Beispiel
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <instance-class>F2</instance-class>
  <automatic-scaling>
    <target-cpu-utilization>0.65</target-cpu-utilization>
    <min-instances>5</min-instances>
    <max-instances>100</max-instances>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

Optional. Das Element <basic-scaling> bestimmt die Anzahl der Instanzen für ein Modul.

Dieses Element kann folgende Elemente enthalten:

<idle-timeout>
Optional. Gibt an, nach welcher Zeit ab Erhalt der letzten Anfrage die Instanz heruntergefahren wird. Die Standardeinstellung beträgt 5 Minuten.
<max-instances>
Erforderlich. Die maximale Anzahl von Instanzen, die von App Engine für diese Modulversion erstellt werden sollen. Diese Beschränkung ist nützlich, um die Kosten eines Moduls zu begrenzen.
Beispiel
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

Optional. Das Element <manual-scaling> aktiviert die manuelle Skalierung eines Moduls und legt die Anzahl der Modulinstanzen fest.

Dieses Element kann folgende Elemente enthalten:

<instances>
Die Anzahl der Instanzen, die dem Modul am Anfang zugewiesen werden sollen.
Beispiel
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Staging-Elemente

Ein großer Teil der bei einer Bereitstellung anfallenden Arbeit wird in einem Vorbereitungsschritt namens Staging lokal verrichtet. In diesem Schritt werden beispielsweise JAR-Dateien zusammengestellt oder JSP-Dateien kompiliert. Optional können Sie in der Konfigurationsdatei der Anwendung bestimmte Aspekte des Staging-Verhaltens mithilfe von Staging-Elementen konfigurieren. Die meisten Anwendungen können erfolgreich bereitgestellt werden, ohne dass das Staging-Verhalten manuell konfiguriert werden muss. Wenn Ihre Anwendung jedoch nicht bereitgestellt wird, müssen Sie möglicherweise das Staging-Verhalten mithilfe der unten aufgeführten Optionen konfigurieren.

Element Beschreibung
<staging>

Optional. Bei den meisten Anwendungen muss das Standardverhalten nicht geändert werden.

Mit dem Staging-Element können Sie eine bestimmte Staging-Konfiguration angeben, wenn dies für die Bereitstellung erforderlich ist.

Dieses Element kann folgende Elemente enthalten:

<enable-jar-splitting>

Optional. Große JAR-Dateien (> 10 Megabyte) werden in kleinere Fragmente aufgeteilt (Standardeinstellung: true).

<jar-splitting-excludes>

Gibt eine durch Kommas getrennte Liste von Dateisuffixen an. Wenn enable-jar-splitting aktiviert ist, werden alle Dateien, die mit den Suffixen übereinstimmen, aus allen JAR-Dateien ausgeschlossen.

<disable_jar_jsps>

Aus JSP-Dateien generierte Klassen werden nicht in JAR-Dateien gefasst (Standardeinstellung: false).

<enable-jar-classes>

WEB-INF/Klasseninhalte werden in JAR-Dateien gefasst (Standardeinstellung: true).

<delete-jsps>

JSP-Quelldateien werden nach der Kompilierung gelöscht (Standardeinstellung: true).

<compile-encoding>

Codierung von Quelldateien wird für die Kompilierung eingelesen (Standardeinstellung: UTF-8).

Beispiel:

        <staging>
          <delete-jsps>false</delete-jsps>
        </staging>
        

Standardeinstellungen für Staging-Optionen

Die Standardeinstellungen für Staging-Optionen sind davon abhängig, ob Sie Google Cloud SDK-basierte Tools verwenden, wie z. B. die gcloud CLI oder Google Cloud SDK-basierte Maven, Gradle, Eclipse oder IntelliJ-Plug-ins verwenden.

Staging-Element App Engine SDK-basierte Standardeinstellungen Google Cloud SDK-basierte Standardeinstellungen
enable-jar-splitting false true
jar-splitting-excludes
disable-jar-jsps false false
enable-jar-classes false true. Dies kann sich auf die Ladereihenfolge von Klassen auswirken. Wenn Ihre Anwendung eine bestimmte Reihenfolge und somit die vorherige Standardeinstellung false erfordert können Sie diesen Wert auf false setzen.
delete-jsps false true
compile-encoding utf-8 utf-8

Syntax ein- und ausschließen

Pfadmuster werden unter Verwendung von null oder mehr <include>- und <exclude>-Elementen festgelegt. In einem Muster steht '*' für null oder mehr Vorkommnisse eines beliebigen Zeichens in einem Datei- oder Verzeichnisnamen, während ** für null oder mehr Verzeichnisse in einem Pfad steht. Dateien und Verzeichnisse, die mit <exclude>-Mustern übereinstimmen, werden nicht hochgeladen, wenn Sie Ihre Anwendung in App Engine bereitstellen. Diese Dateien und Verzeichnisse sind für Ihre Anwendung aber weiterhin zugänglich, wenn sie auf dem lokalen Entwicklungsserver ausgeführt wird.

Ein <include>-Element setzt das Standardverhalten, bei dem alle Dateien eingeschlossen werden, außer Kraft. Ein <exclude>-Element findet nach allen <include>-Mustern Anwendung (ebenso wie das Standardverhalten, falls kein explizites <include>-Muster angegeben wurde).

Das folgende Beispiel demonstriert, wie alle .png-Dateien als statische Dateien gekennzeichnet werden können (mit Ausnahme der Dateien im data/-Verzeichnis sowie allen vorhandenen Unterverzeichnissen):

<static-files>
  <include path="/**.png" />
  <exclude path="/data/**.png" />
</static-files>

Sie können auch HTTP-Header festlegen, die beim Beantworten von Anfragen an diese statischen Ressourcen verwendet werden sollen.

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>

MIME-Typen für statische Dateien

Statische Dateien werden standardmäßig mithilfe eines MIME-Typs bereitgestellt, der anhand der Dateinamenserweiterung ausgewählt wird. Sie können benutzerdefinierte MIME-Typen mithilfe von mime-mapping-Elementen in web.xml mit Dateinamenerweiterungen für statische Dateien verknüpfen.

URLFetch-Zeitlimit

Sie können für jede URLFetch-Anfrage eine Frist festlegen. Standardmäßig beträgt die Frist für einen Abruf fünf Sekunden. Sie können diese Standardeinstellung ändern und die folgende Einstellung in Ihre Konfigurationsdatei appengine-web.xml einfügen. Geben Sie dabei das Zeitlimit in Sekunden an:

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>