Déclencheur de minuteur pour Azure Functions

  • Article
  • 15 minutes de lecture

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.

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 :

  • Bibliothèque de classes in-process : fonction C# compilée exécutée dans le même processus que le runtime Functions.
  • Bibliothèque de classes de processus Worker isolé : fonction C# compilée exécutée dans un processus Worker isolé du runtime. Un processus Worker isolé est nécessaire pour prendre en charge les fonctions C# s’exécutant sur les versions non LTS de .NET et du .NET Framework.
  • Script C# : principalement utilisé lors de la création de fonctions C# dans le Portail Azure.
[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}");
}

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 function.json 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.

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

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

Voici le code JavaScript :

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

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"

Voici le code Python, où l’objet transmis à la fonction est de type Objet azure.functions.TimerRequest.

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)

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.

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

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 .

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
}

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, à partir de 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.

Notes

WEBSITE_TIME_ZONE n’est pas pris en charge sur le plan consommation Linux.

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