Pianificazione dei job con cron.yaml

Il servizio cron di App Engine consente di configurare attività pianificate regolarmente che operano a orari definiti o a intervalli regolari. Queste attività sono comunemente note come cron job. Questi cron job vengono attivati automaticamente dal servizio cron di App Engine. Ad esempio, potresti usare questo rapporto per inviare un'email con un rapporto su base giornaliera, per aggiornare alcuni dati memorizzati nella cache ogni 10 minuti o per aggiornare alcune informazioni di riepilogo una volta all'ora.

Un cron job richiama un URL utilizzando una richiesta GET HTTP soggetto agli stessi limiti di altre richieste HTTP.

Le applicazioni gratuite possono avere fino a 20 attività programmate. Le applicazioni a pagamento possono avere fino a 250 attività pianificate.

Per eseguire il deployment o aggiornare le pianificazioni, il tuo account richiede uno dei seguenti ruoli Identity and Access Management:

  • Proprietario
  • Editor

Puoi impostare l'autorizzazione nella pagina IAM in Google Cloud Console.

Informazioni sul file di configurazione cron

Un file cron.yaml nella directory principale dell'applicazione (insieme a app.yaml) configura le attività pianificate per l'applicazione .NET. Di seguito è riportato un file cron.yaml di esempio:

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

Il file cron.yaml utilizza la sintassi YAML e consiste di definizioni per ogni cron job. Una definizione di job deve avere url e schedule. Se vuoi, puoi anche specificare description, timezone, target e retry_parameters:

url
Obbligatorio. L'URL dell'app a cui vuoi che il servizio Cron invii richieste di job.
schedule
Obbligatorio. Definisce la pianificazione del momento in cui vuoi eseguire il job, consulta la sintassi che segue.
description
(Facoltativo) Descrive il cron job, visibile all'interno di Cloud Console.
timezone
(Facoltativo) Il nome del fuso orario, o "zoneinfo", che vuoi utilizzare per la tua pianificazione job. Se non specifichi un fuso orario, la pianificazione utilizza UTC, nota anche come GMT.
target
(Facoltativo) Il nome di un servizio specifico nella tua applicazione. Quando è specificato target, il servizio Cron sceglie come target la richiesta di lavoro per quel servizio nella tua applicazione. Le richieste di job vengono instradate alle versioni del servizio specificato configurate per il traffico. Scopri come vengono instradate le richieste.

Considerazioni importanti per target:

  • Se hai abilitato la suddivisione del traffico, le richieste di job non verranno divise tra le versioni configurate:
    • Suddivisione di indirizzi IP: le richieste di job del servizio Cron vengono sempre inviate dallo stesso indirizzo IP e, di conseguenza, vengono instradate ogni volta alla stessa versione.
    • Suddivisione dei cookie: le richieste di lavoro non includono un cookie con la richiesta, quindi non vengono instradate ad altre versioni.
  • Se utilizzi un file di invio, i job possono essere reindirizzati quando è configurato lo stesso URL anche in dispatch.yaml. Ad esempio, se l'URL /tasks/hello_service2 è definito in entrambi i file cron.yaml e dispatch.yaml seguenti, le richieste di job vengono inviate a service2, anche se target: service1 è specificato:

    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
(Facoltativo) Specifica di eseguire nuovamente i job non riusciti, consulta la sintassi di seguito.

Definizione del cron job schedule

I cron job vengono pianificati a intervalli ricorrenti e vengono specificati utilizzando un semplice formato simile all'inglese. Puoi definire una pianificazione in modo che il job venga eseguito più volte al giorno oppure in giorni e mesi specifici.

Intervalli sub-giornalieri

Utilizza un intervallo sub-giornaliero per eseguire un job più volte al giorno in base a una pianificazione ripetitiva. Puoi definire un intervallo di tempo di fine o un intervallo di tempo di inizio:

  • Intervallo di tempo di fine: definisce il tempo tra l'ora di fine di un job e il momento in cui viene avviato il job successivo, ovvero il momento in cui il job viene completato o il tempo di timeout. Il servizio Cron esegue job in questo tipo di intervallo nelle 24 ore del giorno, a partire da 00:00, e attende la durata specificata tra ogni job.

    Esempio: per la pianificazione every 5 minutes, il job viene eseguito ogni giorno utilizzando un intervallo di 5 minuti. Se un'istanza di un job in esecuzione in questa pianificazione viene completata alle 02:01, il job successivo attende 5 minuti e ricomincia alle 02:06.

  • Intervallo di tempo di avvio: definisce un intervallo di tempo regolare per l'avvio di ogni job da parte del servizio Cron. A differenza dell'intervallo di tempo di fine, l'intervallo di inizio viene eseguito a ogni job, indipendentemente dal completamento o dal timeout del job precedente. Puoi impostare un intervallo di tempo entro il quale vuoi che il job venga eseguito oppure eseguire job 24 ore al giorno, a partire dalle ore 00:00.

    Poiché l'ora di inizio di un job è rigida, se un'istanza di un job è più lunga dell'intervallo di tempo definito, il servizio Cron può saltare un job. Un singolo orario di inizio nell'intervallo può essere saltato se il job precedente non è stato completato o è stato timeout.

    Esempio: per la pianificazione every 5 minutes from 10:00 to 14:00, il primo job inizia a essere eseguito alle 10:00 e poi ogni 5 minuti. Se questo primo job viene eseguito per 7 minuti, il job 10:05 viene ignorato e, di conseguenza, il servizio Cron non esegue un'altra istanza di questo job fino al giorno 10:10.

Intervallo personalizzato

Puoi utilizzare un intervallo personalizzato per definire una pianificazione in cui il tuo job può essere eseguito una volta al giorno in uno o più giorni selezionati e in uno o più mesi selezionati. I job eseguiti su una pianificazione personalizzata vengono eseguiti tutto l'anno, solo nel momento specifico specificato nei giorni e nei mesi selezionati.

Esempio: per la pianificazione 1,2,3 of month 07:00, il job viene eseguito una volta alle 07:00 nei primi tre giorni di ogni mese.

Considerazioni importanti per schedule:

  • Devi decidere se utilizzare un intervallo sub-giornaliero o un intervallo personalizzato. Non puoi utilizzare combinazioni di elementi di vari tipi di intervallo. Di seguito è riportato un esempio di definizione di pianificazione non valida: schedule: every 6 hours mon,wed,fri.
  • Dovrebbe essere eseguita una sola istanza di un job alla volta. Il servizio Cron è progettato per fornire la distribuzione "almeno una volta", ovvero se un job è pianificato, App Engine invia la richiesta di job almeno una volta. In alcune rare casi, è possibile che venga richiesta più istanze dello stesso job, pertanto il gestore delle richieste deve essere idempotente e il codice deve assicurarsi che non si verifichino effetti collaterali dannosi.

Formattazione del file schedule

Per specificare quando viene eseguito il job, devi definire l'elemento schedule utilizzando la sintassi seguente:

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Scegli un tipo di intervallo per definire il tuo elemento schedule:

Intervallo di tempo di fine
  • [TIPO]: gli intervalli giornalieri devono includere il prefisso every.

    Esempio: schedule: every 12 hours

  • [INTERVAL_VALUE]: un valore intero e l'unità di tempo corrispondente. Valori validi per l'unità di tempo:
    • minutes o mins
    • hours
  • [INTERVAL_SCOPE]: non applicabile. Per impostare un'ora di inizio o un intervallo specifici in cui vuoi eseguire i job, consulta la sintassi per l'intervallo di inizio o Intervallo personalizzato.
Esempi di intervalli di fine
Usa i seguenti esempi per comprendere come definire pianificazioni job che utilizzano un intervallo di tempo di fine:
  • L'esecuzione inizia ogni giorno alle 00:00 e attende 5 minuti tra un job e l'altro. Al termine di ogni job, il servizio Cron attende 5 minuti prima di eseguire il job successivo: 
    schedule: every 5 minutes
  • Inizia ogni giorno alle 00:00 e attende 30 minuti tra un job e l'altro. Al termine di ogni job, il servizio Cron attende 30 minuti prima di eseguire il job successivo: 
    schedule: every 30 mins
Intervallo di inizio
  • [TIPO]: gli intervalli giornalieri devono includere il prefisso every.

    Esempio: schedule: every 12 hours

  • [INTERVAL_VALUE]: un valore intero e l'unità di tempo corrispondente. Valori validi per l'unità di tempo:
    • minutes o mins
    • hours
  • [INTERVAL_SCOPE] Specifica una clausola che corrisponde a [INTERVAL_VALUE]. Puoi definire un intervallo di tempo personalizzato o utilizzare l'opzione synchronized di 24 ore.
    • Includi la clausola from [HH:MM] to [HH:MM] per definire un'ora di inizio e un intervallo specifici in cui vuoi eseguire i job.

      Devi specificare i valori temporali nel formato 24 ore, HH:MM, dove:

      • HH sono numeri interi compresi tra 00 e 23.
      • MM sono numeri interi compresi tra 00 e 59.
    • Utilizza synchronized per specificare un intervallo di tempo di 24 ore (from 00:00 to 23:59) che viene diviso equamente per il valore [INTERVAL_VALUE].

      Importante: [INTERVAL_VALUE] deve dividere 24 in un numero intero, altrimenti si verifica un errore. I valori validi per [INTERVAL_VALUE] includono: 1, 2, 3, 4, 6, 8, 12 o 24.

Esempi di intervalli di inizio
Utilizza i seguenti esempi per comprendere come definire pianificazioni dei job che utilizzano un intervallo di tempo iniziale:
  • Esecuzione ogni 5 minuti dalle 10:00 alle 14:00, tutti i giorni: 
    schedule: every 5 minutes from 10:00 to 14:00
  • Esecuzione una volta ogni ora dalle 08:00 alle 16:00, tutti i giorni: 
    schedule: every 1 hours from 08:00 to 16:00
  • Viene eseguito una volta ogni due ore, ogni giorno a partire dalle 00:00: 
    schedule: every 2 hours synchronized
Intervallo personalizzato
  • [TIPO]: gli intervalli personalizzati possono includere il prefisso every per definire un intervallo ripetitivo oppure puoi definire un elenco specifico di giorni in un mese:
    • Per definire un intervallo ripetitivo puoi utilizzare il prefisso every.

      Esempi: 

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

    • Per definire giorni specifici, devi utilizzare i numeri ordinali. I valori validi vanno dal primo giorno del mese al numero massimo di giorni del mese, ad esempio:
      • 1st o first
      • 2nd o second
      • 3rd o third
      • E fino a: 31st o thirtyfirst

      Esempio: 

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

  • [INTERVAL_VALUE]: gli intervalli personalizzati includono un elenco dei giorni specifici in cui vuoi che il job venga eseguito. L'elenco deve essere definito in un elenco separato da virgole e può includere uno dei seguenti valori:
    • Il valore intero del giorno nel mese fino a un massimo di 31 giorni, ad esempio:
      • 1
      • 2
      • 3
      • E fino a: 31
    • Il nome del giorno in una combinazione di uno qualsiasi dei seguenti valori lunghi o abbreviati:
      • monday o mon
      • tuesday o tue
      • wednesday o wed
      • thursday o thu
      • friday o fri
      • saturday o sat
      • sunday o sun
      • Utilizza day per specificare tutti i giorni della settimana.

    Esempi: 

    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]: specifica una clausola che corrisponde al valore [INTERVAL_VALUE] specificato. Gli intervalli personalizzati possono includere la clausola of [MONTH], che specifica un singolo mese in un anno, o un elenco separato da virgole di più mesi. Devi anche definire un orario specifico per l'esecuzione del job, ad esempio: of [MONTH] [HH:MM].

    Per impostazione predefinita, se la clausola of è esclusa, l'intervallo personalizzato viene eseguito ogni mese.

    • [MONTH]: devi specificare i mesi in un elenco separato da virgole e puoi includere una combinazione dei seguenti valori lunghi o abbreviati:
      • january o jan
      • february o feb
      • march o mar
      • april o apr
      • may
      • june o jun
      • july o jul
      • august o aug
      • september o sep
      • october o oct
      • november o nov
      • december o dec
      • Utilizza month per specificare tutti i mesi dell'anno.
    • [HH:MM]: devi specificare i valori temporali nel formato 24 ore, HH:MM, dove:
      • HH sono numeri interi compresi tra 00 e 23.
      • MM sono numeri interi compresi tra 00 e 59.

      • Esempio: 

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

Esempi di intervalli personalizzati
Usa i seguenti esempi per comprendere come definire pianificazioni dei job che utilizzano un intervallo personalizzato:
  • Esecuzione ogni giorno alle 00:00: 
    schedule: every day 00:00
  • Esecuzione ogni lunedì alle 09:00: 
    schedule: every monday 09:00
  • Esecuzione una volta il secondo mercoledì di marzo alle 17:00: 
    schedule: 2nd wednesday of march 17:00
  • Esecuzione sei volte a maggio. Durante le prime due settimane, viene eseguito una volta ogni lunedì, mercoledì e venerdì alle ore 10:00: 
    schedule: 1st,second mon,wed,fri of may 10:00
  • Viene eseguito una volta alla settimana. Ogni sette giorni a partire dal primo giorno di ogni mese, viene eseguito una volta alle 09:00: 
    schedule: 1,8,15,22 of month 09:00
  • Esecuzione ogni due settimane. Il primo e il terzo lunedì di ogni mese, viene eseguito una volta alle 04:00: 
    schedule: 1st,third monday of month 04:00
  • Viene eseguito tre volte l'anno. Il primo lunedì di settembre, ottobre e novembre, viene eseguito una volta alle 09:00: 
    schedule: 1st monday of sep,oct,nov 09:00
  • Viene eseguito una volta ogni trimestre. Il primo giorno di gennaio, aprile, luglio e ottobre, viene eseguito una volta alle 00:00: 
    schedule: 1 of jan,april,july,oct 00:00

Specifica dei nuovi tentativi

Se un gestore di richieste di cron job restituisce un codice di stato che non è compreso nell'intervallo 200-299 (inclusi) App Engine considera che il job non è riuscito. Per impostazione predefinita, i job non riusciti non vengono eseguiti di nuovo. Puoi causare un nuovo tentativo di job non riusciti includendo un blocco retry_parameters nel file di configurazione.

Di seguito è riportato un esempio di file cron.yaml che contiene un singolo cron job configurato per riprovare fino a cinque volte (valore predefinito) con un backoff iniziale di 2,5 secondi che raddoppia ogni volta.

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

Sintassi dei tentativi cron

I parametri relativi ai nuovi tentativi sono descritti nella tabella riportata di seguito.

Elemento Descrizione
job_retry_limit Un numero intero che rappresenta il numero massimo di nuovi tentativi per un cron job non riuscito. Il valore minimo è 0, quello massimo è 5. Se specifichi anche job_age_limit, App Engine ritenta il cron job finché non raggiunge entrambi i limiti. Il valore predefinito per job_retry_limit è 5.
job_age_limit Il limite di tempo per ritentare un cron job non riuscito, misurato dalla prima esecuzione del cron job. Il valore è un numero seguito da un'unità di tempo, in cui l'unità è s per secondi, m per minuti, h per ore o d per giorni. Ad esempio, il valore 5d specifica un limite di cinque giorni dopo il primo tentativo di esecuzione del cron job. Se specifichi anche job_retry_limit, App Engine ritenta il cron job fino a raggiungere entrambi i limiti.
min_backoff_seconds Numero minimo di secondi di attesa prima di riprovare un cron job in seguito.
max_backoff_seconds Il numero massimo di secondi di attesa prima di riprovare un job cron dopo un errore.
max_doublings Il numero massimo di volte in cui l'intervallo tra i nuovi tentativi cron job non riusciti verrà raddoppiato prima che l'aumento diventi costante. La costante è: 2**(max_doublings - 1) * min_backoff.

Convalida di richieste cron

Potresti verificare che le richieste ai tuoi cron URL provengano da App Engine e non da un'altra origine. Per farlo, convalida un'intestazione HTTP e l'indirizzo IP di origine per la richiesta:

  • Le richieste del servizio Cron conterranno la seguente intestazione HTTP:

    X-Appengine-Cron: true

    Questa e altre intestazioni vengono impostate internamente da App Engine. Se un client invia queste intestazioni, queste vengono rimosse dalla richiesta.

  • App Engine emette richieste cron dall'indirizzo IP 0.1.0.2. Per i cron job creati con versioni gcloud precedenti (precedenti alla 326.0.0), le richieste cron provengono da 0.1.0.1.

Caricamento di cron job

Per caricare i cron job, devi specificare cron.yaml come parametro per il seguente comando gcloud:

gcloud beta app deploy cron.yaml

Eliminazione dei cron job

Per eliminare tutti i cron job, modifica il file cron.yaml in modo che contenga solo:

cron:

Supporto di cron in Google Cloud Console

Puoi controllare i cron job pianificati nella pagina dei job Chrome di Cloud Console.

Puoi anche visitare la pagina Log per vedere quando sono stati aggiunti o rimossi cron job.