Modalità di gestione delle richieste

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata al momento della creazione dell'app. Non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono apparire simili ai codici di paese e provincia di uso comune. 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.

Scopri di più sugli ID regione.

Questo documento descrive come l'applicazione App Engine riceve richieste e invia risposte.

Per maggiori dettagli, consulta l'articolo Riferimento per intestazioni e risposte delle richieste.

Se la tua applicazione utilizza i servizi, puoi indirizzare le richieste a un servizio specifico o a una versione specifica di quel servizio. Per maggiori informazioni sull'indirizzabilità dei servizi, consulta Modalità di routing delle richieste.

Gestione delle richieste

La tua applicazione è responsabile dell'avvio di un server web e della gestione delle richieste. Puoi utilizzare qualsiasi framework web disponibile per il tuo linguaggio di sviluppo.

App Engine esegue più istanze dell'applicazione, ognuna con un proprio server web per la gestione delle richieste. Qualsiasi richiesta può essere instradata a qualsiasi istanza, pertanto le richieste consecutive dello stesso utente non vengono inviate necessariamente alla stessa istanza. Un'istanza può gestire più richieste contemporaneamente. Il numero di istanze può essere regolato automaticamente in base alle variazioni del traffico. Puoi anche modificare il numero di richieste in parallelo che un'istanza può gestire impostando l'elemento max_concurrent_requests nel file app.yaml.

Quando App Engine riceve una richiesta web per la tua applicazione, chiama lo script del gestore che corrisponde all'URL, come descritto nel file di configurazione app.yaml dell'applicazione. Il runtime Python 2.7 supporta lo standard WSGI e lo standard CGI per la compatibilità con le versioni precedenti. WSGI è preferibile e alcune funzionalità di Python 2.7 non funzionano senza questo servizio. La configurazione dei gestori di script dell'applicazione determina se una richiesta viene gestita utilizzando WSGI o CGI.

Il seguente script Python risponde a una richiesta con un'intestazione HTTP e il messaggio Hello, World!.

import webapp2

class MainPage(webapp2.RequestHandler):
    def get(self):
        self.response.headers["Content-Type"] = "text/plain"
        self.response.write("Hello, World!")

app = webapp2.WSGIApplication(
    [
        ("/", MainPage),
    ],
    debug=True,
)

Per inviare più richieste in parallelo a ogni server web, contrassegna la tua applicazione come threadsafe aggiungendo un elemento threadsafe: true al tuo file app.yaml. Non sono disponibili richieste in parallelo se un gestore di script utilizza CGI.

Quote e limiti

App Engine alloca automaticamente le risorse alla tua applicazione man mano che il traffico aumenta. Tuttavia, ciò è vincolato dalle seguenti limitazioni:

  • App Engine riserva una capacità di scalabilità automatica per le applicazioni a bassa latenza, in cui l'applicazione risponde alle richieste in meno di un secondo.

  • Le applicazioni molto legate alla CPU possono anche comportare una latenza aggiuntiva per condividere in modo efficiente le risorse con altre applicazioni sugli stessi server. Le richieste di file statici sono esenti da questi limiti di latenza.

Ogni richiesta in entrata nell'applicazione viene conteggiata ai fini del limite di Richieste. I dati inviati in risposta a una richiesta vengono conteggiati ai fini del limite di larghezza di banda in uscita (fatturabile).

Entrambe le richieste HTTP e HTTPS (protette) vengono conteggiate ai fini dei limiti Richieste, Larghezza di banda in entrata (fatturabile) e Larghezza di banda in uscita (fatturabile). La pagina dei dettagli delle quote della console Google Cloud segnala anche le Richieste sicure, la Larghezza di banda in entrata sicura e Larghezza di banda in uscita sicura come valori separati a scopo informativo. Solo le richieste HTTPS vengono conteggiate per questi valori. Per ulteriori informazioni, consulta la pagina Quote.

I seguenti limiti si applicano specificamente all'uso dei gestori delle richieste:

Limite Quantità
Dimensioni richiesta 32 megabyte
Dimensione della risposta 32 megabyte
Timeout richiesta Dipende dal tipo di scalabilità utilizzato dall'app
Numero totale massimo di file (file di app e file statici) 10.000 in totale
1000 per directory
Dimensione massima del file di un'applicazione 32 megabyte
Dimensione massima di un file statico 32 megabyte
Dimensioni totali massime di tutti i file statici e delle applicazioni Il primo gigabyte è gratuito
0,026$ per gigabyte al mese dopo il primo gigabyte
Timeout richiesta in attesa 10 secondi
Dimensione massima di un singolo campo intestazione della richiesta 8 kilobyte per i runtime di seconda generazione nell'ambiente standard. Le richieste a questi runtime con campi di intestazione che superano gli 8 kilobyte restituiranno errori HTTP 400.

Limiti per le richieste

Tutte le richieste HTTP/2 saranno tradotte in richieste HTTP/1.1 quando inoltrate al server delle applicazioni.

Limiti di risposta

  • Le risposte dinamiche hanno un limite di 32 MB. Se un gestore di script genera una risposta superiore a questo limite, il server restituisce una risposta vuota con un codice di stato errore interno del server 500. Questa limitazione non si applica alle risposte che forniscono dati dall'archivio BLOB legacy o da Cloud Storage.

  • Il limite delle intestazioni delle risposte è di 8 kB per i runtime di seconda generazione. Le intestazioni della risposta che superano questo limite restituiranno errori HTTP 502, con log che mostrano upstream sent too big header while reading response header from upstream.

Intestazioni delle richieste

Una richiesta HTTP in entrata include le intestazioni HTTP inviate dal client. Per motivi di sicurezza, alcune intestazioni vengono controllate o modificate da proxy intermedi prima che raggiungano l'applicazione.

Per saperne di più, consulta la sezione Riferimento alle intestazioni delle richieste.

Gestione dei timeout delle richieste

App Engine è ottimizzato per le applicazioni con richieste di breve durata, in genere quelle che richiedono alcune centinaia di millisecondi. Un'app efficiente risponde rapidamente alla maggior parte delle richieste. un'app che non scala bene con l'infrastruttura di App Engine. Per garantire questo livello di prestazioni, è previsto un timeout della richiesta massimo imposto dal sistema tramite il quale ogni app deve rispondere.

Se la tua app supera questa scadenza, App Engine interrompe il gestore delle richieste. L'ambiente di runtime Python raggiunge questo obiettivo generando un'eccezione DeadlineExceededError da google.appengine.runtime. Se il gestore delle richieste non rileva questa eccezione, come per tutte le eccezioni non rilevate, l'ambiente di runtime restituirà un errore HTTP 500 del server al client.

Il gestore delle richieste può rilevare questo errore per personalizzare la risposta. L'ambiente di runtime concede al gestore delle richieste un po' più di tempo (meno di un secondo) dopo aver sollevato l'eccezione per preparare una risposta personalizzata.

class TimerHandler(webapp2.RequestHandler):
    def get(self):
        from google.appengine.runtime import DeadlineExceededError

        try:
            time.sleep(70)
            self.response.write("Completed.")
        except DeadlineExceededError:
            self.response.clear()
            self.response.set_status(500)
            self.response.out.write("The request did not complete in time.")

Se il gestore non ha restituito una risposta o sollevato un'eccezione entro la seconda scadenza, il gestore viene arrestato e viene restituita una risposta di errore predefinita.

Risposte

App Engine chiama lo script del gestore con un Request e attende che lo script restituisca; tutti i dati scritti nel flusso di output standard vengono inviati come risposta HTTP.

Alla risposta generata si applicano limiti di dimensioni e la risposta può essere modificata prima di essere restituita al client.

Per saperne di più, consulta l'articolo Informazioni sulle richieste di risposte.

Risposte dinamiche

App Engine non supporta risposte in modalità flusso in cui i dati vengono inviati al client in blocchi incrementali durante l'elaborazione della richiesta. Tutti i dati provenienti dal codice vengono raccolti come descritto in precedenza e inviati come singola risposta HTTP.

Compressione delle risposte

App Engine fa del suo meglio per distribuire contenuti compressi (gzip) ai client che li supportano. Per determinare se i contenuti devono essere compressi, App Engine esegue le seguenti operazioni quando riceve una richiesta:

  1. Conferma se il client può ricevere in modo affidabile risposte compresse visualizzando entrambe le intestazioni Accept-Encoding e User-Agent nella richiesta. Questo approccio evita alcuni bug noti con contenuti compressi con gzip nei browser più diffusi.

  2. Conferma se la compressione dei contenuti è appropriata visualizzando l'intestazione Content-Type che hai configurato per il gestore delle risposte. In generale, la compressione è appropriata per i tipi di contenuti basati su testo e non per i tipi di contenuti binari.

Tieni presente quanto segue:

  • Un client può forzare la compressione di tipi di contenuti basati su testo impostando entrambe le intestazioni della richiesta Accept-Encoding e User-Agent su gzip.

  • Se una richiesta non specifica gzip nell'intestazione Accept-Encoding, App Engine non comprime i dati della risposta.

  • Google Frontend memorizza nella cache le risposte provenienti dai gestori di directory e file statici di App Engine. A seconda di una serie di fattori, come il tipo di dati di risposta che vengono memorizzati per primi nella cache, le intestazioni Vary che hai specificato nella risposta e le intestazioni incluse nella richiesta, un client può richiedere dati compressi ma ricevere dati non compressi e viceversa. Per ulteriori informazioni, consulta Memorizzazione nella cache delle risposte.

Memorizzazione nella cache delle risposte

Il frontend Google e, potenzialmente, il browser dell'utente e altri server proxy intermedi con memorizzazione nella cache, memorizzeranno nella cache le risposte della tua app come indicato dalle intestazioni standard di memorizzazione nella cache specificate nella risposta. Puoi specificare queste intestazioni di risposta tramite il framework, direttamente nel codice o tramite i gestori di file statici e directory di App Engine.

Nel frontend Google, la chiave cache è l'URL completo della richiesta.

Memorizzazione nella cache dei contenuti statici

Per fare in modo che i client ricevano sempre contenuti statici aggiornati non appena vengono pubblicati, ti consigliamo di pubblicare contenuti statici da directory sottoposte a controllo delle versioni, ad esempio css/v1/styles.css. Google Frontend non convalida la cache (verifica la presenza di contenuti aggiornati) fino alla scadenza. Anche dopo la scadenza, questa non verrà aggiornata finché non vengono modificati i contenuti dell'URL di richiesta.

Le seguenti intestazioni di risposta che puoi impostare app.yaml influiscono su come e quando il Google Frontend memorizza i contenuti nella cache:

  • Cache-Control deve essere impostato su public affinché il frontend Google possa memorizzare i contenuti nella cache; può anche essere memorizzato nella cache dal frontend Google, a meno che non specifichi un'istruzione Cache-Control private o no-store. Se non imposti questa intestazione in app.yaml, App Engine la aggiunge automaticamente per tutte le risposte gestite da un gestore di directory o file statico. Per scoprire di più, consulta la sezione Intestazioni aggiunte o sostituite.

  • Vary: per fare in modo che la cache restituisca risposte diverse per un URL in base alle intestazioni inviate nella richiesta, imposta uno o più dei seguenti valori nell'intestazione della risposta Vary: Accept, Accept-Encoding, Origin o X-Origin

    A causa del potenziale di una cardinalità elevata, i dati non verranno memorizzati nella cache per altri valori Vary.

    Ad esempio:

    1. Specifica la seguente intestazione della risposta:

      Vary: Accept-Encoding

    2. L'app riceve una richiesta che contiene l'intestazione Accept-Encoding: gzip. App Engine restituisce una risposta compressa e Google Frontend memorizza nella cache la versione compressa con gzip dei dati della risposta. Tutte le richieste successive per questo URL che contengono l'intestazione Accept-Encoding: gzip riceveranno i dati compressi dalla cache fino a quando la cache non verrà invalidata (a causa della modifica dei contenuti dopo la scadenza della cache).

    3. La tua app riceve una richiesta che non contiene l'intestazione Accept-Encoding. App Engine restituisce una risposta non compressa e Google Frontend memorizza nella cache la versione non compressa dei dati delle risposte. Tutte le richieste successive per questo URL che non contengono l'intestazione Accept-Encoding riceveranno i dati compressi dalla cache fino a quando la cache non verrà invalidata.

    Se non specifichi un'intestazione della risposta Vary, Google Frontend crea una singola voce di cache per l'URL e la utilizza per tutte le richieste, a prescindere dalle intestazioni della richiesta. Ad esempio:

    1. Non devi specificare l'intestazione della risposta Vary: Accept-Encoding.
    2. Una richiesta contiene l'intestazione Accept-Encoding: gzip e la versione compressa con gzip dei dati della risposta verrà memorizzata nella cache.
    3. Una seconda richiesta non contiene l'intestazione Accept-Encoding: gzip. Tuttavia, poiché la cache contiene una versione compressa con gzip dei dati della risposta, la risposta verrà compressa con gzip anche se il client ha richiesto dati non compressi.

Anche le intestazioni nella richiesta influenzano la memorizzazione nella cache:

  • Se la richiesta contiene un'intestazione Authorization, i contenuti non verranno memorizzati nella cache da Google Frontend.

Scadenza della cache

Per impostazione predefinita, le intestazioni di memorizzazione nella cache aggiunte dai gestori di file statici e di directory di App Engine alle risposte indicano ai client e ai proxy web come Google Frontend di far scadere la cache dopo 10 minuti.

Dopo che un file viene trasmesso con un determinato orario di scadenza, generalmente non è possibile svuotarlo dalle cache del proxy web, anche se l'utente svuota la cache del browser. Il nuovo deployment di una nuova versione dell'app non reimposta le cache. Pertanto, se pianifichi di modificare un file statico, la scadenza deve essere breve (meno di un'ora). Nella maggior parte dei casi, la scadenza predefinita è di 10 minuti.

Puoi modificare la scadenza predefinita per tutti i gestori di directory e file statici specificando l'elemento default_expiration nel file app.yaml. Per impostare scadenze specifiche per i singoli gestori, specifica l'elemento expiration all'interno dell'elemento gestore nel file app.yaml.

Il valore specificato nell'ora degli elementi di scadenza verrà utilizzato per impostare le intestazioni della risposta HTTP Cache-Control e Expires.

Memorizzazione nella cache delle app

L'ambiente di runtime Python memorizza nella cache i moduli importati tra le richieste su un singolo server web, in modo simile a come un'applicazione Python autonoma carica un modulo solo una volta, anche se il modulo è importato da più file. Poiché i gestori WSGI sono moduli, vengono memorizzati nella cache tra le richieste. Gli script del gestore CGI vengono memorizzati nella cache solo se forniscono una routine main(); in caso contrario, lo script del gestore CGI viene caricato per ogni richiesta.

La memorizzazione nella cache delle app offre un vantaggio significativo in termini di tempo di risposta. Consigliamo a tutti gli script di gestori CGI di utilizzare una routine main(), come descritto di seguito.

Le importazioni vengono memorizzate nella cache

Per maggiore efficienza, il server web conserva i moduli importati in memoria e non li ricarica né rivaluta in seguito a richieste successive alla stessa applicazione sullo stesso server. La maggior parte dei moduli non inizializza dati globali e non presenta altri effetti collaterali quando vengono importati, quindi la memorizzazione nella cache non modifica il comportamento dell'applicazione.

Se l'applicazione importa un modulo che dipende dal modulo valutato per ogni richiesta, l'applicazione deve supportare questo comportamento di memorizzazione nella cache.

Memorizzazione nella cache dei gestori CGI

Puoi indicare ad App Engine di memorizzare nella cache lo script del gestore CGI stesso, oltre ai moduli importati. Se lo script del gestore definisce una funzione denominata main(), lo script e il suo ambiente globale verranno memorizzati nella cache come un modulo importato. La prima richiesta dello script su un determinato server web valuta lo script normalmente. Per le richieste successive, App Engine chiama la funzione main() nell'ambiente memorizzato nella cache.

Per memorizzare nella cache uno script del gestore, App Engine deve essere in grado di chiamare main() senza argomenti. Se lo script gestore non definisce una funzione main() o la funzione main() richiede argomenti (senza valori predefiniti), App Engine carica e valuta l'intero script per ogni richiesta.

Conservare il codice Python analizzato in memoria consente di risparmiare tempo e accelerare le risposte. La memorizzazione nella cache dell'ambiente globale ha anche altri potenziali usi:

  • Espressioni regolari compilate. Tutte le espressioni regolari vengono analizzate e archiviate in un formato compilato. Puoi archiviare espressioni regolari compilate in variabili globali e quindi utilizzare la memorizzazione nella cache dell'app per riutilizzare gli oggetti compilati tra una richiesta e l'altra.

  • GqlQuery. La stringa di query GQL viene analizzata al momento della creazione dell'oggetto GqlQuery. Il riutilizzo di un oggetto GqlQuery con associazione di parametri e il metodo bind() è più rapido rispetto alla ricostruzione dell'oggetto ogni volta. Puoi archiviare un oggetto GqlQuery con l'associazione di parametri per i valori in una variabile globale e poi riutilizzarlo associando nuovi valori parametro per ogni richiesta.

  • File di configurazione e dati. Se l'applicazione carica e analizza i dati di configurazione da un file, può conservare i dati analizzati in memoria per evitare di dover ricaricare il file a ogni richiesta.

Lo script del gestore deve chiamare main() quando viene importato. App Engine si aspetta che l'importazione dello script chiami main(), quindi App Engine non lo chiama quando carica il gestore di richieste per la prima volta su un server.

La memorizzazione nella cache dell'app con main() offre un miglioramento significativo nel tempo di risposta del gestore CGI. Lo consigliamo per tutte le applicazioni che utilizzano CGI.

Logging

Il server web App Engine acquisisce tutto ciò che lo script del gestore scrive nel flusso di output standard per la risposta alla richiesta web. Acquisisce inoltre tutto ciò che lo script del gestore scrive nel flusso di errori standard e lo archivia come dati di log. A ogni richiesta viene assegnato un request_id, un identificatore univoco a livello globale basato sull'ora di inizio della richiesta. I dati di log per la tua applicazione possono essere visualizzati nella console Google Cloud utilizzando Cloud Logging.

L'ambiente di runtime Python di App Engine include un supporto speciale per il modulo di logging dalla libreria standard Python per comprendere i concetti di logging come i livelli di log ("debug", "info", "warning", "error", "critical").

import logging

import webapp2

class MainPage(webapp2.RequestHandler):
    def get(self):
        logging.debug("This is a debug message")
        logging.info("This is an info message")
        logging.warning("This is a warning message")
        logging.error("This is an error message")
        logging.critical("This is a critical message")

        try:
            raise ValueError("This is a sample value error.")
        except ValueError:
            logging.exception("A example exception log.")

        self.response.out.write("Logging example.")

app = webapp2.WSGIApplication([("/", MainPage)], debug=True)

L'ambiente

L'ambiente di esecuzione imposta automaticamente diverse variabili di ambiente. Puoi impostarne altre in app.yaml. Tra le variabili impostate automaticamente, alcune sono speciali per App Engine, mentre altre fanno parte degli standard WSGI o CGI. Il codice Python può accedere a queste variabili utilizzando il dizionario os.environ.

Le seguenti variabili di ambiente sono specifiche di App Engine:

  • CURRENT_VERSION_ID: la versione principale e secondaria dell'applicazione attualmente in esecuzione, come "X.Y". Il numero di versione principale ("X") è specificato nel file app.yaml dell'app. Il numero di versione secondaria ("Y") viene impostato automaticamente quando ogni versione dell'app viene caricata in App Engine. Sul server web di sviluppo, la versione secondaria è sempre "1".

  • AUTH_DOMAIN: il dominio utilizzato per autenticare gli utenti con l'API Users. Le app ospitate su appspot.com hanno un valore AUTH_DOMAIN di gmail.com e accettano qualsiasi Account Google. Le app ospitate su un dominio personalizzato hanno un valore AUTH_DOMAIN uguale al dominio personalizzato.

  • INSTANCE_ID: contiene l'ID istanza dell'istanza di frontend che gestisce una richiesta. L'ID è una stringa esadecimale (ad esempio, 00c61b117c7f7fd0ce9e1325a04b8f0df30deaaf). Un amministratore che ha eseguito l'accesso può utilizzare l'ID in un URL: https://INSTANCE_ID-dot-VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com. La richiesta verrà instradata a quella specifica istanza di frontend. Se l'istanza non riesce a gestire la richiesta, restituisce un errore 503 immediato.

Le seguenti variabili di ambiente fanno parte degli standard WSGI e CGI, con un comportamento speciale in App Engine:

  • SERVER_SOFTWARE: nel server web di sviluppo, questo valore è "Sviluppo/X.Y", dove "X.Y" indica la versione del runtime. Durante l'esecuzione su App Engine, questo valore è "Google App Engine/X.Y.Z".

Ulteriori variabili di ambiente sono impostate in base allo standard WSGI o CGI. Per ulteriori informazioni su queste variabili, consulta lo standard WSGI o lo standard CGI, a seconda dei casi.

Puoi anche impostare le variabili di ambiente nel file app.yaml:

env_variables:
  DJANGO_SETTINGS_MODULE: 'myapp.settings'

Il seguente gestore di richieste webapp2 mostra ogni variabile di ambiente visibile all'applicazione nel browser:

class PrintEnvironmentHandler(webapp2.RequestHandler):
    def get(self):
        self.response.headers["Content-Type"] = "text/plain"
        for key, value in os.environ.iteritems():
            self.response.out.write("{} = {}\n".format(key, value))

ID richiesta

Al momento della richiesta, puoi salvare l'ID richiesta, univoco per la richiesta. L'ID richiesta può essere utilizzato in un secondo momento per cercare i log della richiesta in Cloud Logging.

Il seguente codice campione mostra come ottenere l'ID richiesta nel contesto di una richiesta:

class RequestIdHandler(webapp2.RequestHandler):
    def get(self):
        self.response.headers["Content-Type"] = "text/plain"
        request_id = os.environ.get("REQUEST_LOG_ID")
        self.response.write("REQUEST_LOG_ID={}".format(request_id))

Forzare le connessioni HTTPS

Per motivi di sicurezza, tutte le applicazioni devono incoraggiare i client a connettersi tramite https. Per indicare al browser di preferire https rispetto a http per una determinata pagina o per l'intero dominio, imposta l'intestazione Strict-Transport-Security nelle risposte. Ad esempio:

Strict-Transport-Security: max-age=31536000; includeSubDomains
Per impostare questa intestazione per tutti i contenuti statici pubblicati dalla tua app, aggiungila ai gestori di file statici e directory dell'app.

Per impostare questa intestazione per le risposte generate dal tuo codice, utilizza la libreria flask-talisman.

Gestione del lavoro in background asincrono

Per lavoro in background si intende qualsiasi operazione eseguita dalla tua app per una richiesta dopo l'invio della risposta HTTP. Evita di eseguire operazioni in background nell'app ed esamina il codice per assicurarti che tutte le operazioni asincrone vengano completate prima di consegnare la risposta.

Per i job a lunga esecuzione, consigliamo di utilizzare Cloud Tasks. Con Cloud Tasks, le richieste HTTP durano a lungo e restituiscono una risposta solo al termine di qualsiasi lavoro asincrono.