Riferimento a cron.xml per gli strumenti basati sull'SDK App Engine

Utilizza il file cron.yaml per definire le attività pianificate per la tua applicazione.

Per scoprire di più sulla pianificazione delle attività, incluso come testare, eseguire il deployment o eliminare i cron job, consulta Pianificazione delle attività con Cron.

Esempio

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

Sintassi

Il file cron.yaml deve trovarsi nella directory principale dell'applicazione insieme a app.yaml: cron.yaml configura le attività pianificate per l'applicazione Java 8.

Definizioni di cron job

Elemento Descrizione
description Facoltativo. La descrizione è visibile nella console Google Cloud e nell'interfaccia di amministrazione del server di sviluppo.
retry_parameters Facoltativo. Se il gestore delle richieste di un cron job restituisce un codice di stato HTTP che non rientra nell'intervallo 200-299 (incluso), 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 ritentati includendo un blocco retry-parameters nel file di configurazione.

Per ulteriori informazioni, consulta la sezione Nuovi tentativi di Cron.

schedule Obbligatorio. Definisce la pianificazione di esecuzione del cron job, vedi la sintassi riportata di seguito.
target

La stringa target viene anteposta al nome host della tua app. Di solito è il nome di un servizio. Il cron job verrà indirizzato alla versione del servizio denominato configurata per il traffico.

Se il nome del servizio specificato per target non viene trovato, la richiesta Cron viene indirizzata al servizio default o alla versione dell'app configurata per ricevere traffico.Per saperne di più sul routing, consulta Come vengono indirizzate le richieste.

timezone timezone deve essere il nome di un fuso orario zoneinfo standard. Se non specifichi un fuso orario, i job vengono eseguiti in UTC (noto anche come GMT).
url Obbligatorio. Il campo url è solo un URL nella tua applicazione. Se l'elemento url contiene i caratteri speciali XML &, <, >, ' o ", devi eseguirne l'escape.

Definizione del cron job schedule

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

Intervalli giornalieri

Utilizza un intervallo inferiore a un 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 inizio:

  • Intervallo di tempo di fine: definisce il tempo che intercorre 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 scade . Il servizio Cron esegue i job in questo tipo di intervallo per tutto il giorno di 24 ore, a partire dalle ore 00:00, e attende la durata di tempo specificata tra un job e l'altro.

    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 base a questa pianificazione viene completata alle 02:01, il job successivo attende 5 minuti e riprende alle 02:06.

  • Intervallo di tempo di inizio: 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 tempo di inizio 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 venga eseguito il job oppure eseguire i job 24 ore al giorno a partire dalle ore 00:00.

    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. Un orario di inizio individuale nell'intervallo può essere ignorato se il job precedente non è stato completato o se scade il tempo.

    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 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 alle ore 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 in base a una pianificazione personalizzata vengono eseguiti tutto l'anno, solo all'ora specifica 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 inferiore a un giorno 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</schedule>.
  • In qualsiasi momento deve essere in esecuzione una sola istanza di un job. Il servizio Cron è progettato per fornire la distribuzione "at least once", ovvero, se un job è pianificato, App Engine invia la richiesta di job almeno una volta. In alcuni rari casi, è possibile richiedere 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 se ciò si verifica.

Formattare schedule

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

<schedule>[TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]</schedule>

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</schedule>

  • [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 orario di inizio specifico o un intervallo in cui vuoi che vengano eseguiti i job, consulta la sintassi per l'intervallo di tempo di inizio o l'intervallo personalizzato.
Esempi di intervalli di tempo di fine
Utilizza i seguenti esempi per capire come definire pianificazioni dei job che utilizzano un intervallo di tempo di fine:
  • Viene eseguito 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</schedule>
  • Inizia l'esecuzione 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</schedule>
Intervallo di tempo di inizio
  • [TYPE]: Gli intervalli giornalieri devono includere il prefisso every.

    Esempio: <schedule>every 12 hours</schedule>

  • [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 24 ore synchronized.
    • Includi la clausola from [HH:MM] to [HH:MM] per definire un orario di inizio e un intervallo specifici entro i quali vuoi eseguire i job.

      Devi specificare i valori di tempo nel formato 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 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 tempo di inizio
Utilizza i seguenti esempi per capire come definire pianificazioni dei job che utilizzano un intervallo di tempo di inizio:
  • Viene eseguito ogni 5 minuti dalle 10:00 alle 14:00, tutti i giorni: 
    <schedule>every 5 minutes from 10:00 to 14:00</schedule>
  • Viene eseguito una volta ogni ora dalle 08:00 alle 16:00, tutti i giorni: 
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • Eseguito una volta ogni due ore, tutti i giorni a partire dalle ore 00:00: 
    <schedule>every 2 hours synchronized</schedule>
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>
<schedule>every monday 09:00</schedule>

    • Per definire giorni specifici, devi utilizzare numeri ordinali. I valori validi vanno dal primo giorno di un mese al numero massimo 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>
<schedule>2nd,third wednesday of month 09:00</schedule>

  • [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 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>
<schedule>1,8,15,22 of month 09:00</schedule>
<schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [INTERVAL_SCOPE]: specifica una clausola che corrisponde a [INTERVAL_VALUE] specificato. Gli intervalli personalizzati possono includere la clausola of [MONTH], che specifica un singolo mese in un anno o un elenco di più mesi separati da virgole. 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 un mix 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 di tempo nel formato 24 ore, HH:MM, dove:
      • HH sono numeri interi da 00 a 23.
      • MM sono numeri interi da 00 a 59.

      • Esempio: 

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

Esempi di intervalli personalizzati
Utilizza i seguenti esempi per capire come definire le pianificazioni dei job che utilizzano un intervallo personalizzato:
  • Eseguito ogni giorno alle ore 00:00: 
    <schedule>every day 00:00</schedule>
  • Eseguito ogni lunedì alle 09:00: 
    <schedule>every monday 09:00</schedule>
  • Viene eseguito una volta il secondo mercoledì di marzo alle 17:00: 
    <schedule>2nd wednesday of march 17:00</schedule>
  • Viene eseguito 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</schedule>
  • 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</schedule>
  • Eseguito 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</schedule>
  • Viene eseguita 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</schedule>
  • Viene eseguito una volta al 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</schedule>

Nuovi tentativi di cron

Se il gestore di richieste di un job cron restituisce un codice di stato non compreso nell'intervallo 200-299 (incluso), 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 ritentati includendo un blocco retry_parameters nel file di configurazione.

Ecco un file cron.xml di esempio che contiene un singolo job cron configurato per riprovare fino a cinque volte (il valore predefinito) con un backoff iniziale di 2,5 secondi che raddoppia ogni volta.

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

Sintassi dei nuovi tentativi cron

I parametri di ripetizione sono descritti nella tabella seguente.

Elemento Descrizione
job_retry_limit Il numero massimo di tentativi per un cron job non riuscito non deve superare 5. Se specificato con job_age_limit, App Engine riprova il cron job finché non vengono raggiunti entrambi i limiti. Se omesso dai parametri, il limite è impostato su 5 per impostazione predefinita.
job_age_limit Il limite di tempo per ritentare un cron job non riuscito, misurato dal momento in cui il cron job è stato eseguito per la prima volta. 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 job cron. Se specificato con job_retry_limit, App Engine riprova il cron job finché non vengono raggiunti entrambi i limiti.
min_backoff_seconds Il numero minimo di secondi da attendere prima di riprovare un job cron dopo un tentativo non riuscito.
max_backoff_seconds Il numero massimo di secondi da attendere prima di riprovare un job cron dopo il suo errore.
max_doublings Il numero massimo di volte in cui l'intervallo tra i tentativi di esecuzione del job cron non riuscito viene raddoppiato prima che l'aumento diventi costante. La costante è: 2**(max_doublings - 1) * min_backoff.

Richieste cron

Intestazioni delle richieste

Le richieste del servizio Cron conterranno un'intestazione HTTP:

X-Appengine-Cron: true

Questo e altri header vengono impostati internamente da App Engine. Se un client invia queste intestazioni, vengono rimosse dalla richiesta. L'eccezione riguarda le richieste degli amministratori che hanno eseguito l'accesso alle app legacy, ai quali è consentito impostare l'intestazione a scopo di test.

Indirizzo IP di origine

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

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ù, vedi Come vengono gestite le istanze.

Limiti

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

Supporto di Cron nel server di sviluppo

Il server di sviluppo non esegue automaticamente i cron job. Puoi utilizzare l'interfaccia cron o delle attività pianificate del tuo computer locale per attivare gli URL dei tuoi job con curl o uno strumento simile.

Deployment dei cron job

Puoi utilizzare gcloud CLI per eseguire il deployment dei tuoi job cron in App Engine.

Per eseguire il deployment dei cron job specificati nel file di configurazione cron.yaml, esegui questo comando:

gcloud

    gcloud app deploy cron.yaml

Maven

    mvn appengine:deployCron cron.yaml

Gradle

    gradle appengineDeployCron cron.yaml

IDE

Se utilizzi IntelliJ, seleziona i singoli file di configurazione da implementare utilizzando il modulo di deployment.

Eliminazione di tutti i cron job

Per eliminare tutti i cron job:

  1. Modifica i contenuti del file cron.yaml in modo che siano:

    cron:

  2. Esegui il deployment del file cron.yaml in App Engine.

Supporto di cron nella console Google Cloud

La pagina Code di attività della console Google Cloud contiene una scheda che mostra le attività che eseguono job cron.

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