El servicio cron de App Engine te permite configurar tareas programadas con frecuencia que operan en momentos definidos o a intervalos regulares. Estas tareas se conocen como trabajos cron. Estos trabajos cron se activan de forma automática con el servicio cron de App Engine. Por ejemplo, podrías usar estos trabajos para enviar un informe por correo electrónico a diario, actualizar algunos datos en caché cada 10 minutos o actualizar cierta información de resumen cada una hora.
Un trabajo cron realiza una solicitud GET
HTTP programada al extremo especificado en la misma aplicación en la que se configuró el trabajo cron. El controlador para esa URL ejecuta la lógica cuando recibe una llamada.
El servicio Cron de App Engine no se puede usar para llamar a los extremos web fuera de la app host de App Engine. No se puede usar para llamar a los extremos de App Engine desde otras apps además de la app host.
Las solicitudes de trabajo cron están sujetas a los mismos límites que otras solicitudes HTTP. Las aplicaciones gratuitas pueden tener hasta 20 tareas programadas. Las aplicaciones de pago pueden tener hasta 250 tareas programadas.
Para implementar o actualizar los programas, tu cuenta requiere una de las siguientes funciones de Identity and Access Management:
- Propietario
- Editor
- Administrador de Cloud Scheduler (
roles/cloudscheduler.admin
)
Puedes configurar el permiso en la página de IAM en la consola de Google Cloud.
Acerca del archivo de configuración cron
Para todos los entornos de ejecución, excepto Java, un archivo cron.yaml
en el directorio raíz de tu aplicación (junto con app.yaml
) configura las tareas programadas para tu app.
En Java, un archivo cron.yaml
en el directorio WEB-INF
de tu aplicación (junto con app.yaml
) configura las tareas programadas para la app.
El siguiente es un archivo cron.yaml
de ejemplo:
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
El archivo cron.yaml
usa la sintaxis YAML y consta de definiciones para cada uno de los trabajos cron. Una definición de trabajo debe tener una url
y una propiedad schedule
. De manera opcional, también puedes especificar las propiedades description
, timezone
, target
y retry_parameters
:
url
- Obligatorio. Es la URL en la app a la que deseas que el servicio cron envíe las solicitudes de trabajos.
schedule
- Obligatorio. Define la programación del momento en que deseas que se ejecute el trabajo. Consulta la sintaxis a continuación.
description
- Opcional. Describe el trabajo cron, que se puede ver desde la consola de Google Cloud.
timezone
- Opcional. El nombre de la zona horaria, o “zoneinfo”, que deseas usar para la programación de tu trabajo. Si no especificas una zona horaria, la programación usa
UTC
, también conocida comoGMT
. -
target
- Opcional. El nombre de un servicio específico en tu aplicación. Cuando se especifica la propiedad
target
, el servicio cron dirige la solicitud de trabajo a ese servicio en tu aplicación. Las solicitudes de trabajo se enrutan a las versiones del servicio especificado que se configuran para el tráfico. Obtén más información sobre cómo se enrutan las solicitudes.Consideraciones importantes de
target
:-
Si la división del tráfico está habilitada, las solicitudes de trabajo no se dividirán entre las versiones que configuraste:
- División de direcciones IP: Las solicitudes de trabajo del servicio cron siempre se envían desde la misma dirección IP y, por lo tanto, siempre se enrutan a la misma versión.
- División por cookies: Las solicitudes de trabajo no incluyen una cookie y, por lo tanto, no se enrutan a ninguna otra versión.
-
Si usas un archivo de envío, los trabajos pueden volver a enrutarse cuando la misma URL también se configura en
dispatch.yaml
. Por ejemplo, si la URL/tasks/hello_service2
está definida en los archivoscron.yaml
ydispatch.yaml
, las solicitudes de trabajo se envían aservice2
, aunque esté especificadotarget: service1
: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
-
Si la división del tráfico está habilitada, las solicitudes de trabajo no se dividirán entre las versiones que configuraste:
retry_parameters
- Opcional. Especifica que se deben volver a ejecutar los trabajos con errores; consulta la sintaxis a continuación.
Define la schedule
del trabajo cron
Los trabajos cron se programan en intervalos periódicos y se especifican con un formato similar al del inglés. Puedes definir una programación de modo que tu trabajo se ejecute varias veces al día, o en días y meses específicos.
- Intervalos menores que un día
Usa un intervalo menor que un día de duración para ejecutar un trabajo varias veces al día con una programación repetitiva. Puedes definir un intervalo de hora de finalización o de inicio:
Intervalo de hora de finalización: Define el tiempo entre la “hora de finalización” de un trabajo y el momento en el que se inicia el siguiente trabajo. La “hora de finalización” es la hora en que se completa el trabajo o se agota el tiempo de espera. El servicio cron ejecuta trabajos en este tipo de intervalos las 24 horas del día. Comienza a las
00:00
y espera el tiempo especificado entre cada trabajo.Ejemplo: Para la programación
every 5 minutes
, el trabajo se ejecuta a diario en intervalos de 5 minutos. Si una instancia de un trabajo que se ejecuta según esta programación se completa a las 02:01, el siguiente trabajo esperará 5 minutos y comenzará de nuevo a las 02:06.Intervalo de hora de inicio: Define un intervalo regular para que el servicio cron inicie cada trabajo. A diferencia del intervalo de hora de finalización, el de hora de inicio ejecuta cada trabajo independientemente del momento en que finaliza o se agota el tiempo de espera del trabajo anterior. Puedes establecer un intervalo en el cual deseas que se ejecute tu trabajo o ejecutar trabajos las 24 horas del día a partir de las
00:00
.Dado que la hora de inicio de un trabajo es estricta, si la instancia de un trabajo se ejecuta por más tiempo que el definido en el intervalo, el servicio cron puede omitir el trabajo. Se puede omitir una hora de inicio individual en el intervalo si el trabajo anterior no se completó o si se agotó el tiempo de espera.
Ejemplo: para la programación
every 5 minutes from 10:00 to 14:00
, el primer trabajo se ejecuta a las10:00
y, luego, cada 5 minutos. Si ese primer trabajo se ejecuta durante 7 minutos, se omitirá el trabajo de las10:05
y, por lo tanto, el servicio cron no ejecutará otra instancia de este trabajo hasta las10:10
.
- Intervalo personalizado
Puedes usar un intervalo personalizado para definir un programa en el que tu trabajo pueda ejecutarse una vez al día en uno o más días seleccionados, y en uno o más meses definidos. Los trabajos que se ejecutan con una programación personalizada lo hacen durante todo el año, solo a la hora especificada en los días y meses definidos.
Ejemplo: para la programación
1,2,3 of month 07:00
, el trabajo se ejecuta una vez a las07:00
durante los primeros tres días de cada mes.
Consideraciones importantes de schedule
:
- Debes decidir si deseas usar un intervalo menor que un día o un intervalo personalizado. No puedes combinar y usar elementos de diferentes tipos de intervalos. A continuación, se muestra un ejemplo de una definición de programación no válida:
schedule: every 6 hours mon,wed,fri
. - Solo se debe ejecutar una instancia de trabajo por vez. El servicio cron está diseñado para proporcionar una entrega “al menos una vez”. Esto significa que, si hay un trabajo programado, App Engine envía la solicitud de trabajo al menos una vez. En circunstancias excepcionales, es posible que se soliciten varias instancias de un mismo trabajo; por lo tanto, el controlador de solicitudes deberá ser idempotente, y el código deberá garantizar que no existan efectos secundarios perjudiciales en estos casos.
Define el formato de schedule
Para especificar en qué momento se ejecuta el trabajo, debes definir el elemento schedule
con la siguiente sintaxis:
schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]
Elige un tipo de intervalo para definir el elemento schedule
:
- [TYPE]: Los intervalos diarios deben incluir el prefijo
every
.Por ejemplo:
schedule: every 12 hours
- [INTERVAL_VALUE]: un valor de número entero y la unidad de tiempo correspondiente. Estos son los valores válidos para la unidad de tiempo:
minutes
omins
.hours
- [INTERVAL_SCOPE]: No aplicable. Para establecer una hora de inicio o un rango en particular en los que desees que se ejecuten los trabajos, consulta la sintaxis del intervalo de hora de inicio o del intervalo personalizado.
- Ejemplos de intervalos de hora de finalización
- Usa los siguientes ejemplos para entender cómo definir las programaciones de trabajos que usan un intervalo de hora de finalización:
- Comienza a ejecutarse todos los días a las 00:00 y espera 5 minutos entre cada trabajo. Una vez que finaliza cada trabajo, el servicio cron espera 5 minutos antes de ejecutar el próximo:
schedule: every 5 minutes
- Se ejecuta todos los días a las 00:00 y aguarda 30 minutos entre cada trabajo. Una vez finalizado cada trabajo, el servicio cron espera 30 minutos antes de ejecutar el próximo:
schedule: every 30 mins
- Comienza a ejecutarse todos los días a las 00:00 y espera 5 minutos entre cada trabajo. Una vez que finaliza cada trabajo, el servicio cron espera 5 minutos antes de ejecutar el próximo:
- [TYPE]: Los intervalos diarios deben incluir el prefijo
every
.Por ejemplo:
schedule: every 12 hours
- [INTERVAL_VALUE]: un valor de número entero y la unidad de tiempo correspondiente. Estos son los valores válidos para la unidad de tiempo:
minutes
omins
.hours
- [INTERVAL_SCOPE]: Especifica una cláusula que se corresponde con el [INTERVAL_VALUE]. Puedes definir un intervalo de tiempo personalizado o usar la opción
synchronized
de 24 h.- Incluye la cláusula
from [HH:MM] to [HH:MM]
a fin de definir una hora de inicio y un rango específicos para que se ejecuten los trabajos.Debes especificar los valores de tiempo en el formato de 24 horas,
HH:MM
, en el que sucede lo siguiente:HH
son números enteros del00
al23
.MM
son números enteros del00
al59
.
- Debes usar la opción
synchronized
para especificar un intervalo de tiempo de 24 horas (from 00:00 to 23:59
) que se divide de forma equitativa por el valor de [INTERVAL_VALUE].Importante: El [INTERVAL_VALUE] debe dividir 24 en un número entero; de lo contrario, se producirá un error. Estos son los valores válidos para [INTERVAL_VALUE]:
1
,2
,3
,4
,6
,8
,12
o24
.
- Incluye la cláusula
- Ejemplos de intervalos de hora de inicio
- Usa los siguientes ejemplos para entender cómo definir las programaciones de trabajos que usan un intervalo de hora de inicio:
- Se ejecuta cada 5 minutos de 10:00 a 14:00, todos los días:
schedule: every 5 minutes from 10:00 to 14:00
- Se ejecuta una vez por hora de 08:00 a 16:00, todos los días:
schedule: every 1 hours from 08:00 to 16:00
- Se ejecuta una vez cada dos horas, todos los días, a partir de las 00:00:
schedule: every 2 hours synchronized
- Se ejecuta cada 5 minutos de 10:00 a 14:00, todos los días:
- [TYPE]: Los intervalos personalizados pueden incluir el prefijo
every
para definir un intervalo repetitivo, o puedes definir una lista específica de días y meses:- Para definir un intervalo repetitivo, puedes usar el prefijo
every
.Ejemplos:
schedule: every day 00:00 schedule: every monday 09:00
- Para definir días específicos, debes usar números ordinales. Los valores válidos van desde el primer día de un mes hasta el máximo de días posibles en ese mes, por ejemplo:
1st
ofirst
.2nd
osecond
.3rd
othird
.- Hasta:
31st
othirtyfirst
Ejemplo:
schedule: 1st,3rd tuesday schedule: 2nd,third wednesday of month 09:00
- Para definir un intervalo repetitivo, puedes usar el prefijo
- [INTERVAL_VALUE]: Los intervalos personalizados incluyen una lista de los días específicos en los que deseas que se ejecute el trabajo. Esta se debe definir en una lista separada por comas y puede incluir cualquiera de los siguientes valores:
- El valor de número entero del día del mes hasta un máximo de 31 días, por ejemplo:
1
2
3
- Hasta:
31
- El nombre del día en una combinación de cualquiera de los siguientes valores largos o abreviados:
monday
omon
.tuesday
otue
.wednesday
owed
.thursday
othu
.friday
ofri
.saturday
osat
.sunday
osun
.- Usa
day
para especificar todos los días de la semana.
Ejemplos:
schedule: 2nd monday,thu schedule: 1,8,15,22 of month 09:00 schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00
- El valor de número entero del día del mes hasta un máximo de 31 días, por ejemplo:
- [INTERVAL_SCOPE]: Especifica una cláusula que se corresponda con el [INTERVAL_VALUE] especificado. Los intervalos personalizados pueden incluir la cláusula
of [MONTH]
, que especifica un solo mes en un año, o una lista separada por comas de varios meses. También debes definir una hora específica en la que desees que se ejecute el trabajo, por ejemplo:of [MONTH] [HH:MM]
.De forma predeterminada, si se excluye la cláusula
of
, el intervalo personalizado se ejecutará todos los meses.- [MONTH]: Debes especificar los meses en una lista separada por comas, y puedes incluir una combinación de los siguientes valores largos o abreviados:
january
ojan
.february
ofeb
.march
omar
.april
oapr
.may
june
ojun
.july
ojul
.august
oaug
.september
osep
.october
ooct
.november
onov
.december
odec
.- Usa
month
para especificar todos los meses del año.
- [HH:MM]: Debes especificar los valores de tiempo con el formato de 24 horas,
HH:MM
, en el que sucede lo siguiente:HH
son números enteros del00
al23
.MM
son números enteros del00
al59
.
Ejemplo:
schedule: 1st monday of sep,oct,nov 09:00 schedule: 1 of jan,april,july,oct 00:00
- [MONTH]: Debes especificar los meses en una lista separada por comas, y puedes incluir una combinación de los siguientes valores largos o abreviados:
- Ejemplos de intervalos personalizados
- Usa los siguientes ejemplos para entender cómo definir las programaciones de trabajos que usan un intervalo personalizado:
- Se ejecuta todos los días a las 00:00:
schedule: every day 00:00
- Se ejecuta todos los lunes a las 09:00:
schedule: every monday 09:00
- Se ejecuta una vez el segundo miércoles de marzo a las 17:00:
schedule: 2nd wednesday of march 17:00
- Se ejecuta seis veces en mayo. Durante las dos primeras semanas, se ejecuta una vez cada lunes, miércoles y viernes a las 10:00:
schedule: 1st,second mon,wed,fri of may 10:00
- Se ejecuta una vez a la semana. Cada siete días, a partir del primer día de cada mes, se ejecuta una vez a las 09:00:
schedule: 1,8,15,22 of month 09:00
- Se ejecuta cada dos semanas. En el primer y tercer lunes de cada mes, se ejecuta una vez a las 4:00:
schedule: 1st,third monday of month 04:00
- Se ejecuta tres veces al año. En el primer lunes de septiembre, octubre y noviembre, se ejecuta una vez a las 9:00:
schedule: 1st monday of sep,oct,nov 09:00
- Se ejecuta una vez cada trimestre. En el primer día de enero, abril, julio y octubre, se ejecuta una vez a las 00:00.
schedule: 1 of jan,april,july,oct 00:00
- Se ejecuta todos los días a las 00:00:
Especifica reintentos
Si el controlador de solicitudes de trabajo cron muestra un código de estado que no está dentro del rango entre 200 y 299 (inclusive), App Engine considera que ese trabajo falló. De forma predeterminada, no se reintentan los trabajos con errores. Para lograr que se reintenten trabajos con errores, incluye un bloque retry_parameters
en el archivo de configuración.
El siguiente es un archivo cron.yaml de muestra que contiene un solo trabajo cron y está configurado para reintentarse hasta cinco veces con una retirada inicial de 2.5 segundos que se duplica cada vez.
cron:
- description: "retry demo"
url: /retry
schedule: every 10 mins
retry_parameters:
job_retry_limit: 5
min_backoff_seconds: 2.5
max_doublings: 5
Sintaxis de reintentos de cron
Los parámetros de reintento se describen en la siguiente tabla.
Elemento | Descripción |
---|---|
job_retry_limit |
Un número entero que representa la cantidad máxima de reintentos para un trabajo cron con errores. El valor mínimo es 0 , y el valor máximo es 5 . Si especificas job_age_limit , App Engine vuelve a intentar el trabajo cron hasta que se alcanzan ambos límites.
El valor predeterminado para job_retry_limit es 0 .
|
job_age_limit |
El límite de tiempo para reintentar un trabajo cron con errores, medido desde el momento en que se ejecutó el trabajo por primera vez. El valor es un número seguido de una unidad de tiempo, que se representa con s para segundos, m para minutos, h para horas o d para días. Por ejemplo, el valor 5d especifica un límite de cinco días después del primer intento de ejecución del trabajo cron. Si también especificas job_retry_limit , App Engine vuelve a intentar el trabajo cron hasta que se alcanzan ambos límites.
|
min_backoff_seconds |
La cantidad mínima de segundos que se espera antes de reintentar un trabajo cron después del error. |
max_backoff_seconds |
La cantidad máxima de segundos que se espera antes de reintentar un trabajo cron después de la falla. |
max_doublings |
La cantidad máxima de veces que se reintenta el intervalo entre un trabajo cron con errores se duplicará antes de que el aumento se vuelva constante. La constante es: 2**(max_doublings - 1) * min_backoff .
|
Valida solicitudes cron
Recomendamos verificar que las solicitudes a las URL del cron provengan de App Engine y no de otra fuente. Para hacerlo, valida un encabezado HTTP y la dirección IP de origen de la solicitud:
Las solicitudes del servicio cron contendrán el siguiente encabezado HTTP:
X-Appengine-Cron: true
App Engine configura este y otros encabezados de forma interna. Si un cliente envía estos encabezados, se quitan de la solicitud.
App Engine genera solicitudes cron desde la dirección IP
0.1.0.2
. En el caso de los trabajos cron creados con versiones anteriores de gcloud (antes de 326.0.0), las solicitudes provienen de0.1.0.1
.
Para los entornos de ejecución de Java, en Jetty o Tomcat, puedes realizar la validación con un filtro.
Tiempo de espera de la solicitud
El tiempo de espera de solicitudes cron es de 60 minutos.Para obtener más información sobre los tiempos de espera de solicitudes por entorno y tipo de escalamiento, consulta Elige un entorno de App Engine.
Sube trabajos cron
Si deseas subir los trabajos cron, debes especificar el archivo cron.yaml
como un parámetro para el siguiente comando de gcloud:
gcloud app deploy cron.yaml
Borra trabajos cron
Para borrar todos los trabajos cron, cambia el archivo cron.yaml
a fin de que solo contenga lo siguiente:
cron:
Asistencia de cron en la consola de Google Cloud
Puedes comprobar los trabajos cron programados en la página de trabajos cron en la consola de Google Cloud.
También puedes visitar la página Registros para ver cuándo se agregaron o quitaron los trabajos cron.