Referenz zu cron.yaml

Mit der Datei cron.yaml können Sie geplante Aufgaben für Ihre Anwendung definieren.

Weitere Informationen zum Planen von Aufgaben, z. B. zum Testen, Bereitstellen oder Löschen von Cronjobs, finden Sie unter Aufgaben mit Cron planen.

Beispiel

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

Syntax

Die Datei cron.yaml sollte sich neben der Datei app.yaml im Stammverzeichnis Ihrer Anwendung befinden: cron.yaml konfiguriert geplante Aufgaben für Ihre PHP 2-Anwendung.

Weitere Informationen zum YAML-Format finden Sie auf der YAML-Website.

Definitionen von Cronjobs

Element Beschreibung
description Optional. Die Beschreibung wird in der Google Cloud Console und in der Verwaltungsoberfläche des Entwicklungsservers angezeigt. Schließen Sie den Beschreibungswert in Anführungszeichen ein.
retry_parameters Optional. Wenn der Anfrage-Handler eines Cronjobs einen HTTP-Statuscode zurückgibt, der nicht (einschließlich) im Bereich von 200 bis 299 liegt, betrachtet App Engine den Job als fehlgeschlagen. Fehlgeschlagene Jobs werden standardmäßig nicht wiederholt. Wenn Sie veranlassen möchten, dass fehlgeschlagene Jobs wiederholt werden, fügen Sie einen Block mit Wiederholungsparametern in Ihre Konfigurationsdatei ein.

Weitere Informationen finden Sie im Abschnitt Cron-Wiederholungsversuche.

schedule Erforderlich. Definiert den Zeitplan für die Ausführung des Cronjobs, siehe Syntax unten.
target

Der String target wird dem Hostnamen Ihrer Anwendung vorangestellt. Dies ist normalerweise der Name eines Dienstes. Der Cronjob wird an die für Traffic konfigurierte Version des benannten Dienstes weitergeleitet.

Wenn der für target angegebene Dienstname nicht zu finden ist, wird die Cron-Anfrage entweder zum Dienst default oder zu der Version der Anwendung weitergeleitet, die für den Erhalt von Traffic konfiguriert wurde. Weitere Informationen zum Routing finden Sie unter Anfragerouting.

Wenn Sie eine Weiterleitungsdatei verwenden, wird Ihr Job unter Umständen umgeleitet. Bei der folgenden cron.yaml- und dispatch.yaml-Datei wird der Job beispielsweise in service2 ausgeführt, obwohl das Ziel service1 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
timezone Für timezone sollte der Name einer zoneinfo-Standardzeitzone festgelegt werden. Wenn Sie keine Zeitzone angeben, wird der Zeitplan in UTC (auch als GMT bezeichnet) erstellt.
url Erforderlich. Das Feld url gibt eine URL in Ihrer Anwendung an, die vom Cron-Dienst aufgerufen wird. Weitere Informationen finden Sie unter URLs für Cron sichern.

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 den Zeitraum zwischen dem Ende eines Jobs und dem Beginn des nächsten Jobs. Dabei ist das Ende der Zeitpunkt, zu dem der Job abgeschlossen oder das Zeitlimit überschritten wurde. Bei dieser Art Intervall führt der Cron-Dienst Jobs innerhalb des 24-Stunden-Tages aus, der um 00:00 Uhr beginnt, und wartet zwischen den einzelnen Jobs, bis die angegebene Zeitspanne 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 00:00 Uhr 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:
  • Beginnt jeden Tag um 00:00 Uhr; zwischen den einzelnen Jobs wird fünf Minuten lang gewartet. Nach der Beendigung eines Jobs wartet der Cron-Dienst fünf Minuten, bevor der nächste Job ausgeführt wird: 
    schedule: every 5 minutes
  • Beginnt jeden Tag um 00:00 Uhr; zwischen den einzelnen Jobs wird 30 Minuten lang gewartet. 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 einmal um 00:00 Uhr: 
    schedule: 1 of jan,april,july,oct 00:00

Cron-Wiederholungsversuche

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 eine cron.yaml-Beispieldatei mit nur einem Cronjob, der so konfiguriert ist, dass er bis zu fünfmal (Standard) 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:
    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 Die maximale Anzahl der Wiederholungsversuche für einen fehlgeschlagenen Cronjob, die "5" nicht überschreiten darf. Wenn job_age_limit ebenfalls angegeben wurde, wiederholt App Engine den Cronjob, bis beide Limits erreicht sind. Wenn der Parameter ausgelassen wird, gilt standardmäßig der Grenzwert "5".
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. Zum Beispiel gibt der Wert 5d ein Limit von fünf Tagen ab dem ersten Ausführungsversuch des Cronjobs an. Wenn job_retry_limit ebenfalls angegeben wurde, 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

Anfrageheader

Anfragen vom Cron-Dienst enthalten einen HTTP-Header:

X-Appengine-Cron: true

Dieser und andere Header werden intern von App Engine festgelegt. Wenn ein Client diese Header sendet, werden sie aus der Anfrage entfernt. Eine Ausnahme bilden Anfragen von angemeldeten Administratoren der Legacy-Anwendung, die den Header für Testzwecke festlegen dürfen.

Ausgangs-IP-Adresse

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.

Zeitüberschreitung bei Anfrage

Die Zeitüberschreitung der Cron-Anfrage hängt von dem Skalierungstyp ab, der für Ihre Anwendung konfiguriert ist:

Autoscaling
Zeitüberschreitung bei Anfrage – 10 Minuten.
Einfache Skalierung und manuelle Skalierung
Zeitüberschreitung bei Anfrage – 24 Stunden.

Weitere Informationen finden Sie unter Instanzen verwalten.

Limits

Für kostenlose Anwendungen sind bis zu 20 geplante Aufgaben zulässig. Kostenpflichtige Anwendungen können bis zu 250 geplante Aufgaben enthalten.