Desencadenador de temporizador para Azure FunctionsTimer trigger for Azure Functions

En este artículo se explica cómo usar desencadenadores de temporizador en Azure Functions.This article explains how to work with timer triggers in Azure Functions. Con un desencadenador de temporizador puede ejecutar una función de forma programada.A timer trigger lets you run a function on a schedule.

Esta es la información de referencia para desarrolladores de Azure Functions.This is reference information for Azure Functions developers. Si está familiarizado con Azure Functions, comience con los siguientes recursos:If you're new to Azure Functions, start with the following resources:

Paquetes: Functions 1.xPackages - Functions 1.x

El desencadenador del temporizador se proporciona en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid, versión 2.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 2.x. El código fuente del paquete está en el repositorio azure-webjobs-sdk-extensions de GitHub.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

En todos los entornos de desarrollo, se proporciona automáticamente compatibilidad para este enlace.Support for this binding is automatically provided in all development environments. No tiene que instalar el paquete manualmente ni que registrar la extensión.You don't have to manually install the package or register the extension.

Paquetes: Functions 2.xPackages - Functions 2.x

El desencadenador del temporizador se proporciona en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid, versión 3.x.The timer trigger is provided in the Microsoft.Azure.WebJobs.Extensions NuGet package, version 3.x. El código fuente del paquete está en el repositorio azure-webjobs-sdk-extensions de GitHub.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

En todos los entornos de desarrollo, se proporciona automáticamente compatibilidad para este enlace.Support for this binding is automatically provided in all development environments. No tiene que instalar el paquete manualmente ni que registrar la extensión.You don't have to manually install the package or register the extension.

EjemploExample

Vea el ejemplo específico del lenguaje:See the language-specific example:

Ejemplo de C#C# example

El ejemplo siguiente se muestra un C# función que se ejecuta cada vez que los minutos tienen un valor divisible por cinco (por ejemplo, si la función se inicia a las 18:57:00, será el rendimiento de próxima a 19:00:00).The following example shows a C# function that is executed each time the minutes have a value divisible by five (eg if the function starts at 18:57:00, the next performance will be at 19:00:00). El TimerInfo objeto se pasa a la función.The TimerInfo object is passed into the function.

[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}");
}

Ejemplo de script de C#C# script example

En el ejemplo siguiente se muestra un enlace de desencadenador de temporizador en un archivo function.json y una función de script de C# que usa el enlace.The following example shows a timer trigger binding in a function.json file and a C# script function that uses the binding. La función escribe un registro que indica si esta invocación de función se debe a una repetición de la programación no ejecutada.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. El TimerInfo objeto se pasa a la función.The TimerInfo object is passed into the function.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

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

Este es el código de script de C#:Here's the C# script code:

public static void Run(TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}" );  
}

Ejemplo de F#F# example

En el ejemplo siguiente se muestra un enlace de desencadenador de temporizador en un archivo function.json y una función de script de F# que usa el enlace.The following example shows a timer trigger binding in a function.json file and an F# script function that uses the binding. La función escribe un registro que indica si esta invocación de función se debe a una repetición de la programación no ejecutada.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. El TimerInfo objeto se pasa a la función.The TimerInfo object is passed into the function.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

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

Este es el código del script de F#:Here's the F# script code:

let Run(myTimer: TimerInfo, log: ILogger ) =
    if (myTimer.IsPastDue) then
        log.LogInformation("F# function is running late.")
    let now = DateTime.Now.ToLongTimeString()
    log.LogInformation(sprintf "F# function executed at %s!" now)

Ejemplo de JavaScriptJavaScript example

En el ejemplo siguiente se muestra un enlace de desencadenador de temporizador en un archivo function.json y una función de JavaScript que usa el enlace.The following example shows a timer trigger binding in a function.json file and a JavaScript function that uses the binding. La función escribe un registro que indica si esta invocación de función se debe a una repetición de la programación no ejecutada.The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. Un objeto timer se pasa a la función.A timer object is passed into the function.

Estos son los datos de enlace del archivo function.json:Here's the binding data in the function.json file:

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

Este es el código de JavaScript:Here's the JavaScript code:

module.exports = 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);   

    context.done();
};

Ejemplo de JavaJava example

El la función de ejemplo siguiente se desencadena y se ejecuta cada cinco minutos.The following example function triggers and executes every five minutes. La anotación @TimerTrigger en la función define la programación con el mismo formato de cadena que las expresiones CRON.The @TimerTrigger annotation on the function defines the schedule using the same string format as CRON expressions.

@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);
}

AtributosAttributes

En las bibliotecas de clases de C#, use el atributo TimerTriggerAttribute.In C# class libraries, use the TimerTriggerAttribute.

El constructor del atributo toma una expresión CRON o TimeSpan.The attribute's constructor takes a CRON expression or a TimeSpan. Puede usar TimeSpan solamente si la aplicación de función se ejecuta en un plan de App Service.You can use TimeSpan only if the function app is running on an App Service plan. En el ejemplo siguiente se muestra una expresión CRON:The following example shows a CRON expression:

[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}");
}

ConfiguraciónConfiguration

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json y el atributo TimerTrigger.The following table explains the binding configuration properties that you set in the function.json file and the TimerTrigger attribute.

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Debe establecerse en "timerTrigger".Must be set to "timerTrigger". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Debe establecerse en "in".Must be set to "in". Esta propiedad se establece automáticamente cuando se crea el desencadenador en Azure Portal.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a Nombre de la variable que representa el objeto de temporizador en el código de la función.The name of the variable that represents the timer object in function code.
scheduleschedule ScheduleExpressionScheduleExpression Una expresión CRON o un valor TimeSpan.A CRON expression or a TimeSpan value. TimeSpan solamente se puede usar para una aplicación de función que se ejecuta en un plan de App Service.A TimeSpan can be used only for a function app that runs on an App Service Plan. Puede colocar la expresión de programación en una configuración de aplicación y establecer esta propiedad en el nombre de dicha configuración encapsulado en signos %, como en este ejemplo: "%ScheduleAppSetting%".You can put the schedule expression in an app setting and set this property to the app setting name wrapped in % signs, as in this example: "%ScheduleAppSetting%".
runOnStartuprunOnStartup RunOnStartupRunOnStartup Si true, la función se invoca cuando se inicia el entorno de ejecución.If true, the function is invoked when the runtime starts. Por ejemplo, el entorno de ejecución se inicia cuando la aplicación de función se reactiva después de estar inactiva por inactividad,For example, the runtime starts when the function app wakes up after going idle due to inactivity. cuando la aplicación de función se reinicia debido a cambios de función y cuando la aplicación de función se escala horizontalmente. Por lo tanto, runOnStartup muy pocas veces, si acaso, se debe establecer en true, especialmente en producción.when the function app restarts due to function changes, and when the function app scales out. So runOnStartup should rarely if ever be set to true, especially in production.
useMonitoruseMonitor useMonitorUseMonitor Establezca esta propiedad en true o false para indicar si la programación se debe supervisar.Set to true or false to indicate whether the schedule should be monitored. La supervisión de la programación conserva las apariciones de programación para ayudar a garantizar que la programación se mantiene correctamente aunque las instancias de aplicación de función se reinicien.Schedule monitoring persists schedule occurrences to aid in ensuring the schedule is maintained correctly even when function app instances restart. Si no se establece explícitamente, el valor predeterminado es true para las programaciones que tienen un intervalo de periodicidad suprior a 1 minuto.If not set explicitly, the default is true for schedules that have a recurrence interval greater than 1 minute. Para las programaciones que se desencadenan más de una vez por minuto, el valor predeterminado es false.For schedules that trigger more than once per minute, the default is false.

Cuando desarrolla localmente, la configuración de aplicación pasa al archivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Precaución

No se recomienda establecer runOnStartup en true en producción.We recommend against setting runOnStartup to true in production. Con esta configuración, el código se ejecuta en momentos altamente impredecibles.Using this setting makes code execute at highly unpredictable times. En ciertas configuraciones de producción, estas ejecuciones adicionales pueden dar lugar a costos considerablemente mayores para las aplicaciones hospedadas en los planes de consumo.In certain production settings, these extra executions can result in significantly higher costs for apps hosted in Consumption plans. Por ejemplo, con runOnStartup habilitado el desencadenador se invoca cada vez que se escala la aplicación de función.For example, with runOnStartup enabled the trigger is invoked whenever your function app is scaled. Asegúrese de comprender perfectamente el comportamiento de producción de las funciones antes de habilitar runOnStartup en producción.Make sure you fully understand the production behavior of your functions before enabling runOnStartup in production.

UsoUsage

Cuando se invoca una función de desencadenador de temporizador, se pasa un objeto de temporizador a la función.When a timer trigger function is invoked, a timer object is passed into the function. La siguiente función JSON es un ejemplo que representa el objeto de temporizador.The following JSON is an example representation of the timer object.

{
    "Schedule":{
    },
    "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.The IsPastDue property is true when the current function invocation is later than scheduled. Por ejemplo, un reinicio de aplicación de función podría provocar la ausencia de una invocación.For example, a function app restart might cause an invocation to be missed.

Expresiones CRONCRON expressions

Azure Functions usa la biblioteca NCronTab para interpretar expresiones CRON.Azure Functions uses the NCronTab library to interpret CRON expressions. Una expresión CRON incluye seis campos:A CRON expression includes six fields:

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

Cada campo puede tener uno de los siguientes tipos de valores:Each field can have one of the following types of values:

TypeType EjemploExample Cuándo se desencadenaWhen triggered
Un valor específicoA specific value "0 5 * * * *""0 5 * * * *" A las hh:05:00, donde hh es cada hora (una vez por hora)at hh:05:00 where hh is every hour (once an hour)
Todos los valores (*)All values (*) "0 * 5 * * *""0 * 5 * * *" A las 5:mm: 00 cada día, donde mm es cada minuto de la hora (60 veces al día)at 5:mm:00 every day, where mm is every minute of the hour (60 times a day)
Un intervalo (operador -)A range (- operator) "5-7 * * * * *""5-7 * * * * *" A las hh:mm:05, hh:mm:06 y hh:mm:07, donde hh:mm es cada minuto de cada hora (tres veces por minuto)at hh:mm:05,hh:mm:06, and hh:mm:07 where hh:mm is every minute of every hour (3 times a minute)
Un conjunto de valores (operador ,)A set of values (, operator) "5,8,10 * * * * *""5,8,10 * * * * *" A las hh:mm:05, hh:mm:08 y hh:mm:10, donde hh:mm es cada minuto de cada hora (tres veces por minuto)at hh:mm:05,hh:mm:08, and hh:mm:10 where hh:mm is every minute of every hour (3 times a minute)
Un valor de intervalo (operador /)An interval value (/ operator) "0 */5 * * * *""0 */5 * * * *" A las hh:05:00, hh:10:00, hh:15:00 y así sucesivamente hasta hh:55:00, donde hh es cada hora (doce veces por hora)at hh:05:00, hh:10:00, hh:15:00, and so on through hh:55:00 where hh is every hour (12 times an hour)

Para especificar meses o días puede usar valores numéricos, nombres o abreviaturas de nombres:To specify months or days you can use numeric values, names, or abbreviations of names:

  • Para los días, los valores numéricos van de 0 a 6, donde 0 comienza con el domingo.For days, the numeric values are 0 to 6 where 0 starts with Sunday.
  • Los nombres están en inglés.Names are in English. Por ejemplo: Monday, January.For example: Monday, January.
  • Los nombres no distinguen mayúsculas de minúsculas.Names are case-insensitive.
  • Los nombres se pueden abreviar.Names can be abbreviated. La longitud recomendada para la abreviatura es de tres letras.Three letters is the recommended abbreviation length. Por ejemplo: Mon, Jan.For example: Mon, Jan.

Ejemplos CRONCRON examples

Estos son algunos ejemplos de expresiones CRON que puede usar para el desencadenador de temporizador en Azure Functions.Here are some examples of CRON expressions you can use for the timer trigger in Azure Functions.

EjemploExample Cuándo se desencadenaWhen triggered
"0 */5 * * * *" Una vez cada cinco minutosonce every five minutes
"0 0 * * * *" Una vez al principio de cada horaonce at the top of every hour
"0 0 */2 * * *" Una vez cada dos horasonce every two hours
"0 0 9-17 * * *" Una vez cada hora de 9 a. m. a 5 p. m.once every hour from 9 AM to 5 PM
"0 30 9 * * *" A las 9:30 a. m. todos los díasat 9:30 AM every day
"0 30 9 * * 1-5" A las 9:30 a. m. cada día de la semanaat 9:30 AM every weekday
"0 30 9 * Jan Mon" A las 9:30 a. m. todos los lunes en eneroat 9:30 AM every Monday in January

Nota

Puede encontrar ejemplos de expresiones CRON en línea, pero muchas de ellas omiten el campo {second}.You can find CRON expression examples online, but many of them omit the {second} field. Si copia información de uno de ellos, agregue el campo que falta, {second}.If you copy from one of them, add the missing {second} field. Por lo general querrá un cero en ese campo, no un asterisco.Usually you'll want a zero in that field, not an asterisk.

Zonas horarias CRONCRON time zones

Los números de una expresión CRON hacen referencia a una hora y fecha, no un intervalo de tiempo.The numbers in a CRON expression refer to a time and date, not a time span. Por ejemplo, un 5 en el campo hour hace referencia a las 5:00 a. m., no a cada 5 horas.For example, a 5 in the hour field refers to 5:00 AM, not every 5 hours.

La zona horaria predeterminada que se usa con las expresiones CRON es la Hora universal coordinada (UTC).The default time zone used with the CRON expressions is Coordinated Universal Time (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.To have your CRON expression based on another time zone, create an app setting for your function app named WEBSITE_TIME_ZONE. Establezca el valor en el nombre de la zona horaria deseada como se muestra en Microsoft Time Zone Index (Índice de zona horaria de Microsoft).Set the value to the name of the desired time zone as shown in the Microsoft Time Zone Index.

Por ejemplo, la Hora estándar del Este (EST) es UTC-05:00.For example, Eastern Standard Time is UTC-05:00. Para que el desencadenador de temporizador se dispare a las 10 a.m. (Hora estándar), use la siguiente expresión CRON que representa la zona horaria UTC:To have your timer trigger fire at 10:00 AM EST every day, use the following CRON expression that accounts for UTC time zone:

"schedule": "0 0 15 * * *"

O bien, cree una configuración de aplicación para la aplicación de función denominada WEBSITE_TIME_ZONE y establecer el valor en Hora estándar del Este.Or create an app setting for your function app named WEBSITE_TIME_ZONE and set the value to Eastern Standard Time. A continuación, utilice la siguiente expresión CRON:Then uses the following CRON expression:

"schedule": "0 0 10 * * *"

Si usa WEBSITE_TIME_ZONE, la hora se ajusta a los cambios de hora de la zona horaria en cuestión como, por ejemplo, al horario de verano.When you use WEBSITE_TIME_ZONE, the time is adjusted for time changes in the specific timezone, such as daylight savings time.

TimeSpanTimeSpan

TimeSpan solamente se puede usar para una aplicación de función que se ejecuta en un plan de App Service.A TimeSpan can be used only for a function app that runs on an App Service Plan.

A diferencia de una expresión CRON, un valor TimeSpan especifica el intervalo de tiempo entre cada invocación de función.Unlike a CRON expression, a TimeSpan value specifies the time interval between each function invocation. 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.When a function completes after running longer than the specified interval, the timer immediately invokes the function again.

Expresado como una cadena, el formato TimeSpan es hh:mm:ss cuando hh es menor que 24.Expressed as a string, the TimeSpan format is hh:mm:ss when hh is less than 24. Si los dos primeros dígitos son 24 o un valor superior, el formato es dd:hh:mm.When the first two digits are 24 or greater, the format is dd:hh:mm. A continuación se muestran algunos ejemplos:Here are some examples:

EjemploExample Cuándo se desencadenaWhen triggered
"01:00:00""01:00:00" Cada horaevery hour
"00:01:00""00:01:00" Cada minutoevery minute
"24:00:00""24:00:00" Todos los díaseveryday

Escalado horizontalScale-out

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.If a function app scales out to multiple instances, only a single instance of a timer-triggered function is run across all instances.

Aplicaciones de función que comparten almacenamientoFunction apps sharing Storage

Si comparte una cuenta de almacenamiento entre varias aplicaciones de función, asegúrese de que cada aplicación de función tiene otro id en host.json.If you share a Storage account across multiple function apps, make sure that each function app has a different id in host.json. Puede omitir la propiedad id o establecer manualmente el id de cada aplicación de función en un valor diferente.You can omit the id property or manually set each function app's id to a different value. 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.The timer trigger uses a storage lock to ensure that there will be only one timer instance when a function app scales out to multiple instances. Si dos aplicaciones de función comparten el mismo id y cada una usa un desencadenador de temporizador, solo se ejecutará un temporizador.If two function apps share the same id and each uses a timer trigger, only one timer will run.

Comportamiento de reintentoRetry behavior

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.Unlike the queue trigger, the timer trigger doesn't retry after a function fails. Cuando se produce un error en una función, no se la llamará nuevamente hasta la próxima vez en la programación.When a function fails, it isn't called again until the next time on the schedule.

solución de problemasTroubleshooting

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).For information about what to do when the timer trigger doesn't work as expected, see Investigating and reporting issues with timer triggered functions not firing.

Pasos siguientesNext steps