Déclencheur de minuteur pour Azure Functions

  • Article

Cet article explique comment utiliser des déclencheurs de minuteur dans Azure Functions. Un déclencheur de minuteur vous permet d’exécuter une fonction de manière planifiée.

Il s’agit des informations de référence pour les développeurs Azure Functions. Si vous ne connaissez pas bien Azure Functions, commencez par consulter les ressources suivantes :

Pour savoir comment exécuter manuellement une fonction déclenchée par un minuteur, consultez Exécuter manuellement une fonction non déclenchée via HTTP.

La prise en charge de cette liaison est automatique dans tous les environnements de développement. Vous n’avez pas besoin d’installer manuellement le package ou d’enregistrer l’extension.

Le code source du package de l’extension du minuteur se trouve dans le référentiel GitHub azure-webjobs-sdk-extensions.

Important

Cet article utilise des onglets pour prendre en charge plusieurs versions du modèle de programmation Node.js. Le modèle v4 est en disponibilité générale. Il est conçu pour offrir une expérience plus flexible et intuitive aux développeurs JavaScript et TypeScript. Pour plus d’informations sur le fonctionnement du modèle v4, reportez-vous au guide du développeur Azure Functions Node.js. Pour plus d’informations sur les différences entre v3 et v4, consultez le guide de migration.

Azure Functions prend en charge deux modèles de programmation pour Python. La façon dont vous définissez vos liaisons dépend du modèle de programmation choisi.

Le modèle de programmation Python v2 vous permet de définir des liaisons à l'aide d’éléments décoratifs directement dans le code de votre fonction Python. Pour plus d’informations, consultez le guide des développeurs Python.

Cet article prend en compte les deux modèles de programmation.

Exemple

Cet exemple montre une fonction C# qui s’exécute chaque fois que les minutes ont une valeur divisible par cinq. Par exemple, lorsque la fonction démarre à 18:55:00, l’exécution suivante a lieu à 19:00:00. Un objet TimerInfo est transmis à la fonction.

Une fonction C# peut être créée à l’aide de l’un des modes C# suivants :

  • Modèle worker isolé : fonction C# compilée exécutée dans un processus worker isolé du runtime. Le processus Worker isolé est requis pour prendre en charge les fonctions C# exécutées sur les versions LTS et non-LTS de .NET et de .NET Framework. Les extensions pour les fonctions de processus de travail isolés utilisent des espaces de noms Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modèle In-process : fonction C# compilée exécutée dans le même processus que le runtime Functions. Dans une variation de ce modèle, Functions peut être exécuté à l’aide de scripts C#, principalement pris en charge pour la modification du portail C#. Les extensions pour les fonctions in-process utilisent des espaces de noms Microsoft.Azure.WebJobs.Extensions.*.

Important

Le support prendra fin pour le modèle in-process le 10 novembre 2026. Nous vous recommandons vivement de migrer vos applications vers le modèle worker isolé pour une prise en charge complète.

//<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));

L’exemple suivant lance et exécute la fonction toutes les cinq minutes. L’annotation @TimerTrigger sur la fonction définit le programme avec le même format de chaîne de caractères que les @TimerTrigger.

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

L’exemple suivant illustre une liaison de déclencheur de minuteur dans un fichier et un code de fonction qui utilise la liaison, où une instance représentant le minuteur est transmise à la fonction. La fonction écrit un journal indiquant si cet appel de fonction est dû à une occurrence de planification manquée. L’exemple varie selon que vous utilisez le modèle de programmation Python v1 ou v2.

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)

L’exemple suivant montre une fonction TypeScript de déclencheur de minuteur.

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

L’exemple suivant montre une fonction JavaScript de déclencheur de minuteur.

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

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

Voici les données de liaison dans le fichier function.json :

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

Voici le code de la fonction de minuteur dans le fichier run.ps1 :

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

Attributs

La bibliothèque C# In-process utilise un TimerTriggerAttribute de Microsoft.Azure.WebJobs.Extensions, tandis que la bibliothèque C# processus Worker isolé utilise un TimerTriggerAttribute de Microsoft.Azure.Functions.Worker.Extensions.Timer pour définir la fonction. Le script C# utilise à la place un fichier de configuration function.json.

Propriété d’attribut Description
Planification Une expression CRON ou une valeur TimeSpan. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service. Vous pouvez placer l’expression de planification dans un paramètre d’application et définir cette propriété selon le nom du paramètre d’application encapsulé entre les signes %, par exemple %ScheduleAppSetting%.
RunOnStartup Si la valeur est true, la fonction est appelée au démarrage du runtime. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité. L’application de fonction redémarre en raison de modifications apportées à la fonction et lorsque l’application de fonction effectue un scale-out. À utiliser avec précaution. La propriété RunOnStartup doit rarement, voire jamais, être définie sur true, notamment en production.
UseMonitor Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non. La surveillance de planification conserve les occurrences de planification pour garantir la maintenance correcte de cette dernière même en cas de redémarrage des instances de l’application de fonction. Si elle n’est pas définie explicitement, la valeur par défaut est true pour les planifications dont l’intervalle de récurrence est supérieur ou égal à 1 minute. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false.

Décorateurs

S’applique uniquement au modèle de programmation Python v2.

Pour les fonctions Python v2 définies à l’aide d’un élément décoratif, les propriétés suivantes sur schedule :

Propriété Description
arg_name Nom de la variable qui représente l’objet de minuteur dans le code de la fonction.
schedule Une expression CRON ou une valeur TimeSpan. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service. Vous pouvez placer l’expression de planification dans un paramètre d’application et définir cette propriété selon le nom du paramètre d’application encapsulé dans les signes % , comme sur cet exemple : « %ScheduleAppSetting% ».
run_on_startup Si la valeur est true, la fonction est appelée au démarrage du runtime. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité. L’application de fonction redémarre en raison de modifications apportées à la fonction et lorsque l’application de fonction effectue un scale-out. À utiliser avec précaution. La propriété runOnStartup doit rarement, voire jamais, être définie sur true, notamment en production.
use_monitor Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non. La surveillance de planification conserve les occurrences de planification pour garantir la maintenance correcte de cette dernière même en cas de redémarrage des instances de l’application de fonction. Si elle n’est pas définie explicitement, la valeur par défaut est true pour les planifications dont l’intervalle de récurrence est supérieur ou égal à 1 minute. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false.

Pour les fonctions Python définies à l’aide de function.json, consultez la section Configuration.

Annotations

L’annotation @TimerTrigger sur la fonction définit le schedule avec le même format de chaîne que les expressions CRON. L’annotation prend en charge les paramètres suivants :

Configuration

S’applique uniquement au modèle de programmation Python v1.

Le tableau suivant explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode app.timer().

Propriété Description
schedule Une expression CRON ou une valeur TimeSpan. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service. Vous pouvez placer l’expression de planification dans un paramètre d’application et définir cette propriété selon le nom du paramètre d’application encapsulé dans les signes % , comme sur cet exemple : « %ScheduleAppSetting% ».
runOnStartup Si la valeur est true, la fonction est appelée au démarrage du runtime. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité. L’application de fonction redémarre en raison de modifications apportées à la fonction et lorsque l’application de fonction effectue un scale-out. À utiliser avec précaution. La propriété runOnStartup doit rarement, voire jamais, être définie sur true, notamment en production.
useMonitor Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non. La surveillance de planification conserve les occurrences de planification pour garantir la maintenance correcte de cette dernière même en cas de redémarrage des instances de l’application de fonction. Si elle n’est pas définie explicitement, la valeur par défaut est true pour les planifications dont l’intervalle de récurrence est supérieur ou égal à 1 minute. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false.

Le tableau suivant décrit les propriétés de configuration de liaison que vous définissez dans le fichier function.json.

Propriété function.json Description
type Doit avoir la valeur « timerTrigger ». Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
direction Doit être défini sur « in ». Cette propriété est définie automatiquement lorsque vous créez le déclencheur dans le portail Azure.
name Nom de la variable qui représente l’objet de minuteur dans le code de la fonction.
schedule Une expression CRON ou une valeur TimeSpan. TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service. Vous pouvez placer l’expression de planification dans un paramètre d’application et définir cette propriété selon le nom du paramètre d’application encapsulé dans les signes % , comme sur cet exemple : « %ScheduleAppSetting% ».
runOnStartup Si la valeur est true, la fonction est appelée au démarrage du runtime. Par exemple, le runtime démarre lorsque l’application de fonction sort de veille après une période d’inactivité. L’application de fonction redémarre en raison de modifications apportées à la fonction et lorsque l’application de fonction effectue un scale-out. À utiliser avec précaution. La propriété runOnStartup doit rarement, voire jamais, être définie sur true, notamment en production.
useMonitor Peut-être défini sur la valeur true ou false pour indiquer si la planification doit être surveillée ou non. La surveillance de planification conserve les occurrences de planification pour garantir la maintenance correcte de cette dernière même en cas de redémarrage des instances de l’application de fonction. Si elle n’est pas définie explicitement, la valeur par défaut est true pour les planifications dont l’intervalle de récurrence est supérieur ou égal à 1 minute. Pour les planifications qui se déclenchent plusieurs fois par minute, la valeur par défaut est false.

Lorsque vous développez en local, ajoutez vos paramètres d’application dans le fichier local.settings.json de la collection Values.

Attention

Ne définissez pas runOnStartup sur true en production. Si vous utilisez cette définition, le code s’exécute à des moments extrêmement imprévisibles. Dans certains paramètres de production, ces exécutions supplémentaires peuvent entraîner des coûts sensiblement plus élevés pour les applications hébergées dans un plan Consommation. Par exemple, avec la propriété runOnStartup activée, le déclencheur est appelé à chaque fois que votre Function App est mise à l’échelle. Veillez à bien comprendre le comportement en production de vos fonctions avant d’activer la propriété runOnStartup en production.

Pour obtenir des exemples complets, consultez la section Exemple.

Usage

Lorsqu’une fonction de déclencheur de minuteur est appelée, l’objet minuteur est transmis à la fonction. Le code JSON suivant est un exemple de représentation de l’objet minuteur.

{
    "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 propriété isPastDue est true lorsque l’appel de fonction en cours arrive plus tard que prévu. Par exemple, un redémarrage de la fonction d’application peut entraîner l’échec d’un appel.

Expressions NCRONTAB

Azure Functions utilise la bibliothèque NCronTab pour interpréter les expressions NCRONTAB. Une expression NCRONTAB est semblable à une expression CRON, à ceci près qu’elle comprend un sixième champ supplémentaire au début pour utiliser la précision de temps en secondes :

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

Chaque champ peut être associé aux types de valeurs suivants :

Type Exemple En cas de déclenchement
Une valeur spécifique 0 5 * * * * Une fois par heure du jour, à la 5e minute de chaque heure
Toutes les valeurs (*) 0 * 5 * * * Une fois par minute, pendant la 5e heure
Une plage (opérateur -) 5-7 * * * * * Trois fois par minute - aux secondes 5 à 7 de chaque minute de chaque heure de chaque jour
Un ensemble de valeurs (opérateur ,) 5,8,10 * * * * * Trois fois par minute - aux secondes 5, 8 et 10 de chaque minute de chaque heure de chaque jour
Une valeur d’intervalle (opérateur /) 0 */5 * * * * 12 fois par heure - à la seconde 0 de la 5e minute de chaque heure de chaque jour

Pour spécifier les mois ou les jours, vous pouvez utiliser des valeurs numériques, des noms ou des abréviations de noms :

  • Pour les jours, les valeurs numériques vont de 0 à 6 (ici, 0 représente « dimanche »).
  • Les noms sont en anglais. Par exemple : Monday, January.
  • Les noms sont sensibles à la casse.
  • Les noms peuvent être abrégés. La longueur d’abréviation recommandée est de trois lettres. Par exemple : Mon, Jan.

Exemples NCRONTAB

Voici quelques exemples d’expressions NCRONTAB que vous pouvez utiliser pour le déclencheur de minuteur dans Azure Functions.

Exemple En cas de déclenchement
0 */5 * * * * une fois toutes les cinq minutes
0 0 * * * * une fois toutes les heures
0 0 */2 * * * une fois toutes les deux heures
0 0 9-17 * * * une fois toutes les heures entre 9h et 17h
0 30 9 * * * à 9h30 tous les jours
0 30 9 * * 1-5 à 9h30 tous les jours de la semaine
0 30 9 * Jan Mon à 9h30 tous les lundis en janvier

Notes

L’expression NCRONTAB prend en charge le format à cinq champs et le format à six champs. Le sixième champ comprend une valeur correspondant aux secondes qui est placée au début de l'expression.

Fuseaux horaires NCRONTAB

Les nombres d’une expression CRON font référence à une heure et à une date, pas à un intervalle de temps. Par exemple, un 5 dans le champ hour correspond à 17h, pas à toutes les 5 heures.

Le fuseau horaire par défaut utilisé avec les expressions CRON est le Temps universel coordonné (UTC). Pour baser votre expression CRON sur un autre fuseau horaire, créez un paramètre d’application nommé WEBSITE_TIME_ZONE pour votre application de fonction.

La valeur de ce paramètre dépend du système d’exploitation et du plan sur lequel l’application de fonction s’exécute.

Système d’exploitation Plan Valeur
Windows Tous Définissez la valeur sur le nom du fuseau horaire souhaité comme indiqué par la deuxième ligne de chaque paire donnée par la commande Windows tzutil.exe /L
Linux Premium
Dédié		 Définissez la valeur sur le nom du fuseau horaire souhaité comme indiqué dans la base de données tz.

Remarque

WEBSITE_TIME_ZONE et TZ ne sont actuellement pas pris en charge lors de l’exécution sur Linux dans un plan Consommation. Dans ce cas, la définition de WEBSITE_TIME_ZONE ou de TZ peut créer des problèmes liés au protocole SSL et entraîner l’arrêt du fonctionnement des métriques pour votre application.

Par exemple, l’heure de la côte est des États-Unis (représentée par Eastern Standard Time (Windows) ou America/New_York (Linux)) utilise actuellement l’heure UTC (temps universel coordonné) 05:00 pendant l’heure standard et l’heure UTC 04:00 pendant l’heure d’été. Pour qu’un déclencheur de minuteur s’active à 10:00 (heure de la côte est) chaque jour, créez un paramètre d’application nommé WEBSITE_TIME_ZONE pour votre application de fonction, définissez la valeur sur Eastern Standard Time (Windows) ou sur America/New_York (Linux), puis utilisez l’expression NCRONTAB suivante :

"0 0 10 * * *"

Quand vous utilisez WEBSITE_TIME_ZONE, l’heure est ajustée en fonction des changements d’heure du fuseau horaire spécifique, notamment pour tenir compte de l’heure d’été et des changements de l’heure standard.

TimeSpan

TimeSpan peut être utilisé uniquement pour une application de fonction qui s’exécute sur un plan App Service.

Contrairement à une expression CRON, une valeur TimeSpan spécifie l’intervalle de temps entre chaque appel de fonction. Quand une fonction se termine après une exécution plus longue que l’intervalle spécifié, le minuteur rappelle immédiatement la fonction.

Exprimé sous forme de chaîne, le format TimeSpan est hh:mm:ss lorsque la valeur de hh est inférieure à 24. Lorsque les deux premiers chiffres sont 24 ou plus, le format est dd:hh:mm. Voici quelques exemples :

Exemple En cas de déclenchement
"01:00:00" toutes les heures
"00:01:00" chaque minute
"25:00:00:00" Tous les 25 jours
"1.00:00:00" chaque jour

Montée en charge

Si une application de fonction augmente la taille de plusieurs instances, une seule instance de fonction déclenchée par minuteur est exécutée sur toutes les instances. Elle ne se déclenchera plus si un appel en attente est toujours en cours d’exécution.

Applications de fonction qui partagent du stockage

Si vous partagez des comptes de stockage entre des applications de fonction qui ne sont pas déployées sur App Service, vous devrez peut-être affecter explicitement l’ID d’hôte à chaque application.

Version de Functions Paramètre
2.x (et ultérieures) AzureFunctionsWebHost__hostid variable d’environnement
1.x id dans id

Vous pouvez omettre la valeur d’identification ou définir manuellement la configuration d’identification de chaque application de fonction sur une valeur différente.

Le déclencheur du minuteur utilise un verrou de stockage pour s’assurer qu’il n’y a qu’une seule instance du minuteur lorsqu’une application de fonction augmente la taille de plusieurs instances. Si deux applications de fonction partagent la même configuration d’identification et que chacune utilise un déclencheur de minuteur, un seul minuteur s’exécute.

Comportement pour les nouvelles tentatives

À la différence du déclencheur de file d’attente, le déclencheur de minuteur n’effectue pas de nouvelle tentative après l’échec d’une fonction. En cas d’échec d’une fonction, elle n’est pas rappelée avant la prochaine période planifiée.

Appeler manuellement un déclencheur de retardateur

Le déclencheur de retardateur pour Azure Functions fournit un webhook HTTP qui peut être appelé pour déclencher manuellement la fonction. Cela peut être très utile dans les scénarios suivants.

  • Tests d’intégration
  • Échanges d’emplacements dans le cadre d’une activité de test d'acceptation de build ou de préparation
  • Déploiement initial d’une fonction pour remplir immédiatement un cache ou une table de recherche dans une base de données

Veuillez consulter Exécuter manuellement une fonction non déclenchée via HTTP pour plus de détails sur la façon d’appeler manuellement une fonction déclenchée par un retardateur.

Dépannage

Pour plus d’informations sur la procédure à suivre lorsque le déclencheur du minuteur ne fonctionne pas comme prévu, consultez Investigating and reporting issues with timer triggered functions not firing (Examen et rapport des problèmes concernant l’absence de déclenchement des fonctions déclenchées par minuteur).

Étapes suivantes

Accéder à un guide de démarrage rapide qui utilise un déclencheur de minuteur

En savoir plus sur les déclencheurs et les liaisons Azure Functions