Desencadenador de temporizador para Azure Functions

En este artículo se explica cómo usar desencadenadores de temporizador en Azure Functions. Con un desencadenador de temporizador puede ejecutar una función de forma programada.

Esta es la información de referencia para desarrolladores de Azure Functions. Si está familiarizado con Azure Functions, comience con los siguientes recursos:

• Referencia para desarrolladores de Azure Functions

• Conceptos básicos sobre los enlaces y desencadenadores de Azure Functions

• Codificación y comprobación de Azure Functions en un entorno local

Para información sobre cómo ejecutar manualmente una función desencadenada por un temporizador, consulte Ejecución manual de una función no desencadenada por HTTP.

En todos los entornos de desarrollo, se proporciona automáticamente compatibilidad para este enlace. No tiene que instalar el paquete manualmente ni que registrar la extensión.

El código fuente del paquete de extensión del temporizador está en el repositorio azure-webjobs-sdk-extensions de GitHub.

Ejemplo

//<docsnippet_fixed_delay_retry_example>
[Function(nameof(TimerFunction))]
[FixedDelayRetry(5, "00:00:10")]
public static void Run([TimerTrigger("0 */5 * * * *")] TimerInfo timerInfo,
    FunctionContext context)
{
    var logger = context.GetLogger(nameof(TimerFunction));

[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
}

@FunctionName("keepAlive")
public void keepAlive(
  @TimerTrigger(name = "keepAliveTrigger", schedule = "0 */5 * * * *") String timerInfo,
      ExecutionContext context
 ) {
     // timeInfo is a JSON string, you can deserialize it to an object using your favorite JSON library
     context.getLogger().info("Timer is triggered: " + timerInfo);
}

import datetime
import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="mytimer")
@app.timer_trigger(schedule="0 */5 * * * *", 
              arg_name="mytimer",
              run_on_startup=True) 
def test_function(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.utcnow().replace(
        tzinfo=datetime.timezone.utc).isoformat()
    if mytimer.past_due:
        logging.info('The timer is past due!')
    logging.info('Python timer trigger function ran at %s', utc_timestamp)

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

import datetime
import logging

import azure.functions as func


def main(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()

    if mytimer.past_due:
        logging.info('The timer is past due!')

    logging.info('Python timer trigger function ran at %s', utc_timestamp)

import { app, InvocationContext, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<void> {
    context.log('Timer function processed request.');
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: timerTrigger1,
});

const { app } = require('@azure/functions');

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: (myTimer, context) => {
        context.log('Timer function processed request.');
    },
});

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

module.exports = async function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if (myTimer.isPastDue)
    {
        context.log('Node is running late!');
    }
    context.log('Node timer trigger function ran!', timeStamp);   
};

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

# Input bindings are passed in via param block.
param($myTimer)

# Get the current universal time in the default string format.
$currentUTCtime = (Get-Date).ToUniversalTime()

# The 'IsPastDue' property is 'true' when the current function invocation is later than scheduled.
if ($myTimer.IsPastDue) {
    Write-Host "PowerShell timer is running late!"
}

# Write an information log with the current time.
Write-Host "PowerShell timer trigger function ran! TIME: $currentUTCtime"

Cuando esté desarrollando localmente, agregue la configuración de la aplicación en el archivo local.settings.json de la colección Values.

Consulte la sección de ejemplos para ver ejemplos completos.

Uso

Cuando se invoca una función de desencadenador de temporizador, se pasa a esta un objeto de temporizador. La siguiente función JSON es un ejemplo que representa el objeto de temporizador.

{
    "Schedule":{
        "AdjustForDST": true
    },
    "ScheduleStatus": {
        "Last":"2016-10-04T10:15:00+00:00",
        "LastUpdated":"2016-10-04T10:16:00+00:00",
        "Next":"2016-10-04T10:20:00+00:00"
    },
    "IsPastDue":false
}

{
    "schedule":{
        "adjustForDST": true
    },
    "scheduleStatus": {
        "last":"2016-10-04T10:15:00+00:00",
        "lastUpdated":"2016-10-04T10:16:00+00:00",
        "next":"2016-10-04T10:20:00+00:00"
    },
    "isPastDue":false
}

La propiedad isPastDue es true cuando la invocación de función actual es posterior a la programada. Por ejemplo, un reinicio de aplicación de función podría provocar la ausencia de una invocación.

Expresiones NCRONTAB

Azure Functions usa la biblioteca NCronTab para interpretar las expresiones NCRONTAB. Una expresión NCRONTAB es similar a una expresión CRON, excepto en que incluye un sexto campo adicional al comienzo para usarlo con una precisión de segundos:

{second} {minute} {hour} {day} {month} {day-of-week}

Cada campo puede tener uno de los siguientes tipos de valores:

Para especificar meses o días puede usar valores numéricos, nombres o abreviaturas de nombres:

• En el caso de los días, los valores numéricos van de 0 a 6, donde 0 empieza por el domingo.
• Los nombres están en inglés. Por ejemplo: Monday, January.
• Los nombres no distinguen mayúsculas de minúsculas.
• Los nombres se pueden abreviar. Se recomienda usar tres letras para las abreviaturas. Por ejemplo: Mon, Jan.

Ejemplos de NCRONTAB

Estos son algunos ejemplos de expresiones NCRONTAB que puede usar para el desencadenador de temporizador en Azure Functions.

Zonas horarias de NCRONTAB

Los números de una expresión NCRONTAB hacen referencia a una fecha y hora, no a un intervalo de tiempo. Por ejemplo, un 5 en el campo hour hace referencia a las 5:00 a. m., no a cada 5 horas.

La zona horaria predeterminada que se usa con las expresiones CRON es la Hora universal coordinada (UTC). Para que la expresión CRON se base en otra zona horaria, cree una configuración de aplicación para la aplicación de función denominada WEBSITE_TIME_ZONE.

El valor de esta opción de configuración depende del sistema operativo y del plan en el que se ejecuta la aplicación de funciones.

Por ejemplo, la hora del este de EE. UU. (que se representa mediante Eastern Standard Time en Windows o America/New_York en Linux) usa actualmente UTC-05:00 mientras está vigente la hora estándar y UTC-04:00 durante el horario de verano. Para que un desencadenador de temporizador lo ponga en marcha a las 10:00 AM, hora del este, todos los días,cree una configuración de aplicación para la aplicación de funciones denominada WEBSITE_TIME_ZONE, establezca el valor en Eastern Standard Time (Windows) o America/New_York (Linux) y, a continuación, use la siguiente expresión NCRONTAB:

"0 0 10 * * *"

Si usa WEBSITE_TIME_ZONE, la hora se ajusta a los cambios de hora de la zona horaria concreta, lo que incluye el horario de verano, y los cambios en la hora estándar.

TimeSpan

TimeSpan solamente se puede usar para una aplicación de función que se ejecuta en un plan de App Service.

A diferencia de una expresión NCRONTAB, un TimeSpan valor especifica el intervalo de tiempo entre cada invocación de función. Cuando una función se completa después de ejecutarse más tiempo del intervalo especificado, el temporizador vuelve a invocar inmediatamente a la función.

Expresado como una cadena, el formato TimeSpan es hh:mm:ss cuando hh es menor que 24. Si los dos primeros dígitos son 24 o un valor superior, el formato es dd:hh:mm. Estos son algunos ejemplos:

Escalado horizontal

Si una aplicación de función se escala horizontalmente a varias instancias, una sola instancia de una función desencadenada por el temporizador se ejecuta en todas las instancias. No se desencadenará de nuevo si todavía se está ejecutando una invocación pendiente.

Aplicaciones de función que comparten almacenamiento

Si comparte cuentas de almacenamiento en aplicaciones de funciones que no se implementan en app service, es posible que tenga que asignar explícitamente un identificador de host a cada aplicación.

Puede omitir el valor de identificación o establecer manualmente la configuración de identificación de cada aplicación de funciones en otro valor.

El desencadenador de temporizador utiliza un bloqueo de almacenamiento para asegurarse de que solo hay una instancia de temporizador cuando una aplicación de función se escala a varias instancias. Si dos aplicaciones de función comparten la misma configuración de identificación y cada una usa un desencadenador de temporizador, solo se ejecutará un temporizador.

Comportamiento de reintento

A diferencia del desencadenador de cola, el desencadenador de temporizador no vuelve a realizar el intento después de que se produce un error en una función. Cuando se produce un error en una función, no se la llamará nuevamente hasta la próxima vez en la programación.

Invocación manual de un desencadenador de temporizador

El desencadenador de temporizador de Azure Functions proporciona un webhook HTTP que se puede invocar para desencadenar manualmente la función. Esto puede resultar extremadamente útil en los siguientes escenarios.

• Pruebas de integración
• Intercambios de ranura como parte de una prueba de humo o una actividad de calentamiento
• Implementación inicial de una función para rellenar inmediatamente una caché o una tabla de búsqueda en una base de datos

Consulte Ejecución manual de una función no desencadenada por HTTP para obtener más información sobre cómo invocar manualmente una función desencadenada por un temporizador.

Solución de problemas

Para obtener información sobre qué hacer cuando el desencadenador del temporizador no funcione según lo esperado, consulte Investigating and reporting issues with timer triggered functions not firing (Investigación y notificación de problemas en que las funciones desencadenadas por el temporizador no se activan).

Pasos siguientes