Timertrigger voor Azure Functions

  • Artikel

In dit artikel wordt uitgelegd hoe u werkt met timertriggers in Azure Functions. Met een timertrigger kunt u een functie volgens een schema uitvoeren.

Dit is referentie-informatie voor Azure Functions-ontwikkelaars. Als u nog geen ervaring hebt met Azure Functions, begint u met de volgende resources:

Zie Handmatig een niet door HTTP geactiveerde functie uitvoeren voor meer informatie over het handmatig uitvoeren van een door een timer geactiveerde functie.

Ondersteuning voor deze binding wordt automatisch aangeboden in alle ontwikkelomgevingen. U hoeft het pakket niet handmatig te installeren of de uitbreiding te registreren.

De broncode voor het timeruitbreidingspakket bevindt zich in de GitHub-opslagplaats azure-webjobs-sdk-extensions .

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Met het Python v2-programmeermodel kunt u bindingen definiëren met behulp van decorators rechtstreeks in uw Python-functiecode. Zie de Ontwikkelaarshandleiding voor Python voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

In dit voorbeeld ziet u een C#-functie die wordt uitgevoerd telkens wanneer de minuten een waarde deelbaar hebben met vijf. Wanneer de functie bijvoorbeeld begint om 18:55:00, is de volgende uitvoering om 19:00:00 uur. Er wordt een TimerInfo object doorgegeven aan de functie.

U kunt een C#-functie maken met behulp van een van de volgende C#-modi:

  • Geïsoleerd werkrolmodel: gecompileerde C#-functie die wordt uitgevoerd in een werkproces dat is geïsoleerd van de runtime. Geïsoleerd werkproces is vereist voor de ondersteuning van C#-functies die worden uitgevoerd op LTS- en niet-LTS-versies .NET en .NET Framework. Extensies voor geïsoleerde werkprocesfuncties maken gebruik van Microsoft.Azure.Functions.Worker.Extensions.* naamruimten.
  • In-process model: gecompileerde C#-functie die wordt uitgevoerd in hetzelfde proces als de Functions-runtime. In een variatie van dit model kunnen functies worden uitgevoerd met behulp van C#-scripting. Dit wordt voornamelijk ondersteund voor het bewerken van de C#-portal. Extensies voor in-process-functies maken gebruik van Microsoft.Azure.WebJobs.Extensions.* naamruimten.

Belangrijk

De ondersteuning wordt beëindigd voor het in-process model op 10 november 2026. We raden u ten zeerste aan uw apps te migreren naar het geïsoleerde werkrolmodel voor volledige ondersteuning.

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

Met de volgende voorbeeldfunctie wordt elke vijf minuten geactiveerd en uitgevoerd. De @TimerTrigger aantekening in de functie definieert het schema met dezelfde tekenreeksindeling als CRON-expressies.

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

In het volgende voorbeeld ziet u een timertriggerbinding en functiecode die gebruikmaakt van de binding, waarbij een exemplaar dat de timer vertegenwoordigt, wordt doorgegeven aan de functie. De functie schrijft een logboek dat aangeeft of deze functie aanroep te wijten is aan een gemiste planning. Het voorbeeld is afhankelijk van of u het python-programmeermodel v1 of v2 gebruikt.

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)

In het volgende voorbeeld ziet u een TypeScript-functie voor een timertrigger.

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

In het volgende voorbeeld ziet u een JavaScript-functie voor een timertrigger.

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

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

Dit zijn de bindingsgegevens in het bestand function.json :

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

Hier volgt de timerfunctiecode in het bestand 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"

Kenmerken

In-process C#-bibliotheek maakt gebruik van TimerTriggerAttribute van Microsoft.Azure.WebJobs.Extensions, terwijl de C#-bibliotheek voor geïsoleerde werkprocessen gebruikmaakt van TimerTriggerAttribute van Microsoft.Azure.Functions.Worker.Extensions.Timer om de functie te definiëren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand.

Kenmerkeigenschap Beschrijving
Plannen Een CRON-expressie of een TimeSpan-waarde . Een TimeSpan kan alleen worden gebruikt voor een functie-app die wordt uitgevoerd op een App Service-plan. U kunt de planningsexpressie in een app-instelling plaatsen en deze eigenschap instellen op de naam van de app-instelling die is verpakt in % tekens, zoals %ScheduleAppSetting%.
RunOnStartup Als true, wordt de functie aangeroepen wanneer de runtime wordt gestart. De runtime wordt bijvoorbeeld gestart wanneer de functie-app wordt geactiveerd nadat deze inactief is gegaan vanwege inactiviteit. wanneer de functie-app opnieuw wordt opgestart als gevolg van functiewijzigingen en wanneer de functie-app wordt uitgeschaald. Wees voorzichtig.RunOnStartup moet zelden worden ingesteld trueop , met name in productie.
UseMonitor Stel in op true of false om aan te geven of de planning moet worden bewaakt. Planningsbewaking houdt de planningsexemplaren vast om ervoor te zorgen dat de planning correct wordt onderhouden, zelfs wanneer exemplaren van de functie-app opnieuw worden opgestart. Als deze niet expliciet is ingesteld, is true de standaardwaarde voor schema's met een terugkeerinterval dat groter is dan of gelijk is aan 1 minuut. Voor schema's die meer dan één keer per minuut worden geactiveerd, is de standaardwaarde false.

Decorators

Is alleen van toepassing op het Python v2-programmeermodel.

Voor Python v2-functies die zijn gedefinieerd met behulp van een decorator, zijn de volgende eigenschappen op het schedulevolgende:

Eigenschappen Beschrijving
arg_name De naam van de variabele die het timerobject in functiecode vertegenwoordigt.
schedule Een CRON-expressie of een TimeSpan-waarde . Een TimeSpan kan alleen worden gebruikt voor een functie-app die wordt uitgevoerd op een App Service-plan. U kunt de planningsexpressie in een app-instelling plaatsen en deze eigenschap instellen op de naam van de app-instelling die is verpakt in % tekens, zoals in dit voorbeeld: %ScheduleAppSetting%.
run_on_startup Als true, wordt de functie aangeroepen wanneer de runtime wordt gestart. De runtime wordt bijvoorbeeld gestart wanneer de functie-app wordt geactiveerd nadat deze inactief is gegaan vanwege inactiviteit. wanneer de functie-app opnieuw wordt opgestart als gevolg van functiewijzigingen en wanneer de functie-app wordt uitgeschaald. Wees voorzichtig.runOnStartup moet zelden worden ingesteld trueop , met name in productie.
use_monitor Stel in op true of false om aan te geven of de planning moet worden bewaakt. Planningsbewaking houdt de planningsexemplaren vast om ervoor te zorgen dat de planning correct wordt onderhouden, zelfs wanneer exemplaren van de functie-app opnieuw worden opgestart. Als deze niet expliciet is ingesteld, is true de standaardwaarde voor schema's met een terugkeerinterval dat groter is dan of gelijk is aan 1 minuut. Voor schema's die meer dan één keer per minuut worden geactiveerd, is de standaardwaarde false.

Zie de sectie Configuratie voor Python-functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

De @TimerTrigger aantekening voor de functie definieert het schedule gebruik van dezelfde tekenreeksindeling als CRON-expressies. De aantekening ondersteunt de volgende instellingen:

Configuratie

Is alleen van toepassing op het Python v1-programmeermodel.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de app.timer() methode is doorgegeven.

Eigenschappen Beschrijving
schedule Een CRON-expressie of een TimeSpan-waarde . Een TimeSpan kan alleen worden gebruikt voor een functie-app die wordt uitgevoerd op een App Service-plan. U kunt de planningsexpressie in een app-instelling plaatsen en deze eigenschap instellen op de naam van de app-instelling die is verpakt in % tekens, zoals in dit voorbeeld: %ScheduleAppSetting%.
runOnStartup Als true, wordt de functie aangeroepen wanneer de runtime wordt gestart. De runtime wordt bijvoorbeeld gestart wanneer de functie-app wordt geactiveerd nadat deze inactief is gegaan vanwege inactiviteit. wanneer de functie-app opnieuw wordt opgestart als gevolg van functiewijzigingen en wanneer de functie-app wordt uitgeschaald. Wees voorzichtig.runOnStartup moet zelden worden ingesteld trueop , met name in productie.
useMonitor Stel in op true of false om aan te geven of de planning moet worden bewaakt. Planningsbewaking houdt de planningsexemplaren vast om ervoor te zorgen dat de planning correct wordt onderhouden, zelfs wanneer exemplaren van de functie-app opnieuw worden opgestart. Als deze niet expliciet is ingesteld, is true de standaardwaarde voor schema's met een terugkeerinterval dat groter is dan of gelijk is aan 1 minuut. Voor schema's die meer dan één keer per minuut worden geactiveerd, is de standaardwaarde false.

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld.

function.json-eigenschap Beschrijving
type Moet zijn ingesteld op 'timerTrigger'. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
direction Moet zijn ingesteld op 'in'. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
name De naam van de variabele die het timerobject in functiecode vertegenwoordigt.
schedule Een CRON-expressie of een TimeSpan-waarde . Een TimeSpan kan alleen worden gebruikt voor een functie-app die wordt uitgevoerd op een App Service-plan. U kunt de planningsexpressie in een app-instelling plaatsen en deze eigenschap instellen op de naam van de app-instelling die is verpakt in % tekens, zoals in dit voorbeeld: %ScheduleAppSetting%.
runOnStartup Als true, wordt de functie aangeroepen wanneer de runtime wordt gestart. De runtime wordt bijvoorbeeld gestart wanneer de functie-app wordt geactiveerd nadat deze inactief is gegaan vanwege inactiviteit. wanneer de functie-app opnieuw wordt opgestart als gevolg van functiewijzigingen en wanneer de functie-app wordt uitgeschaald. Wees voorzichtig.runOnStartup moet zelden worden ingesteld trueop , met name in productie.
useMonitor Stel in op true of false om aan te geven of de planning moet worden bewaakt. Planningsbewaking houdt de planningsexemplaren vast om ervoor te zorgen dat de planning correct wordt onderhouden, zelfs wanneer exemplaren van de functie-app opnieuw worden opgestart. Als deze niet expliciet is ingesteld, is true de standaardwaarde voor schema's met een terugkeerinterval dat groter is dan of gelijk is aan 1 minuut. Voor schema's die meer dan één keer per minuut worden geactiveerd, is de standaardwaarde false.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

Let op

RunOnStartuptrue niet instellen in productie. Door deze instelling te gebruiken, wordt code op zeer onvoorspelbare tijden uitgevoerd. In bepaalde productie-instellingen kunnen deze extra uitvoeringen leiden tot aanzienlijk hogere kosten voor apps die worden gehost in een Verbruiksabonnement. Als runOnStartup bijvoorbeeld is ingeschakeld, wordt de trigger aangeroepen wanneer uw functie-app wordt geschaald. Zorg ervoor dat u het productiegedrag van uw functies volledig begrijpt voordat u runOnStartup inschakelt in productie.

Zie de sectie Voorbeeld voor volledige voorbeelden.

Gebruik

Wanneer een timertriggerfunctie wordt aangeroepen, wordt een timerobject doorgegeven aan de functie. De volgende JSON is een voorbeeldweergave van het timerobject.

{
    "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
}

De isPastDue eigenschap is true wanneer de huidige functie aanroep later is dan gepland. Het opnieuw opstarten van een functie-app kan bijvoorbeeld ertoe leiden dat een aanroep wordt gemist.

NCRONTAB-expressies

Azure Functions maakt gebruik van de NCronTab-bibliotheek om NCRONTAB-expressies te interpreteren. Een NCRONTAB-expressie is vergelijkbaar met een CRON-expressie, behalve dat deze een extra zesde veld aan het begin bevat voor tijdsprecisie in seconden:

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

Elk veld kan een van de volgende typen waarden hebben:

Type Opmerking Wanneer geactiveerd
Een specifieke waarde 0 5 * * * * Eenmaal elk uur van de dag op minuut 5 van elk uur
Alle waarden (*) 0 * 5 * * * Op elke minuut in het uur, gedurende uur 5
Een bereik (- operator) 5-7 * * * * * Drie keer per minuut - bij seconden 5 tot en met 7 gedurende elke minuut van elk uur van elke dag
Een set waarden (, operator) 5,8,10 * * * * * Drie keer per minuut - bij seconden 5, 8 en 10 gedurende elke minuut van elk uur van elke dag
Een intervalwaarde (/ operator) 0 */5 * * * * 12 keer per uur - op seconde 0 van elke 5e minuut van elk uur van elke dag

Als u maanden of dagen wilt opgeven, kunt u numerieke waarden, namen of afkortingen van namen gebruiken:

  • Voor dagen zijn de numerieke waarden 0 tot en met 6, waarbij 0 voor zondag staat.
  • De namen zijn in het Engels. Bijvoorbeeld: Monday, January.
  • Namen zijn niet hoofdlettergevoelig.
  • Namen kunnen worden afgekort. Drie letters is de aanbevolen lengte voor afkortingen. Bijvoorbeeld: Mon, Jan.

NCRONTAB-voorbeelden

Hier volgen enkele voorbeelden van NCRONTAB-expressies die u kunt gebruiken voor de timertrigger in Azure Functions.

Opmerking Wanneer geactiveerd
0 */5 * * * * eenmaal om de vijf minuten
0 0 * * * * eenmaal bovenaan elk uur
0 0 */2 * * * eenmaal om de twee uur
0 0 9-17 * * * eenmaal per uur van 9:00 tot 17:00 uur
0 30 9 * * * om 9:30 uur elke dag
0 30 9 * * 1-5 om 9:30 uur elke weekdag
0 30 9 * Jan Mon om 9:30 uur elke maandag in januari

Notitie

NCRONTAB-expressie ondersteunt zowel vijf velden als zes veldindelingen. De zesde veldpositie is een waarde voor seconden die aan het begin van de expressie wordt geplaatst.

NCRONTAB-tijdzones

De getallen in een CRON-expressie verwijzen naar een tijd en datum, niet naar een tijdsperiode. Een 5 in het hour veld verwijst bijvoorbeeld naar 5:00 uur, niet om de 5 uur.

De standaardtijdzone die wordt gebruikt met CRON-expressies is Coordinated Universal Time (UTC). Als u uw CRON-expressie wilt laten gebaseerd op een andere tijdzone, maakt u een app-instelling voor uw functie-app met de naam WEBSITE_TIME_ZONE.

De waarde van deze instelling is afhankelijk van het besturingssysteem en de planning waarop uw functie-app wordt uitgevoerd.

Besturingssysteem Plannen Weergegeven als
Windows Alle Stel de waarde in op de naam van de gewenste tijdzone, zoals opgegeven door de tweede regel van elk paar dat is opgegeven door de Windows-opdracht tzutil.exe /L
Linux Premium
Toegewezen		 Stel de waarde in op de naam van de gewenste tijdzone, zoals wordt weergegeven in de tz-database.

Notitie

WEBSITE_TIME_ZONE en TZ worden momenteel niet ondersteund bij uitvoering op Linux in een verbruiksabonnement. In dit geval kunt u ssl-gerelateerde problemen instellen WEBSITE_TIME_ZONE of TZ maken en ervoor zorgen dat metrische gegevens niet meer werken voor uw app.

Eastern Time in de VS (vertegenwoordigd door Eastern Standard Time (Windows) of America/New_York (Linux)) gebruikt momenteel UTC-05:00 tijdens de standaardtijd en UTC-04:00 tijdens de zomertijd. Als u elke dag een timertrigger wilt activeren om 10:00 uur Eastern Time, maakt u een app-instelling voor uw functie-app met de naam WEBSITE_TIME_ZONE, stelt u de waarde Eastern Standard Time in op (Windows) of America/New_York (Linux) en gebruikt u vervolgens de volgende NCRONTAB-expressie:

"0 0 10 * * *"

Wanneer u de tijd gebruikt WEBSITE_TIME_ZONE , wordt aangepast voor tijdwijzigingen in de specifieke tijdzone, inclusief zomertijd en wijzigingen in de standaardtijd.

TimeSpan

Een TimeSpan kan alleen worden gebruikt voor een functie-app die wordt uitgevoerd op een App Service-plan.

In tegenstelling tot een CRON-expressie geeft een TimeSpan waarde het tijdsinterval aan tussen elke functieaanroep. Wanneer een functie is voltooid nadat deze langer is dan het opgegeven interval, roept de timer de functie onmiddellijk opnieuw aan.

Uitgedrukt als een tekenreeks, is hh:mm:ss de TimeSpan notatie kleiner hh dan 24. Wanneer de eerste twee cijfers 24 of hoger zijn, is dd:hh:mmde notatie . Hieronder volgen een aantal voorbeelden:

Opmerking Wanneer geactiveerd
"01:00:00" elk uur
"00:01:00" elke minuut
"25:00:00:00" om de 25 dagen
"1.00:00:00" Elke dag

Uitschalen

Als een functie-app wordt uitgeschaald naar meerdere exemplaren, wordt slechts één exemplaar van een door een timer geactiveerde functie uitgevoerd op alle exemplaren. Deze wordt niet opnieuw geactiveerd als er nog een openstaande aanroep wordt uitgevoerd.

Functie-apps die opslag delen

Als u opslagaccounts deelt tussen functie-apps die niet zijn geïmplementeerd in App Service, moet u mogelijk expliciet host-id toewijzen aan elke app.

Functions-versie Instelling
2.x (en hoger) AzureFunctionsWebHost__hostid Omgevingsvariabele
1.x id in host.json

U kunt de identificatiewaarde weglaten of de identificatieconfiguratie van elke functie-app handmatig instellen op een andere waarde.

De timertrigger maakt gebruik van een opslagvergrendeling om ervoor te zorgen dat er slechts één timerexemplaren zijn wanneer een functie-app wordt uitgeschaald naar meerdere exemplaren. Als twee functie-apps dezelfde identificatieconfiguratie delen en elk een timertrigger gebruikt, wordt slechts één timer uitgevoerd.

Gedrag voor opnieuw proberen

In tegenstelling tot de wachtrijtrigger wordt de timertrigger niet opnieuw geprobeerd nadat een functie is mislukt. Wanneer een functie mislukt, wordt deze pas de volgende keer in de planning aangeroepen.

Handmatig een timertrigger aanroepen

De timertrigger voor Azure Functions biedt een HTTP-webhook die kan worden aangeroepen om de functie handmatig te activeren. Dit kan zeer nuttig zijn in de volgende scenario's.

  • Integratietests
  • Sleufwisselingen als onderdeel van een betrouwbaarheidstest of opwarmactiviteit
  • Initiële implementatie van een functie om onmiddellijk een cache of opzoektabel in een database te vullen

Raadpleeg een niet door HTTP geactiveerde functie handmatig uitvoeren voor meer informatie over het handmatig aanroepen van een door timer geactiveerde functie.

Probleemoplossing

Zie Onderzoeken en rapporteren van problemen met door timer geactiveerde functies die niet worden geactiveerd voor meer informatie over wat u moet doen wanneer de timertrigger niet werkt zoals verwacht.

Volgende stappen

Ga naar een quickstart die gebruikmaakt van een timertrigger

Meer informatie over Azure Functions-triggers en -bindingen