Jobs mit cron.yaml planen

Mit dem Cron-Dienst von App Engine können Sie regelmäßig geplante Aufgaben konfigurieren, die zu bestimmten Zeiten oder in festen Intervallen ausgeführt werden. Diese Aufgaben werden allgemein als Cronjobs bezeichnet. Der Cron-Dienst von App Engine löst diese Cronjobs automatisch aus. Sie können damit beispielsweise täglich eine Berichts-E-Mail versenden, alle 10 Minuten bestimmte Cache-Daten oder stündlich bestimmte zusammenfassende Informationen aktualisieren.

Ein Cronjob stellt eine geplante HTTP-GET-Anfrage an den angegebenen Endpunkt in der Anwendung, in der der Cronjob konfiguriert ist. Beim Aufruf führt der Handler für diesen Endpunkt die Logik aus.

Der Cron-Dienst von App Engine kann nicht zum Aufrufen von Webendpunkten außerhalb der App Engine-Hostanwendung verwendet werden. Er kann nicht dazu verwendet werden, um App Engine-Endpunkte aus anderen Anwendungen außer der Host-App aufzurufen.

Cronjob-Anfragen unterliegen denselben Einschränkungen wie andere HTTP-Anfragen. Für kostenlose Anwendungen sind bis zu 20 geplante Aufgaben zulässig. Kostenpflichtige Anwendungen können bis zu 250 geplante Aufgaben enthalten.

Zum Bereitstellen oder Aktualisieren von Zeitplänen benötigt Ihr Konto eine der folgenden Rollen für die Identitäts- und Zugriffsverwaltung:

• Inhaber
• Editor
• Cloud Scheduler Admin (roles/cloudscheduler.admin)

Sie können die Berechtigung in der Google Cloud Console auf der Seite „IAM“ festlegen.

Konfigurationsdatei cron

Für alle Laufzeiten außer Java konfiguriert eine cron.yaml-Datei im Stammverzeichnis Ihrer Anwendung (neben app.yaml) geplante Aufgaben für Ihre Anwendung.

Für Java konfiguriert eine cron.yaml-Datei im Verzeichnis WEB-INF Ihrer Anwendung (neben app.yaml) geplante Aufgaben für Ihre Anwendung.

Hier sehen Sie eine cron.yaml-Beispieldatei:

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

Für die Datei cron.yaml gilt die YAML-Syntax. Die Datei enthält die Definitionen für jeden Ihrer Cronjobs. Eine Jobdefinition muss eine url und einen schedule enthalten. Optional können Sie auch description, timezone, target und retry_parameters angeben:

url

Erforderlich. Die URL in Ihrer Anwendung, an die der Cron-Dienst Jobanfragen senden soll.

schedule

Erforderlich. Definiert den Zeitplan für die Ausführung des Jobs. Informationen zur Syntax finden Sie weiter unten.

description

Optional. Beschreibt Ihren Cronjob, der in der Google Cloud Console sichtbar ist.

timezone

Optional. Der Name der Zeitzone bzw. einer „zoneinfo”, die Sie für den Zeitplan Ihres Jobs verwenden möchten. Wenn Sie keine Zeitzone angeben, verwendet der Zeitplan UTC, was auch als GMT bezeichnet wird.

target

Optional. Der Name eines bestimmten Dienstes in der Anwendung. Wenn target angegeben ist, richtet der Cron-Dienst die Jobanfrage an diesen Dienst in Ihrer Anwendung. Die Jobanfragen werden an die Versionen im angegebenen Dienst weitergeleitet, die für den Traffic konfiguriert sind. Erfahren Sie, wie Anfragen weitergeleitet werden.

Wichtige Hinweise zu target:

• Wenn die Trafficaufteilung aktiviert ist, werden Ihre Jobanfragen nicht zwischen den von Ihnen konfigurierten Versionen aufgeteilt:
  • IP-Adressen-Aufteilung: Jobanfragen vom Cron-Dienst werden immer von der gleichen IP-Adresse gesendet und daher jedes Mal an die gleiche Version weitergeleitet
  • Cookie-Aufteilung: Jobanfragen enthalten kein Cookie und werden daher nicht an andere Versionen weitergeleitet
• Wenn Sie eine Weiterleitungsdatei verwenden, können Ihre Jobs umgeleitet werden, wenn die entsprechende URL auch in dispatch.yaml konfiguriert ist. Beispiel: Wenn die URL /tasks/hello_service2 sowohl in der Datei cron.yaml als auch in der Datei dispatch.yaml definiert ist, werden die Jobanfragen auch dann an service2 gesendet, wenn target: service1 angegeben ist:

  cron.yaml:

  cron:
  - description: "test dispatch vs target"
    url: /tasks/hello_service2
    schedule: every 1 mins
    target: service1

  dispatch.yaml:

  dispatch:
  - url: '*/tasks/hello_service2'
    service: service2

retry_parameters

Optional. Legt fest, wie fehlgeschlagene Jobs noch einmal ausgeführt werden. Informationen zur Syntax finden Sie weiter unten.

Cronjob-schedule definieren

Cronjobs werden in regelmäßigen Intervallen geplant und in einem einfachen Format angegeben, das dem Englischen ähnelt. In einem Zeitplan können Sie festlegen, ob der Job mehrmals am Tag oder an bestimmten Tagen und in bestimmten Monaten ausgeführt wird.

Intervalle von weniger als einem Tag

Legen Sie ein Intervall von weniger als einem Tag fest, um einen Job mehrmals täglich nach einem sich wiederholenden Zeitplan auszuführen. Sie können wahlweise ein Start- oder ein Endintervall definieren:

• Endintervall: Definiert die Zeit zwischen dem Ende eines Jobs und dem Beginn des nächsten Jobs, wobei das Ende der Zeitpunkt ist, an dem der Job abgeschlossen wurde oder eine Zeitüberschreitung aufgetreten ist. Bei dieser Art Intervall führt der Cron-Dienst Jobs innerhalb des 24-Stunden-Tages aus. Er beginnt dabei ein Intervall zur Erstellungs-/Aktualisierungszeit des Jobs und wartet zwischen den einzelnen Jobs, bis das angegebene Intervall abgelaufen ist.

  Beispiel: Beim Zeitplan every 5 minutes wird der Job täglich in Fünf-Minuten-Intervallen ausgeführt. Wird eine Instanz eines Jobs, der nach diesem Zeitplan ausgeführt wird, um 02:01 Uhr abgeschlossen, folgt eine Wartezeit von fünf Minuten, bevor um 02:06 Uhr die nächste Jobausführung beginnt.

• Startintervall: Definiert ein reguläres Zeitintervall, das angibt, wann der Cron-Dienst die einzelnen Jobs starten soll. Anders als beim Endintervall werden beim Startintervall die einzelnen Jobs unabhängig davon ausgeführt, wann der vorherige Job abgeschlossen oder beendet wurde. Sie können einen Zeitraum festlegen, innerhalb dessen Ihr Job ausgeführt werden soll, oder Jobs 24 Stunden am Tag ab Beginn des angegebenen Zeitraums ausführen.

  Da die Startzeit eines Jobs verbindlich ist, kann der Cron-Dienst einen Job überspringen, wenn die Ausführung einer Jobinstanz länger als das definierte Zeitintervall dauert. Eine individuelle Startzeit im Intervall kann übersprungen werden, wenn der vorherige Job nicht abgeschlossen oder das Zeitlimit überschritten wurde.

  Beispiel: Beim Zeitplan every 5 minutes from 10:00 to 14:00 beginnt der erste Job um 10:00 Uhr. Danach startet alle fünf Minuten ein Job. Wenn die Ausführung des ersten Jobs sieben Minuten dauert, wird der Job um 10:05 Uhr übersprungen und der Cron-Dienst führt bis 10:10 Uhr keine weiteren Instanzen dieses Jobs aus.

Benutzerdefiniertes Intervall

Sie können ein benutzerdefiniertes Intervall angeben, um einen Zeitplan zu definieren, in dem Ihr Job einmal pro Tag an einem oder mehreren ausgewählten Tagen und in einem oder mehreren ausgewählten Monaten ausgeführt wird. Nach einem benutzerdefinierten Zeitplan ausgeführte Jobs werden das ganze Jahr über nur zum festgelegten Zeitpunkt an den ausgewählten Tagen und in den ausgewählten Monaten ausgeführt.

Beispiel: Beim Zeitplan 1,2,3 of month 07:00 wird der Job jeweils einmal um 07:00 Uhr an den ersten drei Tagen jedes Monats ausgeführt.

Wichtige Hinweise zu schedule:

• Sie müssen festlegen, ob Sie ein untertägiges Intervall oder ein benutzerdefiniertes Intervall verwenden möchten. Die Elemente aus unterschiedlichen Intervalltypen können nicht miteinander kombiniert werden. Das folgende Beispiel stellt eine ungültige Zeitplandefinition dar: schedule: every 6 hours mon,wed,fri
• Es darf immer nur eine Instanz eines Jobs ausgeführt werden. Der Cron-Dienst ist darauf ausgelegt, „mindestens einmal” zu liefern. Wenn ein Job geplant ist, sendet App Engine die Jobanfrage mindestens einmal. In seltenen Fällen können auch mehrere Instanzen desselben Jobs angefragt werden. Daher sollte der Anfrage-Handler idempotent sein und der Code sollte sicherstellen, dass in diesem Fall keine nachteiligen Nebeneffekte auftreten.

schedule formatieren

Sie müssen das schedule-Element mithilfe der folgenden Syntax definieren, um den Beginn der Jobausführung anzugeben:

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Wählen Sie zum Definieren des schedule-Elements einen Intervalltyp aus:

Wiederholungsversuche angeben

Wenn der Anfrage-Handler eines Cronjobs einen Statuscode zurückgibt, der nicht im Bereich von 200 bis 299 (einschließlich) liegt, betrachtet App Engine den Job als fehlgeschlagen. Standardmäßig werden fehlgeschlagene Jobs nicht wiederholt. Fehlgeschlagene Jobs können wiederholt werden, indem Sie der Konfigurationsdatei den Block retry_parameters hinzufügen.

Hier sehen Sie ein Beispiel für eine cron.yaml-Datei mit nur einem Cronjob, der so konfiguriert ist, dass er bis zu fünfmal wiederholt wird, wobei eine Startverzögerung von 2,5 Sekunden vorgesehen ist, die sich jedes Mal verdoppelt.

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    job_retry_limit: 5
    min_backoff_seconds: 2.5
    max_doublings: 5

Syntax für Cron-Wiederholungsversuche

Die Wiederholungsparameter sind in der nachfolgenden Tabelle beschrieben.

Cron-Anfragen validieren

Sie können prüfen, ob Anfragen an Ihre Cron-URLs von App Engine oder von einer anderen Quelle stammen. Dazu validieren Sie einen HTTP-Header und die Quell-IP-Adresse für die Anfrage:

• Anfragen vom Cron-Dienst enthalten den folgenden HTTP-Header:

  "X-Appengine-Cron": "true"
  

  Dieser und weitere Header werden intern von App Engine festgelegt. Wenn ein Client diese Header sendet, werden sie aus der Anfrage entfernt.

• App Engine gibt Cron-Anfragen über die IP-Adresse 0.1.0.2 aus. Bei Cronjobs, die mit älteren gcloud-Versionen (vor Version 326.0.0) erstellt wurden, stammen Cron-Anfragen von 0.1.0.1.

Für die Java-Laufzeiten in Jetty oder Tomcat können Sie diese Validierung in einem Filter ausführen.

Zeitüberschreitung bei Anfrage

Weitere Informationen zu Zeitüberschreitungen bei Anfragen pro Umgebung und Skalierungstyp finden Sie unter App Engine-Umgebung auswählen.

Cronjobs hochladen

Zum Hochladen der Cronjobs müssen Sie cron.yaml als Parameter im folgenden gcloud-Befehl angeben:

gcloud app deploy cron.yaml

Cronjobs löschen

Zum Löschen aller Cronjobs ändern Sie die Datei cron.yaml so, dass sie nur Folgendes enthält:

cron:

Cron-Unterstützung in der Google Cloud Console

Sie können geplante Cronjobs in der Google Cloud Console auf der Seite „Cronjobs“ prüfen.

Sie können auch auf der Seite "Logs" prüfen, wann Cronjobs hinzugefügt oder entfernt wurden.