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:

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:

Endintervall
  • [TYPE]: Tägliche Intervalle müssen das Präfix every enthalten.

    Beispiel: schedule: every 12 hours

  • [INTERVAL_VALUE]: Ein ganzzahliger Wert und die entsprechende Zeiteinheit. Gültige Werte für die Zeiteinheit:
    • minutes oder mins
    • hours
  • [INTERVAL_SCOPE]: Nicht zutreffend. Informationen dazu, wie Sie eine bestimmte Startzeit oder einen bestimmten Zeitraum für die Ausführung von Jobs festlegen, finden Sie im Abschnitt zur Syntax für das Startintervall oder für das benutzerdefinierte Intervall.
Beispiele für Endintervalle
Die folgenden Beispiele veranschaulichen, wie Sie Jobzeitpläne mit einem Endintervall definieren:
  • Wartet nach der Bereitstellung 5 Minuten, bevor die Ausführung zum ersten Mal erfolgt. Nach der Beendigung eines Jobs wartet der Cron-Dienst 5 Minuten, bevor der nächste Job ausgeführt wird: 
    schedule: every 5 minutes
  • Wartet nach der Bereitstellung 30 Minuten, bevor die Ausführung zum ersten Mal erfolgt. Nach der Beendigung eines Jobs wartet der Cron-Dienst 30 Minuten, bevor der nächste Job ausgeführt wird: 
    schedule: every 30 mins
Startintervall
  • [TYPE]: Tägliche Intervalle müssen das Präfix every enthalten.

    Beispiel: schedule: every 12 hours

  • [INTERVAL_VALUE]: Ein ganzzahliger Wert und die entsprechende Zeiteinheit. Gültige Werte für die Zeiteinheit:
    • minutes oder mins
    • hours
  • [INTERVAL_SCOPE]: Gibt eine Klausel an, die [INTERVAL_VALUE] entspricht. Sie können einen benutzerdefinierten Zeitraum definieren oder die 24-Stunden-Option synchronized verwenden.
    • Fügen Sie die Klausel from [HH:MM] to [HH:MM] ein, um eine bestimmte Startzeit und einen bestimmten Bereich zu definieren, in dem Sie Jobs ausführen möchten.

      Sie müssen die Zeitwerte im 24-Stunden-Format HH:MM angeben. Dabei gilt:

      • HH ist eine ganze Zahl im Bereich von 00 bis 23.
      • MM ist eine ganze Zahl im Bereich von 00 bis 59.
    • Verwenden Sie synchronized, um einen 24-Stunden-Zeitraum (from 00:00 to 23:59) festzulegen, der gleichmäßig durch den Wert [INTERVAL_VALUE] dividiert wird.

      Wichtig: [INTERVAL_VALUE] muss 24 in eine ganze Zahl teilen, sonst tritt ein Fehler auf. Gültige Werte für [INTERVAL_VALUE] sind 1, 2, 3, 4, 6, 8, 12 und 24.

Beispiele für Startintervalle
Die folgenden Beispiele zeigen, wie Sie Jobzeitpläne mit einem Startintervall definieren:
  • Wird täglich von 10:00 bis 14:00 Uhr alle fünf Minuten ausgeführt: 
    schedule: every 5 minutes from 10:00 to 14:00
  • Wird täglich von 08:00 bis 16:00 Uhr einmal pro Stunde ausgeführt: 
    schedule: every 1 hours from 08:00 to 16:00
  • Wird täglich ab 00:00 Uhr alle zwei Stunden ausgeführt: 
    schedule: every 2 hours synchronized
Benutzerdefiniertes Intervall
  • [TYPE]: Benutzerdefinierte Intervalle können das Präfix every enthalten, um Wiederholungsintervalle zu definieren. Sie können auch eine bestimmte Auswahl von Tagen in einem Monat definieren:
    • Zum Definieren eines Wiederholungsintervalls kann das Präfix every verwendet werden.

      Beispiele: 

      schedule: every day 00:00
schedule: every monday 09:00

    • Zum Definieren von bestimmten Tagen müssen Sie Ordnungszahlen verwenden. Gültige Werte reichen vom ersten Tag eines Monats bis zur maximalen Anzahl von Tagen in diesem Monat. Beispiel:
      • 1st oder first
      • 2nd oder second
      • 3rd oder third
      • Und bis 31st oder thirtyfirst

      Beispiel: 

      schedule: 1st,3rd tuesday
schedule: 2nd,third wednesday of month 09:00

  • [INTERVAL_VALUE]: Benutzerdefinierte Intervalle umfassen eine Liste der Tage, an denen der Job ausgeführt werden soll. Es muss sich um eine durch Kommas getrennte Liste handeln. Sie kann einen der folgenden Werte enthalten:
    • Den ganzzahligen Wert des Tages im Monat bis maximal 31, zum Beispiel:
      • 1
      • 2
      • 3
      • Und bis 31
    • Den Namen des Tages in einer Kombination aus den folgenden langen oder abgekürzten Werten:
      • monday oder mon
      • tuesday oder tue
      • wednesday oder wed
      • thursday oder thu
      • friday oder fri
      • saturday oder sat
      • sunday oder sun
      • Mit day geben Sie alle Wochentage an.

    Beispiele:

    schedule: 2nd monday,thu
schedule: 1,8,15,22 of month 09:00
schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00

  • [INTERVAL_SCOPE]: Gibt eine Klausel an, die [INTERVAL_VALUE] entspricht. Benutzerdefinierte Intervalle können die Klausel of [MONTH] enthalten, die einen bestimmten Monat in einem Jahr angibt, oder eine durch Kommas getrennte Liste mit mehreren Monaten. Sie müssen außerdem eine Uhrzeit für die Ausführung des Jobs angeben, z. B. of [MONTH] [HH:MM].

    Standardmäßig wird das benutzerdefinierte Intervall jeden Monat ausgeführt, wenn die Klausel of ausgeschlossen wird.

    • [MONTH]: Sie müssen die Monate in einer durch Kommas getrennten Liste angeben. Sie können eine Kombination aus den folgenden langen oder abgekürzten Werten verwenden:
      • january oder jan
      • february oder feb
      • march oder mar
      • april oder apr
      • may
      • june oder jun
      • july oder jul
      • august oder aug
      • september oder sep
      • october oder oct
      • november oder nov
      • december oder dec
      • Mit month geben Sie alle Monate im Jahr an.
    • [HH:MM]: Geben Sie die Zeitwerte im 24-Stunden-Format HH:MM an. Dabei gilt:
      • HH ist eine ganze Zahl zwischen 00 und 23.
      • MM ist eine ganze Zahl im Bereich von 00 bis 59.

      • Beispiel:

      schedule: 1st monday of sep,oct,nov 09:00
schedule: 1 of jan,april,july,oct 00:00

Beispiele für benutzerdefinierte Intervalle
Die folgenden Beispiele veranschaulichen, wie Sie Jobzeitpläne mit einem benutzerdefinierten Intervall definieren:
  • Wird jeden Tag um 00:00 Uhr ausgeführt: 
    schedule: every day 00:00
  • Wird jeden Montag um 09:00 Uhr ausgeführt: 
    schedule: every monday 09:00
  • Wird einmal am zweiten Mittwoch im März um 17:00 Uhr ausgeführt: 
    schedule: 2nd wednesday of march 17:00
  • Wird sechsmal im Mai ausgeführt. Während der ersten zwei Wochen erfolgt die Ausführung jeden Montag, Mittwoch und Freitag um 10:00 Uhr: 
    schedule: 1st,second mon,wed,fri of may 10:00
  • Wird einmal pro Woche ausgeführt. Die Ausführung erfolgt alle sieben Tage ab dem ersten Tag jedes Monats um 09:00 Uhr: 
    schedule: 1,8,15,22 of month 09:00
  • Wird jede zweite Woche ausgeführt. Die Ausführung erfolgt jeden Monat an jedem ersten und dritten Montag um 04:00 Uhr: 
    schedule: 1st,third monday of month 04:00
  • Wird dreimal pro Jahr ausgeführt. Die Ausführung erfolgt am ersten Montag im September, Oktober und November um 09:00 Uhr: 
    schedule: 1st monday of sep,oct,nov 09:00
  • Wird einmal pro Quartal ausgeführt. Die Ausführung erfolgt am ersten Tag im Januar, April, Juli und Oktober um 00:00 Uhr: 
    schedule: 1 of jan,april,july,oct 00:00

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.

Element Beschreibung
job_retry_limit Eine Ganzzahl für die maximale Anzahl an Wiederholungsversuchen für einen fehlgeschlagenen Cronjob. Der Wert muss zwischen 0 und dem maximalen Wert 5 liegen. Wenn Sie job_age_limit festlegen, wiederholt App Engine den Cronjob, bis beide Limits erreicht sind. Der Standardwert für job_retry_limit ist 0.
job_age_limit Das Zeitlimit für die Wiederholung eines fehlgeschlagenen Cronjobs, gemessen ab dem Zeitpunkt der ersten Ausführung des Cronjobs. Der Wert ist eine Zahl, auf die eine Zeiteinheit folgt: s für Sekunden, m für Minuten, h für Stunden oder d für Tage. Beispielsweise wird durch den Wert 5d ein Limit von fünf Tagen ab dem ersten Ausführungsversuch des Cronjobs festgelegt. Wenn Sie auch job_retry_limit angeben, wiederholt App Engine den Cronjob, bis beide Limits erreicht sind.
min_backoff_seconds Die Mindestwartezeit in Sekunden, bevor die Ausführung eines Cronjobs nach einem Fehlversuch wiederholt wird.
max_backoff_seconds Die maximale Wartezeit in Sekunden, bevor die Ausführung eines Cronjobs nach einem Fehlversuch wiederholt wird.
max_doublings Die maximale Häufigkeit, mit der das Intervall zwischen fehlgeschlagenen Cronjob-Wiederholungen verdoppelt wird, bevor die Erhöhung konstant wird. Die Konstante lautet: 2**(max_doublings - 1) * min_backoff.

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

Das Zeitlimit für Cron-Anfragen beträgt 60 Minuten.

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.