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à. Il mapping dall'URL della richiesta al gestore appropriato viene dichiarato nel file app.yaml del servizio, proprio come qualsiasi altro gestore di richieste. Poiché controlli come mappare le richieste di attività a un gestore, puoi organizzare i gestori di attività. Se la tua applicazione elabora molti tipi diversi di attività, puoi aggiungere tutti i gestori a un unico servizio oppure puoi 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 specificata dalla destinazione dell'attività. Le richieste Task Queue vengono inviate dall'indirizzo IP 0.1.0.2.

Se il gestore si trova in un servizio separato, non è necessario che sia scritto nella stessa lingua in cui è stato creato e messo in coda il task.

Quando scrivi il tuo handler, segui queste linee guida:

  • Il codice deve restituire un codice di stato HTTP compreso tra 200 e 299 per indicare l'esito positivo. Qualsiasi altro codice indica che l'attività non è riuscita.

  • I push task hanno una scadenza di completamento fissa che dipende dal tipo di scalabilità del servizio che li esegue. I servizi di scalabilità automatica devono terminare prima che siano trascorsi 10 minuti. I servizi di scalabilità manuale e di base possono essere eseguiti fino a 24 ore. Se il gestore non rispetta la scadenza, il servizio Task Queues presuppone che l'attività non sia riuscita e riproverà a eseguirla.

    Quando il tempo di esecuzione di un'attività si avvicina alla scadenza, App Engine genera un'eccezione DeadlineExceededError (dal modulo google.appengine.runtime) prima del raggiungimento della scadenza, in modo da poter salvare il lavoro o registrare i progressi effettuati.

  • Il gestore deve essere idempotente. L'API Task Queue di App Engine è progettata per fornire la consegna "at least once", ovvero 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 vi siano effetti collaterali dannosi dell'esecuzione ripetuta.

L'esempio seguente mostra il recupero di un valore intero da una richiesta e l'aggiunta del valore a un contatore gestito in Cloud Datastore:


from google.appengine.ext import ndb
import webapp2


COUNTER_KEY = 'default counter'


class Counter(ndb.Model):
    count = ndb.IntegerProperty(indexed=False)


class UpdateCounterHandler(webapp2.RequestHandler):
    def post(self):
        amount = int(self.request.get('amount'))

        # This task should run at most once per second because of the datastore
        # transaction write throughput.
        @ndb.transactional
        def update_counter():
            counter = Counter.get_or_insert(COUNTER_KEY, count=0)
            counter.count += amount
            counter.put()

        update_counter()


app = webapp2.WSGIApplication([
    ('/update_counter', UpdateCounterHandler)
], debug=True)

La mappatura dall'URL dell'attività /update-counter alla classe UpdateCounterHandler viene eseguita all'interno di WSGIApplication.

Il file worker.yaml crea un servizio denominato "worker" e vi aggiunge il codice worker. Tieni presente che l'URL del gestore è sicuro perché specifica login:admin:

runtime: python27
api_version: 1
threadsafe: true
service: worker

handlers:
- url: /.*
  script: worker.app
  login: admin

Task Queue utilizza il codice HTTP nella risposta del gestore per determinare se l'attività è stata completata correttamente. La risposta del gestore è visibile solo al servizio Task Queue e solo per determinare se l'attività è stata completata. La coda ignora tutti gli altri campi nella risposta. Il servizio scarta quindi la risposta. L'app di origine non riceve nessuno dei dati. Se un'attività non va a buon fine, il servizio Task Queue riprova a eseguirla inviando un'altra richiesta.

I dati forniti dall'utente possono essere inviati al gestore nella richiesta come stringa di query o come payload nel corpo della richiesta. L'inserimento dei dati utente è descritto in Creazione di attività. Se la richiesta include dati, il gestore deve sapere come sono stati inseriti nella richiesta. Il codice esatto che utilizzi per recuperare i dati dalla richiesta dipende dal framework web specifico che utilizzi.

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

Lettura delle intestazioni delle richieste

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 che hanno eseguito l'accesso all'applicazione, che sono autorizzati a impostare le intestazioni a scopo di test. D'altra parte, le intestazioni non vengono rimosse quando l'app è in esecuzione nel server di sviluppo.

Le richieste di Task Queue conterranno sempre le seguenti intestazioni:

Intestazione Descrizione
X-Appengine-QueueName Il nome della coda (possibilmente "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 tentativi di ripetizione di 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 gli errori 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ò considerare la richiesta come una richiesta di Task Queue.

Inoltre, le richieste di Task Queue possono contenere le seguenti intestazioni:

Intestazione Descrizione
X-Appengine-TaskPreviousResponse Il codice di risposta HTTP del precedente tentativo.
X-Appengine-TaskRetryReason Il motivo per cui viene eseguito un nuovo tentativo di esecuzione dell'attività.
X-Appengine-FailFast Indica che un'attività in esecuzione non riesce immediatamente se un'istanza esistente non è disponibile.

Protezione degli URL dei gestori di attività

Se un'attività esegue operazioni sensibili (come 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 emesse da App Engine e possono sempre avere come target un URL con limitazioni.

Puoi limitare un URL aggiungendo l'elemento login: admin alla configurazione del gestore nel file app.yaml.

Ad esempio:

handlers:
- url: /your-task
  script: worker.app
  login: admin

Passaggi successivi