Pianificazione dei job con cron.yaml

Il servizio cron di App Engine consente di configurare attività programmate regolarmente che operano in 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, puoi utilizzarlo per inviare giornalmente un'email con il report, aggiornare alcuni dati memorizzati nella cache ogni 10 minuti o aggiornare alcune informazioni di riepilogo una volta all'ora.

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

Non è possibile 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 gli endpoint di App Engine da altre app diverse dall'app host.

Le richieste cron job sono soggette agli stessi limiti delle altre richieste HTTP. 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:

Proprietario
Editor

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 nella directory WEB-INF dell'applicazione (insieme a app.yaml) configura le attività pianificate per l'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 la sintassi YAML ed è costituito da definizioni per ciascuno dei tuoi 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 nella tua app a cui vuoi che il servizio cron invii le richieste di job.

schedule

Obbligatorio. Definisce la pianificazione relativa all'esecuzione del job. Consulta la sintassi di seguito.

description

Facoltativo. Descrive il cron job, visibile dall'interno della console Google Cloud.

timezone

Facoltativo. Il nome del fuso orario, o "infozona", che vuoi utilizzare per la pianificazione del job. Se non specifichi un fuso orario, la pianificazione utilizza UTC, noto anche come GMT.

target

Facoltativo. Il nome di un servizio specifico nella tua app. Quando target è specificato, il servizio cron targetizza la richiesta del job al servizio nella tua app. Le richieste di job vengono instradate alle versioni nel servizio specificato che sono 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 suddivise tra le versioni configurate:
- Suddivisione dell'indirizzo IP: le richieste di job dal 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 job non includono un cookie nella richiesta e, pertanto, non vengono instradate ad altre versioni.
Se utilizzi un file di invio, i tuoi job possono essere reindirizzati quando lo stesso URL è configurato anche in dispatch.yaml. Ad esempio, se l'URL /tasks/hello_service2 è definito in entrambi i seguenti file cron.yaml e dispatch.yaml, 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. Consente di specificare di eseguire nuovamente i job non riusciti; consulta la sintassi di seguito.

Definizione del cron job `schedule`

I cron job vengono pianificati su intervalli ricorrenti e vengono specificati utilizzando un semplice formato di tipo inglese. Puoi definire una pianificazione in modo che il job venga eseguito più volte al giorno o in giorni e mesi specifici.

Intervalli subgiornalieri

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

Intervallo di fine: definisce il tempo tra l'"ora di fine" di un job e l'inizio del job successivo, dove l'"ora di fine" è l'ora in cui il job viene completato o il timeout. Il servizio Cron esegue job in questo tipo di intervallo nell'arco di 24 ore, 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 con 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 riprende alle 02:06.
Intervallo di inizio: definisce un intervallo di tempo regolare entro il quale il servizio cron deve avviare ogni job. A differenza dell'intervallo di tempo di fine, quest'ultimo esegue ogni job indipendentemente dal momento in cui il job precedente viene completato o scade. Puoi impostare un intervallo di tempo entro il quale vuoi che il job venga eseguito, o job 24 ore al giorno, a partire da 00:00.
Poiché l'ora di inizio di un job è rigida, se un'istanza di un job viene eseguita più a lungo dell'intervallo di tempo definito, il servizio cron può ignorare un job. Una singola ora di inizio nell'intervallo può essere saltata se il job precedente non è stato completato o se è scaduto.

Esempio: per la pianificazione every 5 minutes from 10:00 to 14:00, il primo job viene eseguito 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, pertanto, 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 job può essere eseguito una volta al giorno, in uno o più giorni selezionati e in uno o più mesi selezionati. I job eseguiti con una pianificazione personalizzata vengono eseguiti tutto l'anno, solo in un momento 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 vuoi utilizzare un intervallo subgiornaliero o un intervallo personalizzato. Non puoi combinare e utilizzare elementi dei vari tipi di intervallo. Di seguito è riportato un esempio di definizione di pianificazione non valida: schedule: every 6 hours mon,wed,fri.
Deve essere eseguita una sola istanza di un job in qualsiasi momento. Il servizio Cron è progettato per fornire la distribuzione "at least once", ovvero, se un job è pianificato, App Engine invia la richiesta del job almeno una volta. In alcune rare circostanze, è possibile che vengano richieste più istanze dello stesso job. Di conseguenza, il gestore delle richieste deve essere idempotente e il codice deve garantire che non ci siano effetti collaterali dannosi in questo caso.

Formattazione di `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 l'elemento schedule:

Intervallo di tempo di fine

[TYPE]: gli intervalli giornalieri devono includere il prefisso every.
Esempio: schedule: every 12 hours
[INTERVAL_VALUE]: un valore intero e la corrispondente unità di tempo. Valori validi per l'unità di tempo:
- minutes o mins
- hours
[INTERVAL_SCOPE]: non applicabile. Per impostare un'ora di inizio o un intervallo di tempo specifico entro cui eseguire i job, consulta la sintassi per Intervallo di inizio o Intervallo personalizzato.

Esempi di intervallo di tempo di fine

Utilizza i seguenti esempi per aiutarti a comprendere come definire le pianificazioni dei job che utilizzano un intervallo di tempo di fine:

Viene eseguita 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
```
Viene eseguita 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

[TYPE]: gli intervalli giornalieri devono includere il prefisso every.
Esempio: schedule: every 12 hours
[INTERVAL_VALUE]: un valore intero e la corrispondente unità di tempo. 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 entro i quali vuoi eseguire i job.
  Devi specificare i valori dell'ora nel formato di 24 ore, HH:MM, dove:
  - HH sono numeri interi da 00 a 23.
  - MM sono numeri interi da 00 a 59.
- Utilizza synchronized per specificare un intervallo di tempo di 24 ore (from 00:00 to 23:59) diviso uniformemente per il valore [INTERVAL_VALUE].
  Importante: l'intervallo [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 intervallo di tempo di inizio

Utilizza i seguenti esempi per aiutarti a comprendere come definire le pianificazioni dei job che utilizzano un intervallo di tempo di inizio:

Eseguita 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 all'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 ore 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 sono dal primo giorno di un mese fino al numero massimo di giorni in 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 eseguire 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 di uno 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 corrispondente all'intervallo [INTERVAL_VALUE] specificato. Gli intervalli personalizzati possono includere la clausola of [MONTH], che specifica un singolo mese di un anno, o un elenco separato da virgole di mesi multipli. Devi anche definire un momento specifico entro cui vuoi eseguire il job, ad esempio: of [MONTH] [HH:MM].
Per impostazione predefinita, se la clausola of è esclusa, l'intervallo personalizzato viene eseguito ogni mese.
- [MESE]: devi specificare i mesi in un elenco separato da virgole e 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 a 24 ore, HH:MM, dove:
  - HH sono numeri interi da 00 a 23.
  - MM sono numeri interi da 00 a 59.

Esempi di intervalli personalizzati

Utilizza i seguenti esempi per aiutarti a comprendere come definire le pianificazioni dei job che utilizzano un intervallo personalizzato:

Eseguito ogni giorno alle 00:00:
```
schedule: every day 00:00
```
Ogni lunedì alle 09:00:
```
schedule: every monday 09:00
```
Viene eseguita una volta il secondo mercoledì di marzo alle 17:00:
```
schedule: 2nd wednesday of march 17:00
```
Viene eseguita sei volte a maggio. Durante le prime due settimane, viene eseguita una volta ogni lunedì, mercoledì e venerdì alle 10:00:
```
schedule: 1st,second mon,wed,fri of may 10:00
```
Eseguita una volta alla settimana. Ogni 7 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 ogni due settimane. 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
```
Viene eseguita una volta ogni trimestre. Il primo giorno di gennaio, aprile, luglio e ottobre viene eseguita una volta alle 00:00:
```
schedule: 1 of jan,april,july,oct 00:00
```

Specificare i nuovi tentativi

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

Ecco un file cron.yaml di esempio che contiene un singolo cron job configurato per un massimo di cinque tentativi, con un backoff iniziale di 2,5 secondi che 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 dei nuovi tentativi 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 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 raggiungere entrambi i limiti. Il valore predefinito per `job_retry_limit` è `0`.
`job_age_limit`	Il limite di tempo per riprovare un cron job non riuscito, misurato dalla prima esecuzione del cron job. Il valore è un numero seguito da un'unità di tempo, dove l'unità è `s` per i secondi, `m` per i minuti, `h` per le ore o `d` per i 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 riprova il cron job finché non raggiunge entrambi i limiti.
`min_backoff_seconds`	Il numero minimo di secondi di attesa prima di riprovare un cron job non riuscito.
`max_backoff_seconds`	Il numero massimo di secondi di attesa prima di riprovare un cron job non riuscito.
`max_doublings`	Il numero massimo di volte in cui l'intervallo tra i nuovi tentativi di cron job non riusciti sarà raddoppiato prima che l'aumento diventi costante. La costante è: 2*(`max_doublings` - 1) `min_backoff`.

Convalida delle richieste cron

Potresti voler verificare che le richieste ai tuoi URL cron provengano da App Engine e non da un'altra origine. Per farlo, puoi convalidare un'intestazione HTTP e l'indirizzo IP di origine della 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, vengono rimosse dalla richiesta.
App Engine genera richieste cron provenienti dall'indirizzo IP 0.1.0.2. Per i cron job creati con versioni precedenti di gcloud (antecedenti alla versione 326.0.0), le richieste cron provengono da 0.1.0.1.

Nota: se definisci un firewall, devi impostare una regola firewall per l'indirizzo IP 0.1.0.2 o 0.1.0.1 per consentire alla tua app di ricevere richieste dal servizio cron.

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

Timeout richiesta

Il timeout della richiesta cron è di 60 minuti.

Per ulteriori informazioni sui timeout delle richieste per ambiente e sul tipo di scalabilità, consulta Scegliere un ambiente App Engine.

Caricamento di cron job in corso...

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

gcloud app deploy cron.yaml

Eliminazione dei cron job in corso...

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

cron:

Supporto cron nella console Google Cloud

Puoi verificare i cron job pianificati nella pagina Crono job della console Google Cloud.

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