Referencia de cron.xml para herramientas basadas en el SDK de App Engine

Usa el archivo cron.yaml a fin de definir tareas programadas para tu aplicación.

Para obtener más información sobre cómo programar tareas y cómo probar, implementar o borrar trabajos cron, consulta Programa tareas con cron.

Ejemplo

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

Sintaxis

El archivo cron.yaml debe ubicarse en el directorio app.yaml de la aplicación junto con : cron.yaml configura las tareas programadas para tu aplicación de Java 8.

Definiciones del trabajo cron

Elemento Descripción
description Opcional. La descripción se puede ver en la consola de Google Cloud y en la interfaz de administrador del servidor de desarrollo.
retry_parameters Opcional. Si el controlador de solicitudes de un trabajo cron muestra un código de estado HTTP que no está entre 200 y 299 (inclusive), App Engine considera que el trabajo falló. Según la configuración predeterminada, no se reintentan los trabajos con errores. Para hacer que se vuelvan a procesar trabajos con errores, incluye un bloque de parámetros de reintento en tu archivo de configuración.

Consulta la sección Reintentos de cron para obtener más información.

schedule Obligatorio. Define la programación de cuándo deseas que se ejecute el trabajo cron; consulta la sintaxis a continuación.
target

La string target se antepone al nombre de host de tu app. Por lo general, es el nombre de un servicio. El trabajo cron se enruta a la versión del servicio con nombre que se configura para tráfico.

Si no se encuentra el nombre de servicio especificado para target, la solicitud cron se enruta al servicio default o a la versión de la app configurada con el objetivo de recibir tráfico. Para obtener más información acerca del enrutamiento, consulta Cómo se enrutan las solicitudes.

timezone El elemento timezone debe ser el nombre de un nombre de zona horaria estándar según zoneinfo. Si no especificas una zona horaria, los trabajos se ejecutarán en UTC (también conocida como GMT).
url Obligatorio. El campo url es solo una URL en tu aplicación. Si el elemento url contiene los caracteres XML especiales &<, >'", debes escaparlos.

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 las 10:00 y, luego, cada 5 minutos. Si ese primer trabajo se ejecuta durante 7 minutos, se omitirá el trabajo de las 10:05 y, por lo tanto, el servicio cron no ejecutará otra instancia de este trabajo hasta las 10: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 las 07: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</schedule>.
  • 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]</schedule>

Elige un tipo de intervalo para definir el elemento schedule:

Intervalo de hora de finalización
  • [TYPE]: Los intervalos diarios deben incluir el prefijo every.

    Por ejemplo: <schedule>every 12 hours</schedule>

  • [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 o mins
    • 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</schedule>
  • 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</schedule>
Intervalo de hora de inicio
  • [TYPE]: Los intervalos diarios deben incluir el prefijo every.

    Por ejemplo: <schedule>every 12 hours</schedule>

  • [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 o mins
    • 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 del 00 al 23.
      • MM son números enteros del 00 al 59.
    • 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, 1224.

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</schedule>
  • 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</schedule>
  • Se ejecuta una vez cada dos horas, todos los días, a partir de las 00:00:
    <schedule>every 2 hours synchronized</schedule>
Intervalo personalizado
  • [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>
      <schedule>every monday 09:00</schedule>

    • 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 o first
      • 2nd o second
      • 3rd o third
      • Hasta: 31st o thirtyfirst

      Ejemplo:

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

  • [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 o mon
      • tuesday o tue
      • wednesday o wed
      • thursday o thu
      • friday o fri
      • saturday o sat
      • sunday o sun
      • Usa day para especificar todos los días de la semana.

    Ejemplos:

    <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]: 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 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
      • 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 del 00 al 23.
      • MM son números enteros del 00 al 59.
    • Ejemplo:

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

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</schedule>
  • Se ejecuta todos los lunes a las 09:00:
    <schedule>every monday 09:00</schedule>
  • Se ejecuta una vez el segundo miércoles de marzo a las 17:00:
    <schedule>2nd wednesday of march 17:00</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>
  • 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</schedule>

Reintentos de cron

Si el controlador de solicitudes de un trabajo cron muestra un código de estado que no está entre 200 y 299 (inclusive), App Engine considera que el trabajo falló. Según la configuración 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.xml de muestra que contiene un solo trabajo cron configurado para reintentarse hasta cinco veces (la configuración predeterminada) con una retirada inicial de 2.5 segundos que se duplica cada vez.

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

Sintaxis de reintentos de cron

Los parámetros de reintento se describen en la siguiente tabla.

Elemento Descripción
job_retry_limit La cantidad máxima de reintentos para un trabajo cron con errores no debe superar 5. Si se especifica con job_age_limit, App Engine vuelve a intentar el trabajo cron hasta que se alcancen ambos límites. Cuando se omite de los parámetros, el límite se establece en 5 de forma predeterminada.
job_age_limit El límite de tiempo para reintentar un trabajo cron con errores medido desde la primera ejecución del trabajo. El valor es un número seguido por una unidad de tiempo, en el que la unidad es s para los segundos, m para los minutos, h para las horas o d para los 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 se especifica con job_retry_limit, App Engine vuelve a intentar el trabajo cron hasta que se alcancen 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.

Solicitudes de cron

Encabezados de la solicitud

Las solicitudes del servicio cron contendrán un 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. La excepción es para las solicitudes de los administradores que hayan accedido a las apps heredadas, quienes tienen permitido configurar el encabezado con fines de prueba.

Dirección IP de origen

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 de 0.1.0.1.

Tiempo de espera de la solicitud

El tiempo de espera de la solicitud cron depende del tipo de escalamiento que se configura para tu app:

Ajuste de escala automático
Tiempo de espera de la solicitud de 10 minutos.
Ajuste de escala básico y manual
Tiempo de espera de la solicitud de 24 horas.

Para obtener más información, consulta Cómo se administran las instancias.

Límites

Las aplicaciones gratuitas pueden tener hasta 20 tareas programadas. Las aplicaciones de pago pueden tener hasta 250 tareas programadas.

Asistencia de cron en el servidor de desarrollo

El servidor de desarrollo no ejecuta tus trabajos cron de manera automática. Puedes usar tu cron de escritorio local o la interfaz de tareas programadas para activar las URL de tus trabajos con curl o una herramienta similar.

Implementa trabajos cron

Puedes usar la CLI de gcloud para implementar tus trabajos cron en App Engine.

Para implementar los trabajos cron que se especificaron en el archivo de configuración cron.yaml, ejecuta el siguiente comando:

gcloud

    gcloud app deploy cron.yaml

Maven

    mvn appengine:deployCron cron.yaml

Gradle

    gradle appengineDeployCron cron.yaml

IDE

Si usas IntelliJ o Eclipse, debes usar el formulario de implementación para seleccionar los archivos de configuración individuales que se implementarán.

Borra todos los trabajos cron

Sigue estos pasos para borrar todos los trabajos cron:

  1. Edita el contenido del archivo cron.yaml de la siguiente manera:

    cron:

  2. Implementa el archivo cron.yaml en App Engine.

Asistencia de cron en la consola de Google Cloud

La página Listas de tareas en cola de la consola de Google Cloud tiene una pestaña que muestra las tareas que ejecutan trabajos cron.

También puedes visitar la página de registros para averiguar cuándo se agregaron o quitaron trabajos cron.