Riferimento appengine-web.xml di App Engine

ID regione

Il REGION_ID è un codice abbreviato che Google assegna in base alla regione selezionata quando crei l'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono sembrare simili ai codici di paesi e province di uso comune. Per le app create dopo febbraio 2020, REGION_ID.r è incluso negli URL App Engine. Per le app esistenti create prima di questa data, l'ID regione è facoltativo nell'URL.

Scopri di più sugli ID regione.

Oltre al descrittore di deployment web.xml, le applicazioni App Engine Java utilizzano un file di configurazione denominato appengine-web.xml per specificare informazioni sulla tua app e per identificare quali file nel file WAR dell'app sono file statici (come le immagini) e quali sono file di risorse utilizzati dall'applicazione.

Esempio

L'esempio seguente è un file minimo che specifica il runtime Java 8 senza file statici o file di risorse:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <threadsafe>true</threadsafe>
  <runtime>java8</runtime>
</appengine-web-app>

Sintassi

Un'app Java App Engine deve avere un file denominato appengine-web.xml nel file WAR, nella directory WEB-INF/. Si tratta di un file XML il cui elemento principale è <appengine-web-app>.

Puoi trovare le specifiche dello schema e la definizione del tipo di documento per appengine-web.xml nella directory docs/ dell'SDK.

Elemento Descrizione
<async-session-persistence>

Facoltativo. È possibile ridurre la latenza delle richieste configurando l'applicazione per scrivere in modo asincrono i dati della sessione HTTP nel datastore: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

Se la persistenza della sessione asincrona è attivata, App Engine invierà un'attività Task Queue per scrivere i dati della sessione nel datastore prima di scriverli nella memcache. Per impostazione predefinita, l'attività verrà inviata alla coda "default". Se vuoi utilizzare una coda diversa, aggiungi l'attributo `queue-name`: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

I dati di sessione vengono sempre scritti in modo sincrono nella memcache. Se una richiesta tenta di leggere i dati della sessione quando memcache non è disponibile (o i dati della sessione sono stati svuotati), viene eseguito il failover su Datastore, che potrebbe non avere ancora i dati della sessione più recenti. Ciò significa che la persistenza asincrona della sessione può causare la visualizzazione di dati di sessione obsoleti da parte dell'applicazione. Tuttavia, per la maggior parte delle applicazioni, il vantaggio della latenza supera di gran lunga il rischio.

<auto-id-policy> Facoltativo. Se imposti automaticamente gli identificatori di entità, puoi modificare il metodo utilizzato impostando il criterio ID automatico. Di seguito sono riportate le opzioni valide:
default
Valore predefinito. Utilizza ID automatici sparsi che sono numeri interi grandi e ben distribuiti abbastanza piccoli da essere rappresentati da numeri in virgola mobile a 64 bit.
legacy
L'opzione legacy verrà ritirata in una release futura e verrà rimossa definitivamente. Per ulteriori informazioni, consulta il post del blog che annuncia questa modifica.
<automatic-scaling>

Facoltativo. Per una spiegazione completa, consulta la sezione Scalabilità automatica.

<basic-scaling>

Facoltativo. Per una spiegazione completa, consulta la sezione Scalabilità di base.

<env-variables>

Facoltativo. Il file appengine-web.xml può definire variabili di ambiente che vengono impostate durante l'esecuzione dell'applicazione. 

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

Per evitare conflitti con l'ambiente locale, il server di sviluppo non imposta le variabili di ambiente in base a questo file e richiede che l'ambiente locale abbia già impostato queste variabili su valori corrispondenti. 

export DEFAULT_ENCODING="UTF-8"
dev_appserver war

Quando viene eseguito il deployment su App Engine, l'ambiente viene creato con queste variabili già impostate.

<inbound-services>

Facoltativo. Prima che un'applicazione possa ricevere email, deve essere configurata per abilitare il servizio. Per abilitare il servizio per un'app Java 8, includi una sezione <inbound-services> nel file appengine-web.xml.

È disponibile il seguente servizio in entrata:

mail
Consente all'applicazione di ricevere posta.
<instance-class>

Facoltativo. La dimensione della classe di istanze per questo modulo.

Quando specifichi diverse opzioni di scalabilità, sono disponibili le seguenti classi di istanze:

automatic_scaling
Quando utilizzi la scalabilità automatica, sono disponibili le classi di istanze F1, F2, F4 e F4_1G.
Predefinito: viene assegnata F1 se non specifichi una classe di istanza insieme all'elemento automatic_scaling.
basic_scaling
Quando utilizzi lo scaling di base, sono disponibili le classi di istanze B1, B2, B4, B4_1G e B8.
Predefinito: viene assegnata la classe B2 se non specifichi una classe di istanza insieme all'elemento basic_scaling.
manual_scaling
Quando utilizzi la scalabilità manuale, sono disponibili le classi di istanza B1, B2, B4, B4_1G e B8.
Predefinito: viene assegnata la classe B2 se non specifichi una classe di istanza insieme all'elemento manual_scaling.

Nota:se instance-class è impostato su F2 o su un valore superiore, puoi ottimizzare le istanze impostando max-concurrent-requests su un valore superiore a 10, che è il valore predefinito. Per trovare il valore ottimale, aumentalo gradualmente e monitora il rendimento della tua applicazione.

<manual-scaling>

Facoltativo. Per una spiegazione completa, consulta la sezione Scalabilità manuale.

<precompilation-enabled>

Facoltativo. App Engine utilizza un processo di "precompilazione" con il bytecode Java di un'app per migliorare il rendimento dell'app nell'ambiente di runtime Java. Il codice precompilato funziona in modo identico al bytecode originale.

Se per qualche motivo preferisci che la tua app non utilizzi la precompilazione, puoi disattivarla aggiungendo quanto segue al file appengine-web.xml: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

Nota : i moduli ora si chiamano Servizi e i servizi vengono ancora dichiarati nei file appengine-web.xml come moduli, ad esempio: <module>service_name</module>.

Obbligatorio se crei un servizio. Facoltativo per il servizio predefinito. Ogni servizio e ogni versione devono avere un nome. Un nome può contenere numeri, lettere e trattini. Non può contenere più di 63 caratteri, non può iniziare o terminare con un trattino e non può contenere la stringa `-dot`. Scegli un nome univoco per ogni servizio e ogni versione. Non riutilizzare i nomi tra servizi e versioni.

Vedi anche servizio.

<public-root>

Facoltativo. <public-root> è una directory della tua applicazione che contiene i file statici per la tua applicazione. Quando viene effettuata una richiesta per un file statico, il <public-root> per la tua applicazione viene anteposto al percorso della richiesta. Indica il percorso di un file dell'applicazione contenente i contenuti richiesti.

Il valore predefinito <public-root> è /.

Ad esempio, il seguente codice mapperà il percorso dell'URL /index.html al percorso del file dell'applicazione /static/index.html: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<resource-files>

Facoltativo. I file elencati nell'elemento <resource-files> sono accessibili dal codice dell'applicazione utilizzando il file system. Questi file vengono archiviati sui server delle applicazioni con l'app, a differenza di come vengono archiviati e pubblicati i file statici.

L'elemento <resource-files> può contenere i seguenti elementi:

<include>
Un elemento <include> designa i file come file di risorse e disponibili per il codice dell'applicazione. Questi file sono disponibili per il tuo codice solo in modalità di sola lettura e non per la pubblicazione del traffico. Includere ed escludere file.
<exclude>

I file e le directory che corrispondono ai pattern <exclude> non verranno caricati né saranno disponibili per il codice dell'applicazione. Tuttavia, questi file e directory saranno comunque accessibili alla tua applicazione quando viene eseguita sul server di sviluppo locale. Per ulteriori informazioni, vedi Inclusione ed esclusione di file.

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

Questo esempio mostra come designare tutti i file .xml come file di risorse, ad eccezione di quelli nella directory feeds/ e in tutte le relative sottodirectory.

I file di risorse di App Engine vengono letti utilizzando java.io.File o javax.servlet.ServletContext.getResource/getResourceAsStream. Non sono accessibili tramite Class.getResourceAsStream().

runtime

Per utilizzare l'ambiente di runtime Java 8, devi specificare questa voce con il valore java8.

Esempio: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

I servizi erano precedentemente noti come moduli.

Al momento, la definizione di un servizio come: <service>service_name</service > è supportata solo dai comandi gcloud app.
service-account

Facoltativo. L'elemento service-account consente di specificare un service account gestito dall'utente come identità per la versione. Il account di servizio specificato verrà utilizzato per accedere ad altri servizi Google Cloud ed eseguire attività.

Esempio: 
<?xml version="1.0" encoding="utf-8"?>
 <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
   <!-- ... -->
   <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account>
   <!-- ... -->
 </appengine-web-app>
<sessions-enabled>

Facoltativo. App Engine include un'implementazione delle sessioni, utilizzando l'interfaccia di sessione servlet. L'implementazione archivia i dati di sessione in Datastore per la persistenza e utilizza anche memcache per la velocità. Come per la maggior parte degli altri servlet container, gli attributi di sessione impostati con `session.setAttribute()` durante la richiesta vengono mantenuti alla fine della richiesta.

Questa funzionalità è disattivata per impostazione predefinita. Per attivarlo, aggiungi quanto segue a appengine-web.xml:

Esempio: 
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

L'implementazione crea entità Datastore di tipo _ah_SESSION e voci memcache utilizzando chiavi con un prefisso di _ahs. Puoi eliminare queste entità utilizzando il modello Dataflow.

Nota: poiché App Engine archivia i dati di sessione in Datastore e memcache, tutti i valori archiviati nella sessione devono implementare l'interfaccia java.io.Serializable.

Consulta l'elemento async-session-persistence per ridurre la latenza dell'archiviazione dei dati di sessione.

<ssl-enabled>

Facoltativo. Per impostazione predefinita, qualsiasi utente può accedere a qualsiasi URL utilizzando HTTP o HTTPS. Puoi configurare un'app in modo che richieda HTTPS per determinati URL nel descrittore di deployment. Consulta la sezione Descrittore del deployment: URL sicuri.

Se vuoi disattivare l'utilizzo di HTTPS per l'applicazione, inserisci quanto segue nel file appengine-web.xml: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

Non è possibile disattivare HTTPS per alcuni percorsi URL e non per altri nell'ambiente di runtime Java.

<static-error-handlers>

Facoltativo. Quando si verificano determinati errori, App Engine mostra una pagina di errore generica. Puoi configurare la tua app in modo che fornisca un file statico personalizzato anziché queste pagine di errore generiche, a condizione che i dati di errore personalizzati siano inferiori a 10 kilobyte. Puoi configurare diversi file statici da pubblicare per ogni codice di errore supportato specificando i file nel file appengine-web.xml della tua app. Per pubblicare pagine di errore personalizzate, aggiungi una sezione <static-error-handlers> al tuo appengine-web.xml, come in questo esempio: 

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

Avviso: assicurati che il percorso del file di risposta agli errori non si sovrapponga ai percorsi del gestore di file statici.

Ogni voce file indica un file statico che deve essere mostrato al posto della risposta di errore generica. Il error-code indica quale codice di errore deve causare la pubblicazione del file associato. I codici di errore supportati sono i seguenti:

over_quota
Indica che l'app ha superato una quota di risorse.
timeout
Viene pubblicato se viene raggiunta una scadenza prima che la tua app risponda.

error-code è facoltativo; se non viene specificato, il file fornito è la risposta di errore predefinita per la tua app.

Se vuoi, puoi specificare un mime-type da utilizzare quando viene visualizzato l'errore personalizzato. Consulta l'elenco completo dei tipi MIME.

<static-files>

Facoltativo. L'elemento <static-files> specifica i pattern che corrispondono ai percorsi dei file da includere ed escludere dall'elenco dei file statici, eseguendo l'override o la modifica del comportamento predefinito. I file statici vengono pubblicati da server e cache dedicati separati dai server delle applicazioni e sono utili per pubblicare contenuti statici come immagini, fogli di stile CSS o file JavaScript.

L'elemento <static-files> può contenere i seguenti elementi:

<include>

Un elemento <include> sostituisce il comportamento predefinito di inclusione di tutti i file non JSP. L'elemento <include> può specificare le intestazioni HTTP da utilizzare quando si risponde alla richiesta delle risorse specificate. Per ulteriori informazioni, vedi Inclusione ed esclusione dei file.

Puoi ignorare la scadenza predefinita della cache statica specificando l'attributo expiration nell'elemento include. Il valore è una stringa di numeri e unità, separati da spazi, in cui le unità possono essere d per i giorni, h per le ore, m per i minuti e s per i secondi. Ad esempio, "4d 5h" imposta la scadenza della cache a 4 giorni e 5 ore dopo la prima richiesta del file. Per saperne di più, vedi Scadenza della cache.

<exclude>
I file e le directory che corrispondono ai pattern <exclude> non verranno caricati quando esegui il deployment dell'app in App Engine. Tuttavia, questi file e directory saranno comunque accessibili alla tua applicazione quando viene eseguita sul server di sviluppo locale. Per ulteriori informazioni, vedi Inclusione ed esclusione dei file.
Esempio 
<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

Facoltativo. Il file appengine-web.xml può definire le proprietà di sistema e le variabili di ambiente impostate durante l'esecuzione dell'applicazione. 

<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>
<threadsafe>

Obbligatorio. Quando l'elemento threadsafe in appengine-web.xml è false, App Engine invia le richieste in serie a un determinato server web. Quando il valore è true, App Engine può inviare più richieste in parallelo: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

Se vuoi utilizzare le richieste simultanee, il codice dell'applicazione deve utilizzare la sincronizzazione corretta dei thread prima di attivare threadsafe.

Questo elemento non è supportato nei runtime Java 11+.

<url-stream-handler>

Facoltativo. I valori possibili sono native o urlfetch.

Il valore predefinito è native, il che significa che le classi di rete Java standard utilizzano il trasporto HTTP(S) Java standard. Per utilizzare questa impostazione, devi attivare la fatturazione per la tua app, altrimenti riceverai eccezioni, documentate in Richieste di problemi.

Se imposti url-stream-handler su urlfetch, URL.openConnection e i metodi correlati utilizzeranno il recupero URL per il trasporto http e https.

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

L'elemento <version> contiene l'identificatore della versione più recente del codice dell'app. L'identificatore della versione può contenere lettere minuscole, cifre e trattini. Non può iniziare con il prefisso "ah-" e i nomi "default" e "latest" sono riservati e non possono essere utilizzati.

I nomi delle versioni devono iniziare con una lettera per distinguerli dalle istanze numeriche, che sono sempre specificate da un numero. In questo modo si evita l'ambiguità con URL come 123.my-module.uc.r.appspot.com, che possono essere interpretati in due modi: se esiste la versione "123", la destinazione sarà la versione "123" del modulo specificato. Se questa versione non esiste, la destinazione sarà l'istanza numero 123 della versione predefinita del modulo.

App Engine utilizza questo identificatore di versione per determinare se creare una nuova versione dell'app con l'identificatore specificato (o sostituire la versione dell'app con l'identificatore specificato se ne esiste già una). Puoi testare nuove versioni della tua app con un URL utilizzando "-dot-" come separatore di sottodomini nell'URL, ad esempio, https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com. Utilizzando Google Cloud console, puoi selezionare la versione predefinita della tua app. La versione predefinita viene caricata quando non viene specificata alcuna versione o una versione non valida.

<warmup-requests-enabled>

Facoltativo. Valore predefinito: true. Le richieste di warmup sono abilitate per impostazione predefinita per le applicazioni Java 8.

Con le richieste di preriscaldamento attive, l'infrastruttura di App Engine invia richieste `GET` a /_ah/warmup, inizializzando servlet <load-on-startup>, ServletContextListeners e servlet di preriscaldamento personalizzati, che ti consentono di inizializzare il codice dell'applicazione come richiesto. Potresti dover implementare un tuo gestore per /_ah/warmup a seconda del metodo che scegli.

Per disattivare le richieste di warmup, specifica false per questo elemento: 

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>
<vpc-access-connector>

Facoltativo. Configura l'applicazione in modo che utilizzi un connettore di accesso VPC serverless, consentendole di inviare richieste alle risorse interne nella tua rete VPC. Per saperne di più, consulta Connessione a una rete VPC.

name
Specifica il nome completo del connettore di accesso VPC serverless: 
projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME
egress-setting
Facoltativo. Il valore predefinito è private-ranges-only. Il egress-setting può essere uno dei seguenti:
private-ranges-only
Predefinito. Le richieste agli indirizzi IP interni vengono inviate tramite il connettore di accesso VPC serverless alla rete VPC connessa. Le richieste agli indirizzi IP esterni vengono inviate a internet pubblico.
all-traffic
Tutte le richieste vengono inviate tramite il connettore di accesso VPC serverless alla rete VPC connessa.
Esempio 
<vpc-access-connector>
  <name>projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME</name>
  <egress-setting>all-traffic</egress-setting>
</vpc-access-connector>

Elementi di scalabilità

La tabella seguente elenca le opzioni per definire come specificare che la tua applicazione deve essere scalata.

Per un confronto delle funzionalità di rendimento dei tipi di scalabilità, vedi Scalabilità delle istanze dinamiche.

Elemento Descrizione
<automatic-scaling>

Facoltativo. La scalabilità automatica viene presupposta per impostazione predefinita con una classe di istanza predefinita di F1, a meno che non sia specificato diversamente.

L'elemento automatic_scaling imposta i livelli minimo e massimo per il numero di istanze, la latenza e le connessioni simultanee per un modulo.

Questo elemento può contenere i seguenti elementi:

<target-cpu-utilization>
(Facoltativo) Specifica un valore compreso tra 0,5 e 0,95.

Questo parametro specifica la soglia di utilizzo della CPU in corrispondenza della quale verranno avviate nuove istanze per gestire il traffico, consentendoti di trovare un equilibrio tra rendimento e costi. I valori più bassi aumentano il rendimento e i costi, mentre i valori più alti riducono il rendimento ma anche i costi. Ad esempio, un valore di 0,7 significa che le nuove istanze verranno avviate dopo che l'utilizzo della CPU raggiunge il 70%.

<target-throughput-utilization>
(Facoltativo) Specifica un valore compreso tra 0,5 e 0,95.

Utilizzato con max-concurrent-requests per specificare quando viene avviata una nuova istanza a causa di richieste simultanee. Quando il numero di richieste simultanee raggiunge un valore pari a max-concurrent-requests volte target-throughput-utilization, lo scheduler avvia una nuova istanza.

<max-instances>
(Facoltativo) Il numero massimo di istanze che App Engine deve creare per questa versione dell'applicazione. Ciò è utile per limitare i costi di un modulo. Specifica un valore compreso tra 0 e 2147483647.
<min-instances>
(Facoltativo) Il numero minimo di istanze che App Engine deve creare per questa versione del modulo. Queste istanze gestiscono il traffico quando arrivano le richieste e continuano a farlo anche quando vengono avviate istanze aggiuntive in base alle esigenze di gestione del traffico.

Specifica un valore compreso tra 0 e 1000. Puoi impostare il parametro sul valore 0 per consentire lo scale-out a 0 istanze per ridurre i costi quando non vengono gestite richieste. Tieni presente che ti viene addebitato un costo per il numero di istanze specificato, indipendentemente dal fatto che ricevano traffico o meno.

<max-concurrent-requests>

Facoltativo. Il numero di richieste simultanee che un'istanza di scalabilità automatica può accettare prima che lo scheduler generi una nuova istanza (valore predefinito: 10, valore massimo: 80).

Potresti riscontrare una maggiore latenza dell'API se questa impostazione è troppo alta. Tieni presente che lo scheduler potrebbe generare una nuova istanza prima che venga raggiunto il numero massimo effettivo di richieste.

Nota:se instance-class è impostato su F2 o su un valore superiore, puoi ottimizzare le istanze impostando max-concurrent-requests su un valore superiore a 10, che è il valore predefinito. Per trovare il valore ottimale, aumentalo gradualmente e monitora il rendimento della tua applicazione.

<max-idle-instances>

Il numero massimo di istanze inattive che App Engine deve mantenere per questa versione. Il valore predefinito è "automatico". Tieni presente che:

  • Un valore massimo elevato riduce il numero di istanze inattive in modo più graduale quando i livelli di carico tornano alla normalità dopo un picco. Ciò aiuta l'applicazione a mantenere prestazioni stabili durante le fluttuazioni del carico di richieste, ma aumenta anche il numero di istanze inattive (e i conseguenti costi di esecuzione) durante questi periodi di carico elevato.
  • Un valore massimo basso mantiene i costi di gestione più bassi, ma può peggiorare le prestazioni in caso di livelli di carico volatili.

Nota:quando si torna ai livelli normali dopo un picco di carico, il numero di istanze inattive può superare temporaneamente il massimo specificato. Tuttavia, non ti verranno addebitati costi per un numero di istanze superiore a quello massimo specificato.

<max-pending-latency>

Il tempo massimo che App Engine deve consentire a una richiesta di attendere nella coda in attesa prima di avviare istanze aggiuntive per gestire le richieste in modo da ridurre latenza in sospeso.

  • Un valore massimo basso significa che App Engine avvierà nuove istanze prima per le richieste in attesa, migliorando le prestazioni ma aumentando i costi di esecuzione.
  • Un valore massimo elevato significa che gli utenti potrebbero attendere più a lungo l'elaborazione delle loro richieste se ci sono richieste in attesa e nessuna istanza inattiva per gestirle, ma l'esecuzione dell'applicazione costerà meno.
<min-idle-instances>

Il numero di istanze da mantenere in esecuzione e pronte a gestire il traffico.Questa impostazione si applica solo alla versione che riceve la maggior parte del traffico. Tieni presente quanto segue:

  • Un valore minimo basso contribuisce a ridurre i costi di gestione durante i periodi di inattività, ma significa che potrebbero essere disponibili meno istanze per rispondere a un improvviso picco di carico.

  • Un valore minimo elevato consente di preparare l'applicazione per picchi rapidi nel carico di richieste. App Engine mantiene in esecuzione il numero minimo di istanze per gestire le richieste in entrata. Ti vengono addebitati i costi per le istanze, indipendentemente dal fatto che gestiscano o meno le richieste. Per il corretto funzionamento di questa funzionalità, devi assicurarti che le richieste di preavvio siano attive e che la tua applicazione le gestisca.

    Se imposti un numero minimo di istanze inattive, latenza in sospeso avrà un impatto minore sul rendimento della tua applicazione. Poiché App Engine mantiene le istanze inattive in riserva, è improbabile che le richieste entrino nella coda in attesa, tranne in picchi di carico eccezionalmente elevati. Dovrai testare la tua applicazione e il volume di traffico previsto per determinare il numero ideale di istanze da tenere di riserva.

<min-pending-latency>

Il tempo minimo in secondi che App Engine deve consentire a una richiesta di attendere nella coda in attesa prima di avviare una nuova istanza per gestirla. Specifica un valore compreso tra 0,01 e 15.

  • Un valore minimo basso significa che le richieste devono trascorrere meno tempo nella coda in attesa quando tutte le istanze esistenti sono attive. In questo modo, le prestazioni migliorano, ma aumentano i costi di esecuzione dell'applicazione.
  • Un valore minimo elevato significa che le richieste rimarranno in attesa più a lungo se tutte le istanze esistenti sono attive. In questo modo i costi di esecuzione vengono ridotti, ma aumenta il tempo di attesa degli utenti per la gestione delle richieste.
Esempio 
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <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>

Facoltativo. L'elemento <basic-scaling> imposta il numero di istanze per un modulo.

Questo elemento può contenere i seguenti elementi:

<idle-timeout>
(Facoltativo) L'istanza verrà arrestata dopo questo periodo di tempo dalla ricezione dell'ultima richiesta. Il valore predefinito è 5 minuti.
<max-instances>
Obbligatorio. Il numero massimo di istanze che App Engine deve creare per questa versione del modulo. Ciò è utile per limitare i costi di un modulo.
Esempio 
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

Facoltativo. L'elemento <manual-scaling> consente la scalabilità manuale per un modulo e imposta il numero di istanze per un modulo.

Questo elemento può contenere i seguenti elementi:

<instances>
Il numero di istanze da assegnare al modulo all'inizio.
Esempio 
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Elementi di gestione temporanea

Gran parte del lavoro svolto durante un deployment avviene localmente in un passaggio di preparazione chiamato staging, in cui vengono assemblati i file JAR, compilati i JSP e così via. Puoi configurare facoltativamente alcune parti del comportamento di staging utilizzando gli elementi di staging nel file di configurazione dell'applicazione. La maggior parte delle applicazioni verrà eseguita correttamente senza configurare manualmente il comportamento di staging. Se la tua app non viene implementata, potrebbe essere necessario configurare lo staging utilizzando le opzioni mostrate di seguito.

Elemento Descrizione
<staging>

Facoltativo. La maggior parte delle applicazioni non deve modificare il comportamento predefinito.

L'elemento di gestione temporanea ti consente di specificare una particolare configurazione di gestione temporanea, se necessaria per il deployment.

Questo elemento può contenere i seguenti elementi:

<enable-jar-splitting>

Facoltativo. Dividi i file JAR di grandi dimensioni (> 10 megabyte) in frammenti più piccoli. (Valore predefinito: true).

<jar-splitting-excludes>

Specifica un elenco di suffissi di file separati da virgole. Se enable-jar-splitting è abilitato, tutti i file che corrispondono ai suffissi verranno esclusi da tutti i file JAR.

<disable_jar_jsps>

Non creare file JAR per le classi generate dai file JSP. (valore predefinito: false).

<enable-jar-classes>

Crea un file JAR con i contenuti di WEB-INF/classes. (valore predefinito: false).

<delete-jsps>

Elimina i file di origine JSP dopo la compilazione. (Valore predefinito: true).

<compile-encoding>

Codifica di input dei file di origine per la compilazione. (valore predefinito: utf-8).

Ad esempio:

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

Valori predefiniti dell'opzione di staging

I valori predefiniti per le opzioni di staging sono i seguenti:

Elemento temporaneo Valore predefinito
enable-jar-splitting true
jar-splitting-excludes ND
disable-jar-jsps false
enable-jar-classes true. Ciò può influire sull'ordine di caricamento delle classi, quindi se la tua app dipende da un determinato ordine, imposta questo valore su false.
delete-jsps true
compile-encoding utf-8

Sintassi di inclusione ed esclusione

I pattern di percorso vengono specificati utilizzando zero o più elementi <include> e <exclude>. In un pattern, '*' rappresenta zero o più caratteri in un nome di file o directory, mentre ** rappresenta zero o più directory in un percorso. I file e le directory che corrispondono ai pattern <exclude> non verranno caricati quando esegui il deployment dell'app in App Engine. Tuttavia, questi file e directory saranno comunque accessibili alla tua applicazione quando viene eseguita sul server di sviluppo locale.

Un elemento <include> esegue l'override del comportamento predefinito di inclusione di tutti i file. Un elemento <exclude> viene applicato dopo tutti i pattern <include> (nonché quello predefinito se non viene fornito alcun <include> esplicito).

L'esempio seguente mostra come designare tutti i file .png come file statici (ad eccezione di quelli nella directory data/ e in tutte le relative sottodirectory):

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

Puoi anche impostare le intestazioni HTTP da utilizzare quando rispondi alle richieste di queste risorse statiche.

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

Tipi MIME per i file statici

Per impostazione predefinita, i file statici vengono pubblicati utilizzando un tipo MIME selezionato in base all'estensione del nome file. Puoi associare tipi MIME personalizzati a estensioni dei nomi file per i file statici utilizzando gli elementi <mime-mapping> in web.xml.

Timeout di URLFetch

Puoi impostare una scadenza per ogni richiesta URLFetch. Per impostazione predefinita, la scadenza per un recupero è di 5 secondi. Puoi modificare questa impostazione predefinita includendo la seguente impostazione nel file di configurazione appengine-web.xml. Specifica il timeout in secondi:

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