Creazione dei gestori di attività

Questa pagina descrive come creare un gestore di attività, il codice che gestisce un'attività push. Devi fornire un gestore delle richieste per elaborare l'attività. La mappatura dall'URL della richiesta al gestore appropriato è dichiarata in app.yaml del tuo servizio, come per qualsiasi altro gestore delle richieste. Poiché sei tu a controllare come mappare le richieste di attività a un gestore, puoi organizzare liberamente i gestori delle attività. Se la tua applicazione elabora molti tipi diversi di attività, puoi aggiungere tutti i gestori a un singolo servizio o distribuirli tra più servizi.

Scrittura di un gestore delle richieste di attività push

Nella coda, il servizio Task Queue crea un'intestazione HTTP e la invia a un'istanza del servizio worker specificato dal target dell'attività. Le richieste di Task Queue vengono inviate dall'indirizzo IP 0.1.0.2.

Il gestore non deve essere scritto nella stessa lingua in cui è stata creata e messa in coda l'attività se si trova in un servizio separato.

Quando scrivi il tuo gestore, segui queste linee guida:

  • Il codice deve restituire un codice di stato HTTP compreso nell'intervallo 200-299 per indicare il successo. Qualsiasi altro codice indica che l'attività non è riuscita.

  • Le attività push hanno una scadenza di completamento fissa che dipende dal tipo di scalabilità del servizio che le esegue. I servizi di scalabilità automatica devono essere completati prima che siano trascorsi 10 minuti. I servizi di scalabilità manuale e di base possono essere eseguiti per un massimo di 24 ore. Se il gestore manca la scadenza, il servizio Task Queue presume che l'attività non sia riuscita e la riproverà.

  • L'handler deve essere idempotente. L'API Task Queue di App Engine è progettata per fornire la consegna "almeno una volta". In altre parole, se un'attività viene aggiunta correttamente, App Engine la invierà a un gestore almeno una volta. Tieni presente che in alcuni rari casi è possibile l'esecuzione di più attività, pertanto il codice deve garantire che non si verifichino effetti collaterali dannosi dell'esecuzione ripetuta.

La coda di attività utilizza il codice HTTP nella risposta dell'handler per determinare se la tâche è riuscita. La risposta dell'handler viene visualizzata solo dal servizio Task Queue e solo per determinare se l'attività è riuscita. La coda ignora tutti gli altri campi nella risposta. Il servizio ignora quindi la risposta. L'app di origine non riceve mai i dati. Se un'attività non va a buon fine, il servizio Task Queue riprova inviando un'altra richiesta.

I dati forniti dall'utente possono essere inviati all'handler nella richiesta come stringa di query o come payload nel corpo della richiesta. L'inserimento dei dati utente è descritto in Creare attività. Se la richiesta include dati, l'handler deve sapere come sono stati inseriti nella richiesta. Il codice esatto utilizzato per recuperare i dati dalla richiesta dipende dal particolare framework web in uso.

Per testare un gestore delle attività, accedi come amministratore e visita l'URL del gestore nel browser.

Intestazioni delle richieste di lettura

Una richiesta HTTP di attività push ha intestazioni speciali impostate da App Engine, che contengono informazioni specifiche dell'attività che il gestore può utilizzare.

Se queste intestazioni sono presenti in una richiesta di un utente esterno alla tua app, vengono rimosse e sostituite. L'unica eccezione riguarda le richieste degli amministratori dell'applicazione che hanno eseguito l'accesso e che sono autorizzati a impostare le intestazioni a scopo di test. Invece, i titoli non vengono rimossi quando l'app è in esecuzione nel server di sviluppo.

Le richieste provenienti dalla coda di attività conterranno sempre le seguenti intestazioni:

Intestazione Descrizione
X-Appengine-QueueName Il nome della coda (eventualmente "default" per la coda in modalità push predefinita).
X-Appengine-TaskName Il nome dell'attività o un ID univoco generato dal sistema se non è stato specificato alcun nome.
X-Appengine-TaskRetryCount Il numero di volte in cui è stato eseguito un nuovo tentativo per questa attività. Per il primo tentativo, questo valore è 0. Questo numero include i tentativi in cui l'attività non è riuscita a causa della mancanza di istanze disponibili e non ha mai raggiunto la fase di esecuzione.
X-Appengine-TaskExecutionCount Il numero di volte in cui questa attività non è riuscita in precedenza durante la fase di esecuzione. Questo numero non include i fallimenti dovuti alla mancanza di istanze disponibili.
X-Appengine-TaskETA Il tempo di esecuzione target dell'attività, specificato in secondi dal 1° gennaio 1970.

Se il gestore delle richieste trova una delle intestazioni elencate sopra, può essere certo che la richiesta è una richiesta della coda di attività.

Inoltre, le richieste dalla coda di attività possono contenere le seguenti intestazioni:

Intestazione Descrizione
X-Appengine-TaskPreviousResponse Il codice di risposta HTTP del tentativo precedente.
X-Appengine-TaskRetryReason Il motivo per cui riprovare a eseguire l'attività.
X-Appengine-FailFast Indica che un'attività in esecuzione non va a buon fine immediatamente se non è disponibile un'istanza esistente.

Protezione degli URL dei gestori di attività

Se un'attività esegue operazioni sensibili (ad esempio la modifica dei dati), ti consigliamo di proteggere l'URL del gestore per impedire a un utente esterno malintenzionato di chiamarlo direttamente. Puoi impedire agli utenti di accedere agli URL delle attività limitando l'accesso agli amministratori di App Engine. Le richieste di attività vengono generate da App Engine e possono sempre avere come target un URL con limitazioni.

Passaggi successivi