Avviso: nei prossimi mesi stiamo riorganizzando il sito della documentazione di App Engine per semplificare la ricerca di contenuti e l'allineamento con il resto dei prodotti Google Cloud. Gli stessi contenuti saranno disponibili, ma la navigazione ora corrisponderà al resto dei prodotti Cloud.
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
ID regione
REGION_ID è un codice abbreviato assegnato da Google in base all'area geografica selezionata quando crei l'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID area geografica potrebbero sembrare simili ai codici paese e provincia più utilizzati. Per le app create dopo febbraio 2020, REGION_ID.r è incluso negli URL di App Engine. Per le app esistenti create prima di questa data, l'ID regione è facoltativo nell'URL.
Ogni servizio nell'app ha il proprio file app.yaml, che funge da descrittore per il deployment. Prima di creare e implementare i file app.yaml per i servizi aggiuntivi nella tua app, devi creare il file app.yaml per il servizio default.
Di seguito è riportato un esempio di file app.yaml per un'applicazione PHP 7+:
runtime: php81 # Replace with php74 to use PHP 7.4
handlers:
# Serve a directory as a static resource.
- url: /stylesheets
static_dir: stylesheets
# Serve images as static resources.
- url: /(.+\.(gif|png|jpg))$
static_files: \1
upload: .+\.(gif|png|jpg)$
# Serve your app through a front controller at index.php or public/index.php.
- url: .*
script: auto
In questo esempio, App Engine gestisce i file con estensione gif, png o jpg come risorse statiche. Il codice dell'applicazione legge i file configurati
in fase di esecuzione.
Il formato YAML supporta i commenti. Una riga che inizia con un cancelletto (#)
viene ignorata:
# This is a comment.
I pattern URL e dei percorsi file utilizzano la sintassi delle espressioni regolari estese POSIX, esclusi gli elementi di confronto e le classi di confronto. Sono supportati i riferimenti arretrati alle corrispondenze raggruppate (ad esempio \1),
come le seguenti estensioni Perl: \w \W \s \S \d \D.
(Facoltativo) Imposta un periodo di cache predefinito globale per tutti i gestori di file statici per un'applicazione. Puoi anche configurare una durata della cache per gestori di file statici specifici. Il valore è una stringa di numeri e unità separate da spazi, dove le unità possono essere did 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 su 4 giorni e 5 ore dopo la prima richiesta del file. Se omesso, il server di produzione imposta la scadenza su 10 minuti.
Esempio:
runtime: php81 # Replace with php74 to use PHP 7.4
default_expiration: "4d 5h"
handlers:
# ...
(Facoltativo)
Esegue l'override del comportamento di avvio predefinito eseguendo il comando entrypoint all'avvio della tua app. Per fare in modo che l'app riceva le richieste HTTP, l'elemento entrypoint deve contenere un comando che avvia un server web in ascolto sulla porta 8080.
Se non specifichi un
entrypoint, App Engine
pubblicherà la tua applicazione tramite un controller anteriore in un
file public/index.php o index.php.
env_variables
(Facoltativo)
Puoi definire le variabili di ambiente nel file app.yaml per renderle disponibili per la tua app.
Le variabili di ambiente che hanno il prefisso GAE sono riservate per l'utilizzo dal sistema e non consentite nel file app.yaml.
Esempio:
env_variables:
MY_VAR: "my value"
dove MY_VAR e my value sono il nome e
il valore della variabile di ambiente che vuoi definire e ogni voce di variabile
di ambiente rientra entro due spazi sotto l'elemento
env_variables. Per le variabili di ambiente non è stato assegnato
un valore predefinito a "None".
Puoi quindi recuperare il valore di queste variabili utilizzando
getenv() o $_SERVER, ma
non$_ENV. I seguenti
comandi richiamano il valore della variabile di ambiente
MY_VAR:
Pubblicata se viene raggiunta una scadenza prima che ci sia una risposta dalla tua
app.
Il file error_code è facoltativo; se non è specificato, il file specificato è la risposta di errore predefinita per la tua app.
file
Ogni voce di file indica un file statico che deve essere pubblicato al posto della risposta di errore generica. Se specifichi un elemento file senza un elemento error_code corrispondente, il file statico sarà la pagina di errore predefinita per la tua app.
I dati di errore personalizzati devono essere inferiori a 10 kilobyte.
(Facoltativo)
Un elenco di pattern URL e descrizioni di come devono essere gestiti.
App Engine può gestire gli URL eseguendo il codice dell'applicazione o pubblicando file statici caricati con il codice, ad esempio immagini, CSS o JavaScript.
Se hai definito un handlers statico, devi anche definire un gestore per tutto il traffico dell'applicazione, per instradarlo a una entrypoint.
Per eseguire il routing a un elemento entrypoint, specifica il percorso del controller anteriore con l'elemento entrypoint oppure utilizza l'elemento script se l'app contiene un file public/index.php o index.php.
(Facoltativo)
Le applicazioni devono abilitare questi servizi prima di poter ricevere richieste in entrata. Puoi abilitare il servizio per un'app PHP 7+
includendo una sezione inbound_services nel
file app.yaml.
I seguenti valori sono disponibili a seconda della scalabilità del servizio:
Scalabilità automatica
F1, F2, F4, F4_1G
Predefinito:F1
Facoltativamente, utilizza l'elemento automatic_scaling per modificare le impostazioni
predefinite per la scalabilità automatica, ad esempio il numero minimo e massimo
di istanze, latenza e connessioni simultanee.
Nota: se instance_class
è impostato su F2 o su un valore superiore, puoi ottimizzare le tue istanze
impostando max_concurrent_requests su un valore superiore
al valore predefinito di 10. Per determinare il valore ottimale, aumentalo gradualmente e monitora le prestazioni dell'applicazione.
Scalabilità di base e manuale
B1, B2, B4, B4_1G, B8
Predefinito:B2
Le classi di istanza di base e manuali richiedono di specificare
l'elemento basic_scaling o l'elemento manual_scaling.
runtime
Obbligatorio. Il nome dell'ambiente di runtime utilizzato dalla tua
app. Ad esempio, per specificare PHP 8.1, utilizza:
runtime: php81
service
Obbligatorio se stai creando un
servizio.
Facoltativo per il servizio default. Ogni servizio e ogni versione deve avere un nome. Un nome può contenere numeri, lettere e trattini. La lunghezza combinata di VERSION-dot-SERVICE-dot-PROJECT_ID, dove VERSION è il nome della versione, SERVICE è il nome del servizio e PROJECT_ID è l'ID progetto. Non può contenere più di 63 caratteri e non può iniziare o terminare con un trattino. Scegli un nome univoco per ogni servizio e ogni versione. Non riutilizzare i nomi tra i servizi e le versioni.
Esempio:
service: service-name
service_account
(Facoltativo) L'elemento service_account consente di specificare un
account di servizio gestito dall'utente come identità per la versione. L'account di servizio specificato verrà utilizzato per accedere ad altri servizi di Google Cloud ed eseguire le attività.
(Facoltativo)
Configura la tua applicazione in modo che utilizzi un connettore di accesso VPC serverless, consentendo all'applicazione di inviare richieste alle risorse interne nella rete VPC. Per maggiori informazioni, consulta la sezione
Connessione a una rete VPC.
name
Il valore letterale della stringa. Specifica il nome completo del connettore di accesso VPC serverless tra virgolette:
Facoltativo. Il valore predefinito è private-ranges-only. 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 a indirizzi IP esterni vengono inviate alla rete Internet pubblica.
all-traffic
Tutte le richieste vengono inviate tramite il connettore di accesso VPC serverless alla rete VPC connessa.
L'elemento handlers fornisce un elenco di pattern URL e descrizioni di come devono essere gestiti. App Engine può gestire gli URL eseguendo il codice dell'applicazione o pubblicando file statici caricati con il codice, ad esempio immagini, CSS o JavaScript.
I pattern vengono valutati nell'ordine in cui sono visualizzati nel file app.yaml, dall'alto verso il basso. La prima mappatura il cui pattern corrisponde all'URL è quella utilizzata per gestire la richiesta.
Nella tabella riportata di seguito sono elencati gli elementi secondari dell'elemento handlers che controllano il comportamento di script, file statici, directory statiche e altre impostazioni.
Elemento
Descrizione
expiration
(Facoltativo)
Il periodo di tempo in cui un file statico pubblicato da questo gestore deve essere memorizzato
nella cache da proxy web e browser. Il valore è una stringa di numeri e unità separate da spazi, dove 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 su 4 giorni e 5 ore dopo
la prima richiesta del file. Se omesso, viene utilizzato l'applicazione default_expiration. Per ulteriori dettagli, consulta Scadenza della cache.
http_headers
(Facoltativo) Puoi impostare intestazioni HTTP per le risposte dei gestori di file statici o di directory. Se devi impostare intestazioni HTTP
nei gestori script, devi farlo nel codice
dell'app. Per informazioni su quali intestazioni della risposta influenzano la memorizzazione nella cache, consulta Memorizzazione nella cache dei contenuti statici.
Esempio
handlers:
- url: /images
static_dir: static/images
http_headers:
X-Foo-Header: foo
X-Bar-Header: bar value
vary: Accept-Encoding
# ...
Supporto CORS
Un utilizzo importante di questa funzionalità è il supporto del sistema CORS (Cross-Origin Resource Sharing), ad esempio l'accesso ai file ospitati da un'altra app di App Engine.
Ad esempio, potresti avere un'app di gioco mygame.uc.r.appspot.com che accede agli asset ospitati da myassets.uc.r.appspot.com.
Tuttavia, se mygame tenta di eseguire un codice JavaScript
XMLHttpRequest in myassets, avrà esito
negativo a meno che il gestore per myassets non
restituisca un'intestazione della risposta Access-Control-Allow-Origin: contenente il valore http://mygame.uc.r.appspot.com.
Ecco come fare in modo che il gestore di file statici restituisca il valore dell'intestazione di risposta richiesta:
Nota: se vuoi consentire a tutti di accedere alle tue risorse, puoi utilizzare il carattere jolly '*' invece di https://mygame.uc.r.appspot.com.
mime_type
(Facoltativo) Se specificato, tutti i file gestiti da questo gestore verranno
pubblicati utilizzando il tipo MIME specificato. Se non specificato, il tipo MIME di un file verrà derivato dall'estensione del nome file.
Se lo stesso file viene caricato con più estensioni, l'estensione risultante può dipendere dall'ordine in cui si sono verificati i caricamenti.
(Facoltativo) redirect_http_response_code viene utilizzato con l'impostazione secure per impostare il codice di risposta HTTP restituito durante l'esecuzione di un reindirizzamento richiesto in base alla configurazione dell'impostazione secure.
L'elemento redirect_http_response_code ha i seguenti
valori possibili:
301
Codice di risposta spostato definitivamente.
302
Codice di risposta trovato.
303
Vedi Altro codice di risposta.
307
Codice di risposta di reindirizzamento temporaneo.
Esempio
handlers:
- url: /youraccount/.*
script: auto
secure: always
redirect_http_response_code: 301
Quando la richiesta di un utente viene reindirizzata, il codice di stato HTTP viene impostato sul valore del parametro redirect_http_response_code. Se il parametro non è presente, verrà restituito 302.
script
(Facoltativo)
Specifica che le richieste al gestore specifico devono scegliere come target la tua app. L'unico valore accettato per l'elemento script è auto perché tutto il traffico viene pubblicato utilizzando il comando itempoint. Per utilizzare i gestori statici, almeno uno dei gestori deve contenere la riga script: auto o definire un elemento entrypoint per il deployment.
(Facoltativo) Qualsiasi gestore di URL può utilizzare l'impostazione secure, inclusi i gestori di script e di file statici. L'elemento secure ha i seguenti
valori possibili:
optional
Le richieste HTTP e HTTPS con gli URL che corrispondono al gestore
hanno esito positivo senza reindirizzamenti. L'applicazione può esaminare la richiesta per determinare quale protocollo è stato utilizzato e rispondere di conseguenza. Questa è l'impostazione predefinita quando secure non viene fornito per un gestore.
never
Le richieste di URL che corrispondono a questo gestore che utilizzano HTTPS vengono automaticamente reindirizzate all'URL equivalente HTTP. Quando la richiesta HTTPS di un utente
viene reindirizzata a una richiesta HTTP,
i parametri di ricerca vengono rimossi dalla richiesta. Questo impedisce a un utente di inviare accidentalmente dati di query su una connessione non sicura destinata a una connessione sicura.
always
Le richieste di URL che corrispondono a questo gestore che non utilizzano HTTPS vengono
automaticamente reindirizzate all'URL HTTPS con lo stesso percorso. I parametri di ricerca vengono conservati per il reindirizzamento.
Esempio
handlers:
- url: /youraccount/.*
script: auto
secure: always
L'accesso e la disconnessione degli Account Google vengono sempre eseguiti utilizzando una connessione sicura, non correlata alla configurazione degli URL dell'applicazione.
static_dir
(Facoltativo) Il percorso della directory contenente i file statici, dalla
directory radice dell'applicazione. Tutto ciò che segue la fine del pattern url corrispondente viene aggiunto al criterio static_dir per formare il percorso completo del file richiesto.
Ogni file nella directory statica viene pubblicato utilizzando il tipo MIME che corrisponde all'estensione del nome file, a meno che non venga sostituito dall'impostazione mime_type della directory. Tutti i file della directory specificata vengono caricati come file statici e non possono essere eseguiti come script.
Esempio:
handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
static_dir: stylesheets
# ...
static_files
(Facoltativo) Un gestore di pattern statici consente di associare un pattern URL ai percorsi dei file statici caricati con l'applicazione. L'espressione regolare del pattern URL può definire raggruppamenti delle espressioni regolari da utilizzare nella creazione del percorso del file. Puoi utilizzarlo al posto di static_dir per mappare file specifici in una struttura di directory senza mappare l'intera directory.
Esempio:
handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
static_files: static/\1
upload: static/.*\.(gif|png|jpg)$
# ...
I file statici non possono essere uguali ai file di codice dell'applicazione.
upload
(Facoltativo) Un'espressione regolare che corrisponde ai percorsi dei file per tutti i file a cui verrà fatto riferimento in questo gestore. Questo è necessario perché il gestore non è in grado di determinare quali file nella directory della tua applicazione corrispondono ai pattern url e static_files specificati. I file statici vengono caricati e gestiti separatamente dai file dell'applicazione. L'esempio
sopra potrebbe utilizzare il seguente pattern upload:
archives/(.*)/items/(.*)
url
Elemento obbligatorio in handlers. Il pattern URL, come espressione regolare. L'espressione può contenere raggruppamenti a cui si può fare riferimento nel percorso del file per lo script con riferimenti a espressioni regolari. Ad esempio, /profile/(.*)/(.*) corrisponderà all'URL /profile/edit/manager e utilizza edit e manager come primo e secondo raggruppamento.
Il pattern URL presenta alcune differenze di comportamento quando viene utilizzato con i seguenti elementi:
Utilizza un prefisso URL. Il pattern Express standard non deve contenere
raggruppamenti se utilizzato con l'elemento static_dir. Tutti gli URL che iniziano con questo prefisso vengono gestiti da questo gestore, utilizzando la parte dell'URL dopo il prefisso come parte del percorso del file.
Un gestore di pattern statici dei file associa un pattern URL ai percorsi
dei file statici caricati con l'applicazione. L'espressione regolare del pattern URL può definire raggruppamenti delle espressioni regolari da utilizzare nella creazione del percorso file. Puoi utilizzarlo al posto di static_dir per mappare file specifici in una struttura di directory senza mappare l'intera directory.
Ridimensionare elementi
Gli elementi nella tabella seguente configurano la scalabilità dell'applicazione. Per scoprire di più sulla scalabilità delle app di App Engine, consulta Tipi di scalabilità.
Elemento
Descrizione
automatic_scaling
(Facoltativo) Applicabile solo per le applicazioni che utilizzano una classe di istanza F1 o superiore.
Specifica questo elemento per modificare le impostazioni predefinite per la scalabilità automatica,
ad esempio impostare i livelli minimo e massimo per il numero di istanze,
la latenza e le connessioni simultanee per un servizio.
Questo elemento può contenere i seguenti elementi:
max_instances
(Facoltativo) Specifica un valore compreso tra 0 e 2147483647, dove zero
disattiva l'impostazione.
Questo parametro specifica il numero massimo di istanze che App Engine può creare per questa versione del modulo. Questo è utile per limitare
i costi di un modulo.
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 altre istanze, come richiesto per gestire il traffico.
Specifica un valore compreso tra 0 e 1000. Puoi impostare il parametro sul valore 0 per consentire la scalabilità a 0 istanze per ridurre i costi quando non vengono gestite richieste. Tieni presente che ti viene addebitato il numero di istanze specificate indipendentemente dal fatto che stiano ricevendo traffico o meno.
max_idle_instances
(Facoltativo) Il numero massimo di istanze inattive che App Engine deve conservare per questa versione. Specifica un valore compreso tra 1 e 1000. Se non specificato, il valore predefinito è automatic,
il che significa che App Engine gestirà
il numero di istanze inattive.
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. Questo
aiuta l'applicazione a mantenere prestazioni costanti attraverso
le fluttuazioni del carico delle richieste, ma aumenta anche il numero di istanze
inattive (e i conseguenti costi di esecuzione) durante tali periodi di
carico elevato.
Un valore minimo basso mantiene bassi i costi di esecuzione, ma può ridurre le prestazioni di fronte ai livelli di carico volatili.
Nota: quando si torna a livelli normali dopo un picco di carico, il numero di istanze inattive può superare temporaneamente il limite massimo specificato. Tuttavia, non ti verrà addebitato più di un numero di istanze rispetto al numero massimo specificato.
min_idle_instances
Facoltativo: il numero di istanze aggiuntive da mantenere in esecuzione e pronte per gestire il traffico di questa versione.
App Engine calcola il numero di istanze necessarie per gestire il traffico attuale dell'applicazione in base alle impostazioni di scalabilità come target_cpu_utilization e target_throughput_utilization. L'impostazione min_idle_instances
specifica il numero di istanze da eseguire in aggiunta a questo numero calcolato. Ad esempio, se App Engine calcola che 5 istanze sono necessarie per gestire il traffico e min_idle_instances è impostato su 2, App Engine eseguirà 7 istanze (5, calcolate in base al traffico più 2 aggiuntive per min_idle_instances).
Tieni presente che ti viene addebitato il numero di istanze specificate indipendentemente dal fatto che stiano ricevendo traffico o meno. Tieni presente che:
Un minimo minimo consente di mantenere bassi i costi di esecuzione durante i periodi di inattività, ma significa che potrebbe essere immediatamente disponibile un numero inferiore di istanze per rispondere a un improvviso picco di carico.
Un minimo elevato consente di preparare l'applicazione a picchi rapidi nel carico di richieste. App Engine mantiene il numero minimo di istanze in esecuzione per gestire le richieste in entrata. Ti viene addebitato il numero di istanze specificate, indipendentemente dal fatto che stiano gestendo o meno le richieste.
Se imposti un numero minimo di istanze inattive, la latenza in attesa avrà un effetto inferiore sulle prestazioni dell'applicazione.
target_cpu_utilization
(Facoltativo) Specifica un valore compreso tra 0,5 e 0,95. Il valore predefinito è
0.6.
Questo parametro specifica la soglia di utilizzo della CPU nella quale le nuove istanze inizieranno a gestire il traffico, consentendoti di bilanciare prestazioni e costi; valori più bassi aumentano le prestazioni e aumentano i costi; valori più alti diminuiscono le prestazioni, ma riducono anche i costi. Ad esempio, un valore pari a 0,7 indica che le nuove istanze verranno avviate dopo che l'utilizzo della CPU ha raggiunto il 70%.
target_throughput_utilization
(Facoltativo) Specifica un valore compreso tra 0,5 e 0,95. Il valore predefinito è
0.6.
Utilizzato con max_concurrent_requests per specificare quando viene avviata una nuova istanza a causa di richieste in parallelo. Quando il numero di richieste in parallelo raggiunge un valore pari a max_concurrent_requests volte target_throughput_utilization, lo scheduler tenta di avviare una nuova istanza.
max_concurrent_requests
(Facoltativo) Il numero di richieste in parallelo che un'istanza di scalabilità automatica può accettare prima che lo scheduler generi una nuova istanza (impostazione predefinita: 10, massimo: 1000).
Utilizzato con target_throughput_utilization per specificare quando viene avviata una nuova istanza a causa di richieste in parallelo.
Quando il numero di richieste in parallelo raggiunge un valore pari a max_concurrent_requests volte target_throughput_utilization, lo scheduler tenta di avviare una nuova istanza.
Ti consigliamo di non impostare max_concurrent_requests
su un valore inferiore a 10, a meno che non sia necessario un solo thread. È probabile che un valore inferiore a 10 generi più istanze del necessario per un'app threadsafe e ciò potrebbe comportare costi non necessari.
Se questa impostazione è troppo alta, la latenza dell'API potrebbe risultare aumentata. Tieni presente che lo scheduler potrebbe generare una nuova istanza prima che venga raggiunto il numero massimo effettivo di richieste.
max_pending_latency
La quantità massima di tempo 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 la latenza in attesa. Quando viene raggiunta questa soglia, è un indicatore per fare lo scale up e comporta un aumento del numero di istanze.
Se non è specificato, il valore predefinito è automatic. Ciò significa che le richieste possono rimanere nella coda in attesa per un massimo di 10 secondi, il limite massimo di tempo per le richieste in attesa, prima che vengano attivate le nuove istanze.
Un valore massimo basso significa che App Engine avvierà le nuove istanze prima per le richieste in attesa, migliorando le prestazioni ma aumentando i costi di esecuzione.
Un limite massimo elevato significa che gli utenti potrebbero attendere più tempo per la pubblicazione delle loro richieste (se ci sono richieste in attesa e nessuna istanza inattiva per gestirle), ma l'esecuzione dell'applicazione avrà un costo inferiore.
min_pending_latency
Un elemento facoltativo che puoi impostare per specificare il tempo minimo
in cui App Engine deve consentire a una richiesta di attendere nella
coda in attesa prima di avviare una nuova istanza per gestirla.
Specificare un valore può ridurre i costi di esecuzione, ma aumentare il tempo
in cui gli utenti devono attendere che vengano pubblicate le loro richieste.
Per le app gratuite, il valore predefinito è 500ms. Per le app a pagamento, il valore predefinito è 0.
Questo elemento interagisce con l'elemento max_pending_latency per determinare quando App Engine crea nuove istanze.
Se le richieste in attesa sono in coda:
Inferiore al min_pending_latency specificato, App Engine non creerà nuove istanze.
Più di max_pending_latency, App Engine proverà a creare una nuova istanza.
Tra il periodo di tempo specificato da min_pending_latency
e max_pending_latency, App Engine proverà
a riutilizzare un'istanza esistente. Se nessuna istanza è in grado di elaborare la richiesta prima del giorno max_pending_latency, App Engine creerà una nuova istanza.
