Aufgaben-Handler erstellen

Auf dieser Seite wird erläutert, wie Sie einen Aufgaben-Handler erstellen, also Code, mit dem eine Push-Aufgabe verarbeitet wird. Sie müssen einen Anfrage-Handler zur Verarbeitung der Aufgabe angeben. Die Zuordnung der Anfrage-URL zum richtigen Handler wird wie bei jedem anderen Anfrage-Handler in der Datei app.yaml des Dienstes angegeben. Da Sie steuern, wie einem Handler Aufgabenanfragen zugeordnet werden, haben Sie beim Organisieren Ihrer Aufgaben-Handler freie Hand. Wenn Ihre Anwendung viele verschiedene Arten von Aufgaben verarbeitet, können Sie alle diese Handler zu einem einzigen Dienst hinzufügen oder sie auf mehrere Dienste verteilen.

Anfrage-Handler für Push-Aufgabe schreiben

In der Aufgabenwarteschlange erstellt der Aufgabenwarteschlangendienst einen HTTP-Header und sendet ihn an eine Instanz des Worker-Dienstes, der durch das Ziel der Aufgabe angegeben ist. Die Anfragen der Aufgabenwarteschlange werden von der IP-Adresse 0.1.0.2 gesendet.

Wenn Sie den Handler in einem separaten Dienst schreiben, braucht er nicht in derselben Sprache geschrieben zu werden, in der die Aufgabe erstellt und in die Warteschlange eingefügt wurde.

Beachten Sie beim Schreiben des Handlers folgende Richtlinien:

  • Der Code muss einen HTTP-Statuscode im Bereich von 200 bis 299 für die erfolgreiche Verarbeitung zurückgeben. Jeder andere Code zeigt an, dass die Aufgabe fehlgeschlagen ist.

  • Für Push-Aufgaben gibt es eine feste Fertigstellungsfrist, die vom Skalierungstyp des Dienstes abhängt, mit dem sie ausgeführt werden. Automatische Skalierungsdienste müssen innerhalb von 10 Minuten abgeschlossen sein. Manuelle und einfache Skalierungsdienste können bis zu 24 Stunden ausgeführt werden. Wenn die Frist für Ihren Handler verstrichen ist, geht der Dienst der Aufgabenwarteschlange davon aus, dass die Aufgabe fehlgeschlagen ist, und versucht die Ausführung noch einmal.

    Wenn sich die Ausführungszeit einer Aufgabe der Frist nähert, löst App Engine vor Erreichen der Frist eine DeadlineExceededError (aus dem google.appengine.runtime-Modul) aus, sodass Sie Ihre Arbeit speichern oder den Fortschritt in Logs erfassen können.

  • Der Handler muss idempotent sein. Die Task Queue API von App Engine ist darauf ausgelegt, eine Aufgabe "mindestens einmal" zu senden. Wenn also eine Aufgabe erfolgreich hinzugefügt wurde, sendet App Engine diese mindestens einmal an einen Handler. In einigen seltenen Fällen ist eine mehrmalige Ausführung von Aufgaben möglich. Daher muss im Code sichergestellt sein, dass bei wiederholter Ausführung keine schädlichen Auswirkungen auftreten.

Im folgenden Beispiel wird das Abrufen einer Ganzzahl aus einer Anfrage und das Hinzufügen des Werts zu einem in Cloud Datastore verwalteten Zähler veranschaulicht:


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)

Die Zuordnung von der Aufgaben-URL /update-counter zur UpdateCounterHandler-Klasse erfolgt innerhalb von WSGIApplication.

Die worker.yaml-Datei erstellt einen Dienst namens "worker" und fügt den Worker-Code hinzu. Die URL des Handlers ist durch Angabe von login:admin sicher:

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

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

Die Aufgabenwarteschlange überprüft anhand des HTTP-Codes in der Antwort des Handlers, ob die Aufgabe erfolgreich war. Die Antwort wird nur dem Aufgabenwarteschlangendienst übermittelt, damit dieser feststellen kann, ob die Aufgabe erfolgreich ausgeführt wurde. Alle anderen Felder in der Antwort werden von der Warteschlange ignoriert. Anschließend wird die Antwort vom Dienst verworfen. Die ursprüngliche Anwendung empfängt keine dieser Daten. Wenn eine Aufgabe fehlschlägt, wiederholt der Aufgabenwarteschlangendienst die Aufgabe. Hierzu wird eine weitere Anfrage vom Dienst gesendet.

Vom Nutzer bereitgestellte Daten können in der Anfrage als Abfragestring oder als Nutzlast im Anfragetext an den Handler gesendet werden. Das Einfügen von Nutzerdaten wird unter Aufgaben erstellen beschrieben. Wenn die Anfrage Daten enthält, muss der Handler erkennen können, wie die Daten in die Anfrage eingefügt wurden. Der genaue Code, den Sie zum Abrufen der Daten aus der Anfrage verwenden, hängt vom jeweils verwendeten Web-Framework ab.

Melden Sie sich zum Testen eines Aufgaben-Handlers als Administrator an und rufen Sie im Browser die Handler-URL auf.

Anfrageheader lesen

Eine HTTP-Anfrage für eine Push-Aufgabe hat spezielle Header, die von App Engine festgelegt werden und aufgabenspezifische Informationen enthalten, die der Handler verwenden kann.

Wenn diese Header in einer externen Nutzeranfrage an Ihre Anwendung vorhanden sind, werden sie entfernt und ersetzt. Eine Ausnahme bilden Anfragen von angemeldeten Administratoren der Anwendung, die Header für Testzwecke festlegen dürfen. Wenn Ihre Anwendung jedoch auf dem Entwicklungsserver ausgeführt wird, werden Header nicht entfernt.

Anfragen aus der Aufgabenwarteschlange enthalten immer die folgenden Header:

Header Beschreibung
X-Appengine-QueueName Der Name der Warteschlange (möglicherweise "default" für die Standard-Push-Warteschlange).
X-Appengine-TaskName Der Name der Aufgabe oder eine vom System generierte eindeutige ID, wenn kein Name festgelegt wurde.
X-Appengine-TaskRetryCount Die Anzahl der Ausführungsversuche für diese Aufgabe. Für den ersten Versuch lautet dieser Wert 0. Diese Anzahl enthält Versuche, bei denen die Aufgabe aufgrund fehlender verfügbarer Instanzen fehlgeschlagen ist und die Ausführungsphase nicht erreicht wurde.
X-Appengine-TaskExecutionCount Die Zahl, die angibt, wie oft diese Aufgabe vorher während der Ausführungsphase fehlgeschlagen ist. Für diesen Wert werden Fehler aufgrund fehlender verfügbarer Instanzen nicht berücksichtigt.
X-Appengine-TaskETA Die Zielausführungszeit der Aufgabe, angegeben in Sekunden seit dem 1. Januar 1970.

Wenn der Anfrage-Handler einen der oben aufgeführten Header erkennt, kann er davon ausgehen, dass es sich bei der Anfrage um eine Aufgabenwarteschlangenanfrage handelt.

Darüber hinaus können Aufgabenwarteschlangenanfragen die folgenden Header enthalten:

Header Beschreibung
X-Appengine-TaskPreviousResponse Der HTTP-Antwortcode aus der vorangegangenen Wiederholung.
X-Appengine-TaskRetryReason Der Grund für die Wiederholung der Aufgabe.
X-Appengine-FailFast Zeigt an, dass die Ausführung einer Aufgabe sofort fehlschlägt, wenn keine vorhandene Instanz verfügbar ist.

URLs von Aufgaben-Handlern absichern

Wenn von einer Aufgabe sensible Vorgänge ausgeführt werden (z. B. Datenänderungen), sollten Sie die Handler-URL absichern. Damit können Sie verhindern, dass die URL von böswilligen externen Nutzern direkt aufgerufen wird. Durch Beschränkung des Zugriffs auf App Engine-Administratoren lässt sich verhindern, dass Nutzer auf Aufgaben-URLs zugreifen. Aufgabenanfragen selbst werden von App Engine ausgegeben und können immer auch auf eingeschränkte URLs zugreifen.

Zum Einschränken einer URL können Sie das Element login: admin in die Handler-Konfiguration der Datei app.yaml einfügen.

Beispiel:

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

Weitere Informationen