Cómo programar trabajos con cron.yaml

El servicio Cron de App Engine te permite configurar tareas generalmente programadas que operan a horas definidas o intervalos regulares. Estas tareas se conocen comúnmente como trabajos cron. Estos trabajos cron se activan de manera automática con el servicio cron de App Engine. Por ejemplo, podrías usar esto para enviar un informe por correo electrónico a diario. Además, puedes actualizar algunos datos en caché cada 10 minutos o actualizar información de resumen cada una hora.

En un momento determinado del día, un trabajo cron invocará una URL mediante una solicitud HTTP GET. Una solicitud HTTP invocada por cron puede ejecutarse hasta durante 60 minutos, pero está sujeta 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.

Cómo funciona el archivo de configuración cron

Un archivo cron.yaml en el directorio raíz de tu aplicación (junto con app.yaml) configura tareas programadas para tu aplicación de Go. El siguiente es un ejemplo de archivo 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

El archivo cron.yaml usa la sintaxis YAML y consta de definiciones para cada uno de tus trabajos cron. Una definición de trabajo debe tener una url y un schedule. De manera opcional, también puedes especificar una description, timezone, target y retry_parameters:

url
Obligatorio: La URL en tu aplicación a la que deseas que el servicio Cron envíe las solicitudes de trabajo.
schedule
Obligatorio: Define la programación del momento en que deseas que el trabajo se ejecute, consulta la sintaxis a continuación.
description
Opcional: Esto describe tu trabajo cron, que es visible desde GCP Console.
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 usará UTC, también conocida como GMT.
target
Opcional: El nombre de un servicio específico en tu aplicación. Cuando se especifica un 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 acerca de 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 de cookies: las solicitudes de trabajo no incluyen una cookie con la solicitud y, por lo tanto, no se enrutan a ninguna otra versión.
  • Si usas un archivo de envío, tus trabajos pueden volverse a enrutar cuando la misma URL se configura también en dispatch.yaml. Por ejemplo, si la URL /tasks/hello_service2 se encuentra definida en los siguientes archivos cron.yaml y dispatch.yaml, las solicitudes de trabajo se envían a service2, aunque target: service1 esté especificado:

    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
Opcional: Especifica cómo volver a ejecutar trabajos con errores; consulta la sintaxis a continuación.

Cómo definir el schedule de un 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 trabajo siguiente, donde la "hora de finalización" se refiere al horario en el que se completa el trabajo o se agota el tiempo de espera. El servicio de Cron ejecuta trabajos en este tipo de intervalos durante las 24 horas. Comienza en 00:00 y espera durante el tiempo especificado entre cada trabajo.

    Ejemplo: Para la programación every 5 minutes, el trabajo se ejecuta a diario mediante un intervalo de 5 minutos. Si una instancia de un trabajo que se ejecuta según este programa se completa a las 2:01, el siguiente trabajo esperará 5 minutos y comenzará de nuevo a las 2: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 de forma independiente del momento en que finaliza o se agota el tiempo de espera. Puedes establecer un intervalo de tiempo dentro del 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 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 durante un tiempo específico en los días y meses determinados.

Ejemplo: Para la programación 1,2,3 of month 07:00, el trabajo se ejecuta una vez a las 07:00 en los tres primeros días de cada mes.

Consideraciones importantes para schedule:

  • Debes decidir si deseas usar un intervalo menor de un día o un intervalo personalizado. No puedes combinar y usar elementos de diferentes tipos de intervalos. El siguiente es 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 a la 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 las solicitudes deberá ser idempotente, y tu código deberá garantizar que no existan efectos secundarios perjudiciales en estos casos.

Define el formato de schedule

Para especificar cuándo 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 tu elemento schedule:

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

    Ejemplo: schedule: every 12 hours

  • [INTERVAL_VALUE]: Un valor de número entero y la unidad de tiempo correspondiente. Los valores válidos para la unidad de tiempo son los siguientes:
    • minutes o mins
    • hours
  • [INTERVAL_SCOPE]: No aplicable. Para establecer una hora de inicio o un rango específicos en los que desees que se ejecuten tus trabajos, consulta la sintaxis del intervalo de hora de inicio o del intervalo personalizado.
Ejemplos de intervalo de hora de finalización
Usa los siguientes ejemplos para entender cómo definir los programas de trabajos que usan un intervalo de hora de finalización:
  • Se ejecuta todos los días a las 00:00 y aguarda 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
Intervalo de hora de inicio
  • [TYPE]: Los intervalos diarios deben incluir el prefijo every.

    Ejemplo: schedule: every 12 hours

  • [INTERVAL_VALUE]: Un valor de número entero y la unidad de tiempo correspondiente. Los valores válidos para la unidad de tiempo son los siguientes:
    • 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 horas.
    • Incluye la cláusula from [HH:MM] to [HH:MM] para definir una hora de inicio y un rango en el que desees que se ejecuten los trabajos.

      Debes especificar los valores de tiempo en el formato de 24 horas, HH:MM, en los que sucede lo siguiente:

      • HH son números enteros del 00 al 23.
      • MM son números enteros del 00 al 59.
    • Usa synchronized para especificar un intervalo de tiempo de 24 horas (from 00:00 to 23:59) que se divide de manera uniforme según el valor [INTERVAL_VALUE].

      Importante: El [INTERVAL_VALUE] debe dividir 24 en un número entero; de lo contrario, se producirá un error. Los valores válidos para [INTERVAL_VALUE] incluyen los siguientes: 1, 2, 3, 4, 6, 8, 12 o 24.

Ejemplos de intervalo de hora de inicio
Usa los siguientes ejemplos para entender cómo definir programas de trabajo que emplean 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
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: 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 o first
      • 2nd o second
      • 3rd o third
      • Y hasta: 31st o thirtyfirst

      Ejemplo:

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

  • [INTERVAL_VALUE]: Los intervalos personalizados incluyen una lista de los días específicos en los que deseas que se ejecute el trabajo. La lista se debe definir en una lista separada por comas y puede incluir cualquiera de los siguientes valores:
    • El valor del número entero desde el día del mes hasta un máximo de 31 días, por ejemplo:
      • 1
      • 2
      • 3
      • Y 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: 1,8,15,22 of month 09:00
    schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00

  • [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].

    Según la configuración 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 bien oct
      • november o nov
      • december o dec
      • Usa month para especificar todos los meses del año.
    • [HH:MM]: Debes especificar los valores horarios en el formato de 24 horas, HH:MM, en los 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: 1 of jan,april,july,oct 00:00

Ejemplos de intervalos personalizados
Usa los siguientes ejemplos para entender cómo definir los programas de trabajo que emplean 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

Cómo especificar 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ó. 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 retry_parameters en tu 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 (de manera predeterminada) 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:
    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 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 reintentará el trabajo cron hasta que se hayan alcanzado ambos límites. Cuando se omite en 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 de una unidad de tiempo, en donde la unidad es 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 se especifica con job_retry_limit, App Engine reintenta el trabajo cron hasta que se hayan alcanzado ambos límites.
min_backoff_seconds La cantidad mínima de segundos que se espera antes de reintentar un trabajo cron después de la falla.
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.

Cómo validar solicitudes de cron

Puede que desees validar que las solicitudes a las URL de tu cron provengan de App Engine y no de otra fuente. Puedes hacerlo si validas un encabezado HTTP y la dirección IP de origen de la solicitud:

  • Las solicitudes del servicio cron también contendrán un encabezado HTTP:

    X-Appengine-Cron: true
    

    Google App Engine configura de manera interna el encabezado X-Appengine-Cron. Si tu controlador de solicitudes encuentra este encabezado, puede confiar que la solicitud es una solicitud de cron. App Engine quita los encabezados X- cuando se originan en una fuente externa para que puedas confiar en este encabezado.

  • Google App­­ Engine emite solicitudes cron desde la dirección IP 10.0.0.1.

Cómo subir trabajos cron

A fin de subir tus trabajos cron, debes especificar cron.yaml como parámetro para el siguiente comando de gcloud:

gcloud app deploy cron.yaml

Cómo quitar trabajos cron

Para borrar todos los trabajos cron, cambia el archivo cron.yaml a fin de que solo contenga lo siguiente:

cron:

Cómo mostrar información del trabajo

Puedes mostrar la versión analizada de tus trabajos cron con el comando appcfg.py cron_info, incluidas las veces que se ejecutarán los trabajos.

Ten en cuenta que appcfg.py cron_info no procesará de manera correcta los programas si se especifica una zona horaria diferente a UTC.

Asistencia de cron en Google­ Cloud Platform Console

Puedes verificar los trabajos cron programados en la página de trabajos cron de GCP Console.

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

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno flexible de App Engine para Go