Pianificazione dei job con cron.yaml

Il servizio Cron di App Engine consente di configurare regolarmente attività eseguite in orari specifici o a intervalli regolari. Queste attività sono comunemente chiamate cron job. Questi cron job vengono attivati automaticamente dal servizio cron di App Engine. Ad esempio, potresti utilizzarlo per inviare di inviare un'email con il report ogni giorno, per aggiornare alcuni dati memorizzati nella cache ogni 10 o aggiornare alcune informazioni di riepilogo una volta all'ora.

Un cron job esegue una richiesta HTTP GET pianificata all'endpoint specificato nella nella stessa app in cui è configurato il cron job. Il gestore per quell'endpoint esegue la logica quando viene richiamata.

Impossibile utilizzare il servizio Cron di App Engine per chiamare endpoint web al di fuori dell'app host di App Engine. Non può essere utilizzato per chiamare App Engine endpoint di altre app oltre all'app host.

Le richieste di cron job soggetto agli stessi limiti degli altri HTTP richieste di Google. Le applicazioni gratuite possono avere fino a 20 attività pianificate. Le applicazioni a pagamento possono avere fino a 250 attività pianificate.

Per eseguire il deployment o l'aggiornamento delle pianificazioni, il tuo account richiede uno dei seguenti ruoli Identity and Access Management:

Puoi impostare l'autorizzazione nella Pagina IAM nella console Google Cloud.

Informazioni sul file di configurazione cron

Per tutti i runtime, ad eccezione di Java, un file cron.yaml nella directory radice dell'applicazione (insieme a app.yaml) configura le attività pianificate per l'app.

Per Java, un file cron.yaml nel file WEB-INF directory della tua applicazione (insieme a app.yaml) configura le attività pianificate per la tua app.

Di seguito è riportato un esempio di file cron.yaml:

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 l'elemento Sintassi YAML ed è composto da definizioni per ciascuno dei tuoi cron job. Una definizione di job deve avere un url e un schedule. Se vuoi, puoi anche specificare description, timezone, target e retry_parameters:

url
Obbligatorio. L'URL nell'app a cui vuoi che il servizio Cron invii le richieste di lavoro.
schedule
Obbligatorio. Definisce la pianificazione dell'esecuzione del job. Consulta la sintassi riportata di seguito.
description
Facoltativa. Descrive il cron job, che è visibile dall'interno Console Google Cloud e l'interfaccia di amministrazione del server di sviluppo locale.
timezone
(Facoltativo) Il nome del fuso orario o "zoneinfo" da utilizzare per la pianificazione dei job. Se non specifichi un fuso orario, la programmazione utilizza UTC, conosciuto anche comeGMT.
target
Facoltativa. Il nome di un servizio specifico nella tua app. Quando viene specificato target, il servizio Cron indirizza la richiesta di job a quel servizio nella tua app. Le richieste di job vengono inoltrate alle versioni del servizio specificato configurate per il traffico. Scopri come vengono indirizzate le richieste.

Considerazioni importanti per target:

  • Se hai attivato la suddivisione del traffico, le richieste di job non verranno suddivise tra le versioni che hai configurato:
    • Suddivisione degli indirizzi IP: le richieste di job dal servizio Cron vengono sempre inviate dallo stesso indirizzo IP e, di conseguenza, vengono indirizzate allo stesso la versione precedente ogni volta.
    • Suddivisione dei cookie: le richieste di job non includono un cookie con il valore e, di conseguenza, non vengono indirizzati ad altre versioni.
  • Se utilizzi un di invio, i job possono essere reindirizzati quando viene visualizzato lo stesso URL. configurato in dispatch.yaml. Ad esempio, se L'URL /tasks/hello_service2 è definito in entrambi i campi persone che segui cron.yaml e dispatch.yaml file, le richieste di job vengono inviate a service2, 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 qui sotto.

Definizione del cron job schedule

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

Intervalli subgiornalieri

Utilizza un intervallo giornaliero secondario per eseguire un job più volte al giorno programmazione. Puoi definire un intervallo di fine o un intervallo di inizio:

  • Intervallo di fine: definisce il periodo di tempo che intercorre tra l'"ora di fine". di un job e all'avvio del job successivo, dove l'"ora di fine" è in cui il job viene completato volte di Google. Il servizio Cron esegue i job in questo tipo di intervallo nelle 24 ore giorno, iniziando un intervallo dopo l'ora di creazione/aggiornamento del job e attende per l'intervallo specificato tra un job e l'altro.

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

  • Intervallo di inizio: definisce un intervallo di tempo regolare per l'avvio di ogni job da parte del servizio Cron. A differenza del di fine, l'intervallo di inizio esegue ogni job indipendentemente quando il job precedente viene completato o scade. Puoi impostare un intervallo di tempo all'interno che vuoi venga eseguito dal job o eseguire job 24 ore al giorno, a partire da l'inizio dell'intervallo di tempo specificato.

    Poiché l'ora di inizio di un job è rigorosa, se un'istanza di un job viene eseguita più a lungo dell'intervallo di tempo definito, il servizio Cron può saltare un job. È possibile saltare una singola ora di inizio nell'intervallo se un job precedente non è stato completato volte di Google.

    Esempio: per every 5 minutes from 10:00 to 14:00 pianificazione, l'esecuzione del primo job inizia alle ore 10:00 e poi ogni 5 minuti. Se il 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 job può essere eseguito una volta al giorno in uno o più giorni selezionati e in uno o più mesi. I job eseguiti in base a una pianificazione personalizzata vengono eseguiti tutto l'anno, solo alla un orario specifico nei giorni e nei mesi selezionati.

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

Considerazioni importanti per schedule:

  • Devi decidere se utilizzare un intervallo inferiore a un giorno o un intervallo personalizzato. Non puoi combinare e utilizzare elementi dei vari intervalli di testo. Di seguito è riportato un esempio di definizione di pianificazione non valida: schedule: every 6 hours mon,wed,fri.
  • In qualsiasi momento deve essere eseguita una sola istanza di un job. Il servizio Cron è progettato per fornire la consegna "almeno una volta", ovvero se un job è pianificato, App Engine invia la richiesta di job almeno una volta. In alcune rare circostanze è possibile che vengano richieste più istanze dello stesso job, pertanto il gestore delle richieste deve essere idempotente e il codice deve garantire che non si verifichino effetti collaterali dannosi in questo caso.

Formattazione di schedule

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

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Scegli un tipo di intervallo per definire l'elemento schedule:

Intervallo di tempo di fine
  • [TYPE]: gli intervalli giornalieri devono includere every .

    Esempio: schedule: every 12 hours

  • [INTERVAL_VALUE]: un valore intero e l'unità di misura corrispondente. Valori validi per l'unità di tempo:
    • minutes o mins
    • hours
  • [INTERVAL_SCOPE]: non applicabile. Per impostare un'ora di inizio specifica entro l'intervallo in cui vuoi eseguire i job, consulta la sintassi Intervallo di inizio oppure Intervallo personalizzato.
Esempi di intervallo di tempo di fine
Utilizza i seguenti esempi per capire come definire le pianificazioni dei job che utilizzano un intervallo di ora di fine:
  • Attende 5 minuti dopo il deployment per l'esecuzione la prima volta. Al termine di ogni job, il servizio Cron attende 5 minuti prima di eseguire il job successivo: 
    schedule: every 5 minutes
  • Attende 30 minuti dopo il deployment per la prima esecuzione. Dopo il giorno ogni job termina, il servizio Cron attende 30 minuti prima di eseguire job successivo: 
    schedule: every 30 mins
Intervallo di inizio
  • [TYPE]: gli intervalli giornalieri devono includere every .

    Esempio: schedule: every 12 hours

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

      Devi specificare i valori di tempo 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.
    • Usa synchronized per specificare un intervallo di 24 ore (from 00:00 to 23:59) in modo uniforme diviso 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 capire come definire il job programmazioni che utilizzano un intervallo di inizio:
  • In esecuzione ogni 5 minuti dalle 10:00 alle 14:00, tutti i giorni: 
    schedule: every 5 minutes from 10:00 to 14:00
  • Viene eseguito una volta ogni ora dalle 08:00 alle 16:00, ogni giorno: 
    schedule: every 1 hours from 08:00 to 16:00
  • Eseguito una volta ogni due ore, tutti i giorni a partire dalle ore 00:00: 
    schedule: every 2 hours synchronized
Intervallo personalizzato
  • [TYPE]: 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 metodo Prefisso every.

      Esempi: 

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

    • Per definire giorni specifici, devi utilizzare i numeri ordinali. Valido valori vanno dal primo giorno di un mese, fino al valore massimo numero di giorni di quel 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 venga eseguito il job. L'elenco deve essere definito in un elenco separato da virgole e può includere uno dei seguenti valori:
    • Il valore intero del giorno del mese fino a un massimo di 31 giorni, ad esempio:
      • 1
      • 2
      • 3
      • E fino a: 31
    • Il nome del giorno in una combinazione dei seguenti elementi valori abbreviati:
      • monday o mon
      • tuesday o tue
      • wednesday o wed
      • thursday o thu
      • friday o fri
      • saturday o sat
      • sunday o sun
      • Usa 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 alla specificato [INTERVAL_VALUE]. 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'ora specifica in cui vuoi che venga eseguito il job, ad esempio: of [MONTH] [HH:MM].

    Per impostazione predefinita, se la clausola of è esclusa, il parametro personalizzato viene eseguito ogni mese.

    • [MONTH]: devi specificare i mesi in un elenco separato da virgole e può 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 dell'ora nel formato 24 ore. HH:MM, dove:
      • HH sono numeri interi compresi tra 00 e 23.
      • MM sono numeri interi da 00 a 59.

      • Esempio: 

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

Esempi di intervalli personalizzati
Utilizza i seguenti esempi per capire come definire le pianificazioni dei job che utilizzano un intervallo personalizzato:
  • Viene eseguito ogni giorno alle ore 00:00: 
    schedule: every day 00:00
  • Viene eseguito ogni lunedì alle 09:00: 
    schedule: every monday 09:00
  • Verrà eseguita una volta il secondo mercoledì di marzo alle ore 17:00: 
    schedule: 2nd wednesday of march 17:00
  • Viene pubblicato sei volte a maggio. Durante le prime due settimane, viene pubblicato 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 eseguita una volta alle 09:00: 
    schedule: 1,8,15,22 of month 09:00
  • Eseguita a settimane alterne. Il primo e il terzo lunedì di ogni mese, viene eseguita una volta alle 04:00: 
    schedule: 1st,third monday of month 04:00
  • Viene eseguito tre volte all'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
  • Eseguita 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

Specificare i nuovi tentativi

Se il gestore delle richieste di un job cron restituisce un codice di stato non compreso tra 200 e 299 (inclusi), App Engine considera il job non riuscito. Per impostazione predefinita, i job non riusciti non vengono riprovati. Puoi fare in modo che i job non riusciti vengano riprovati includendo un blocco retry_parameters nel file di configurazione.

Ecco un file cron.yaml di esempio contenente un singolo cron job configurato riprova fino a cinque volte con un backoff iniziale di 2,5 secondi raddoppia ogni volta.

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

Sintassi delle ripetizioni cron

I parametri per i nuovi tentativi sono descritti nella tabella seguente.

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 e il valore massimo è 5. Se specifichi anche job_age_limit, App Engine riprova il cron job fino a quando non raggiunge entrambi i limiti. Il valore predefinito per job_retry_limit è 0.
job_age_limit Il limite di tempo per il nuovo tentativo di un cron job non riuscito, misurato dal momento in cui viene eseguita per la prima volta il cron job. Il valore è un numero seguito da un'unità di volta, dove l'unità è sper i secondi, mper 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 job cron. Se specifichi anche job_retry_limit, App Engine riprova il cron job fino a quando non raggiunge entrambi i limiti.
min_backoff_seconds Il numero minimo di secondi da attendere prima di riprovare un job cron dopo che non è riuscito.
max_backoff_seconds Il numero massimo di secondi di attesa prima di riprovare un job cron dopo che non è riuscito.
max_doublings Il numero massimo di volte in cui l'intervallo tra un cron job non riuscito il numero di nuovi tentativi sarà raddoppiato prima che l'aumento diventi costante. La costante è: 2**(max_doublings - 1) * min_backoff.

Convalida delle richieste cron

Ti consigliamo di verificare che le richieste agli URL cron provengano da App Engine e non da un'altra origine. Puoi farlo convalidando un'intestazione HTTP e l'indirizzo IP di origine della richiesta:

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

    "X-Appengine-Cron": "true"

    Questo e altri intestazioni vengono impostati internamente da App Engine. Se un client invia queste intestazioni, vengono rimosse dalla richiesta.

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

Per i runtime Java, in Jetty o Tomcat, puoi eseguire questa convalida in una filtro.

Timeout richiesta

Il timeout della richiesta cron dipende dal tipo di scalabilità configurato per la tua app:

Scalabilità automatica
Timeout della richiesta di 10 minuti.
Scalabilità di base e scalabilità manuale
Timeout della richiesta di 24 ore.

Per saperne di più, consulta Come vengono gestite le istanze.

Per ulteriori informazioni sui timeout delle richieste per ambiente e sulla scalabilità consulta Scegliere un ambiente App Engine.

Caricamento dei cron job

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

gcloud 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 nella console Google Cloud

Puoi controllare i cron job pianificati nella console Google Cloud Pagina dei job Cron.

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