Dela via


Timerutlösare för Azure Functions

Den här artikeln beskriver hur du arbetar med timerutlösare i Azure Functions. Med en timerutlösare kan du köra en funktion enligt ett schema.

Det här är referensinformation för Azure Functions-utvecklare. Om du inte har använt Azure Functions tidigare börjar du med följande resurser:

Information om hur du kör en timerutlöst funktion manuellt finns i Köra en funktion som inte är HTTP-utlöst manuellt.

Stöd för den här bindningen tillhandahålls automatiskt i alla utvecklingsmiljöer. Du behöver inte installera paketet manuellt eller registrera tillägget.

Källkoden för tidstilläggspaketet finns på GitHub-lagringsplatsen azure-webjobs-sdk-extensions .

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden för Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i python-funktionskoden. Mer information finns i utvecklarguiden för Python.

Den här artikeln stöder båda programmeringsmodellerna.

Exempel

Det här exemplet visar en C#-funktion som körs varje gång minuterna har ett värde som är delbart med fem. När funktionen till exempel startar kl. 18:55:00 är nästa körning kl. 19:00:00. Ett TimerInfo objekt skickas till funktionen.

En C#-funktion kan skapas med något av följande C#-lägen:

  • Isolerad arbetsmodell: Kompilerad C#-funktion som körs i en arbetsprocess som är isolerad från körningen. Isolerad arbetsprocess krävs för att stödja C#-funktioner som körs på LTS- och icke-LTS-versioner .NET och .NET Framework. Tillägg för isolerade arbetsprocessfunktioner använder Microsoft.Azure.Functions.Worker.Extensions.* namnområden.
  • Processmodell: Kompilerad C#-funktion som körs i samma process som Functions-körningen. I en variant av den här modellen kan Functions köras med C#-skript, vilket främst stöds för redigering av C#-portalen. Tillägg för in-process-funktioner använder Microsoft.Azure.WebJobs.Extensions.* namnområden.
//<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));

Följande exempelfunktion utlöser och körs var femte minut. Kommentaren @TimerTrigger i funktionen definierar schemat med samma strängformat som CRON-uttryck.

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

I följande exempel visas en timerutlösarbindning och funktionskod som använder bindningen, där en instans som representerar timern skickas till funktionen. Funktionen skriver en logg som anger om funktionens anrop beror på en utebliven schemahändelse. Exemplet beror på om du använder python-programmeringsmodellen v1 eller 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)

I följande exempel visas en typeScript-funktion för timerutlösare.

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

I följande exempel visas en JavaScript-funktion för timerutlösare.

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

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

Här är bindningsdata i filen function.json :

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

Följande är tidsinställd funktionskod i filen 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"

Attribut

Det processbaserade C#-biblioteket använder TimerTriggerAttribute från Microsoft.Azure.WebJobs.Extensions medan C#-biblioteket för isolerad arbetsprocess använder TimerTriggerAttribute från Microsoft.Azure.Functions.Worker.Extensions.Timer för att definiera funktionen. C#-skriptet använder i stället en function.json konfigurationsfil.

Attributegenskap beskrivning
Tidsplan Ett CRON-uttryck eller ett TimeSpan-värde . En TimeSpan kan endast användas för en funktionsapp som körs på en App Service-plan. Du kan placera schemauttrycket i en appinställning och ange den här egenskapen till namnet på appinställningen som omsluts av % tecken, som %ScheduleAppSetting%.
RunOnStartup Om trueanropas funktionen när körningen startar. Körningen startar till exempel när funktionsappen aktiveras efter inaktivitet, när funktionsappen startas om på grund av funktionsändringar och när funktionsappen skalar ut. Använd med försiktighet. RunOnStartup bör sällan eller aldrig anges till true, särskilt i produktion.
UseMonitor Ange till true eller false för att indikera om schemat ska övervakas. Schemaövervakning bevarar schemaförekomster för att säkerställa att schemat underhålls korrekt även när funktionsappinstanser startas om. Om den inte anges explicit är true standardvärdet för scheman som har ett upprepningsintervall som är större än eller lika med 1 minut. För scheman som utlöses mer än en gång per minut är falsestandardvärdet .

Dekoratörer

Gäller endast för python v2-programmeringsmodellen.

För Python v2-funktioner som definierats med hjälp av en dekoratör, följande egenskaper på schedule:

Property beskrivning
arg_name Namnet på variabeln som representerar det tidsinställda objektet i funktionskoden.
schedule Ett NCRONTAB-uttryck eller ett TimeSpan-värde . En TimeSpan kan endast användas för en funktionsapp som körs på en App Service-plan. Du kan placera schemauttrycket i en appinställning och ange den här egenskapen till namnet på appinställningen som omsluts i % tecken, som i det här exemplet: %ScheduleAppSetting%.
run_on_startup Om trueanropas funktionen när körningen startar. Körningen startar till exempel när funktionsappen aktiveras efter inaktivitet, när funktionsappen startas om på grund av funktionsändringar och när funktionsappen skalar ut. Använd med försiktighet. runOnStartup bör sällan eller aldrig anges till true, särskilt i produktion.
use_monitor Ange till true eller false för att indikera om schemat ska övervakas. Schemaövervakning bevarar schemaförekomster för att säkerställa att schemat underhålls korrekt även när funktionsappinstanser startas om. Om den inte anges explicit är true standardvärdet för scheman som har ett upprepningsintervall som är större än eller lika med 1 minut. För scheman som utlöses mer än en gång per minut är falsestandardvärdet .

Information om Python-funktioner som definierats med hjälp av function.json finns i avsnittet Konfiguration .

Kommentarer

Kommentaren @TimerTrigger på funktionen definierar schedule att använda samma strängformat som CRON-uttryck. Kommentaren stöder följande inställningar:

Konfiguration

Gäller endast programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas app.timer() till metoden.

Property beskrivning
schedule Ett NCRONTAB-uttryck eller ett TimeSpan-värde . En TimeSpan kan endast användas för en funktionsapp som körs på en App Service-plan. Du kan placera schemauttrycket i en appinställning och ange den här egenskapen till namnet på appinställningen som omsluts i % tecken, som i det här exemplet: %ScheduleAppSetting%.
runOnStartup Om trueanropas funktionen när körningen startar. Körningen startar till exempel när funktionsappen aktiveras efter inaktivitet, när funktionsappen startas om på grund av funktionsändringar och när funktionsappen skalar ut. Använd med försiktighet. runOnStartup bör sällan eller aldrig anges till true, särskilt i produktion.
useMonitor Ange till true eller false för att indikera om schemat ska övervakas. Schemaövervakning bevarar schemaförekomster för att säkerställa att schemat underhålls korrekt även när funktionsappinstanser startas om. Om den inte anges explicit är true standardvärdet för scheman som har ett upprepningsintervall som är större än eller lika med 1 minut. För scheman som utlöses mer än en gång per minut är falsestandardvärdet .

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i filen function.json .

function.json egenskap beskrivning
typ Måste anges till "timerTrigger". Den här egenskapen anges automatiskt när du skapar utlösaren i Azure Portal.
riktning Måste anges till "in". Den här egenskapen anges automatiskt när du skapar utlösaren i Azure Portal.
Namn Namnet på variabeln som representerar det tidsinställda objektet i funktionskoden.
schedule Ett NCRONTAB-uttryck eller ett TimeSpan-värde . En TimeSpan kan endast användas för en funktionsapp som körs på en App Service-plan. Du kan placera schemauttrycket i en appinställning och ange den här egenskapen till namnet på appinställningen som omsluts i % tecken, som i det här exemplet: %ScheduleAppSetting%.
runOnStartup Om trueanropas funktionen när körningen startar. Körningen startar till exempel när funktionsappen aktiveras efter inaktivitet, när funktionsappen startas om på grund av funktionsändringar och när funktionsappen skalar ut. Använd med försiktighet. runOnStartup bör sällan eller aldrig anges till true, särskilt i produktion.
useMonitor Ange till true eller false för att indikera om schemat ska övervakas. Schemaövervakning bevarar schemaförekomster för att säkerställa att schemat underhålls korrekt även när funktionsappinstanser startas om. Om den inte anges explicit är true standardvärdet för scheman som har ett upprepningsintervall som är större än eller lika med 1 minut. För scheman som utlöses mer än en gång per minut är falsestandardvärdet .

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Varning

Ange inte runOnStartup till true i produktion. Med den här inställningen körs kod vid mycket oförutsägbara tidpunkter. I vissa produktionsinställningar kan dessa extra körningar resultera i betydligt högre kostnader för appar som finns i en förbrukningsplan. Med till exempel runOnStartup aktiverat anropas utlösaren när din funktionsapp skalas. Se till att du förstår funktionernas produktionsbeteende fullt ut innan du aktiverar runOnStartup i produktion.

Se avsnittet Exempel för fullständiga exempel.

Förbrukning

När en timerutlösarfunktion anropas skickas ett timerobjekt till funktionen. Följande JSON är en exempelrepresentation av timerobjektet.

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

Egenskapen isPastDue är true när den aktuella funktionsanropet är senare än schemalagt. En omstart av funktionsappen kan till exempel leda till att ett anrop missas.

NCRONTAB-uttryck

Azure Functions använder NCronTab-biblioteket för att tolka NCRONTAB-uttryck. Ett NCRONTAB-uttryck liknar ett CRON-uttryck förutom att det innehåller ytterligare ett sjätte fält i början som ska användas för tidsprecision i sekunder:

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

Varje fält kan ha någon av följande typer av värden:

Typ Exempel När den utlöses
Ett specifikt värde 0 5 * * * * En gång varje timme på dagen vid minut 5 i varje timme
Alla värden (*) 0 * 5 * * * Varje minut i timmen, under timme 5
Ett intervall (- operator) 5-7 * * * * * Tre gånger per minut – vid sekunderna 5 till 7 under varje minut av varje timme varje dag
En uppsättning värden (, operator) 5,8,10 * * * * * Tre gånger per minut – vid sekunderna 5, 8 och 10 under varje minut i varje timme varje dag
Ett intervallvärde (/ operator) 0 */5 * * * * 12 gånger i timmen – vid andra 0 av var 5:e minut av varje timme varje dag

Om du vill ange månader eller dagar kan du använda numeriska värden, namn eller förkortningar av namn:

  • För dagar är de numeriska värdena 0 till 6, där 0 börjar med söndag.
  • Namnen är på engelska. Exempel: Monday, January.
  • Namn är skiftlägesokänsliga.
  • Namn kan förkortas. Vi rekommenderar att du använder tre bokstäver för förkortningar. Exempel: Mon, Jan.

NCRONTAB-exempel

Här följer några exempel på NCRONTAB-uttryck som du kan använda för timerutlösaren i Azure Functions.

Exempel När den utlöses
0 */5 * * * * en gång var femte minut
0 0 * * * * en gång högst upp i varje timme
0 0 */2 * * * en gång varannan timme
0 0 9-17 * * * en gång i timmen från 09:00 till 17:00
0 30 9 * * * kl. 09:30 varje dag
0 30 9 * * 1-5 kl. 09:30 varje vardag
0 30 9 * Jan Mon kl. 09:30 varje måndag i januari

Kommentar

NCRONTAB-uttrycket stöder både fem fält och sex fältformat . Den sjätte fältpositionen är ett värde för sekunder som placeras i början av uttrycket. Om CRON-uttrycket är ogiltigt visas ett 404-fel i funktionstestet i Azure Portal, om Application Insights är anslutet loggas mer information där.

NCRONTAB-tidszoner

Talen i ett NCRONTAB-uttryck refererar till ett tids- och datum, inte ett tidsintervall. Till exempel refererar en 5 i fältet hour till 05:00, inte var 5:e timme.

Standardtidszonen som används med CRON-uttrycken är Coordinated Universal Time (UTC). Om du vill att CRON-uttrycket ska baseras på en annan tidszon skapar du en appinställning för funktionsappen med namnet WEBSITE_TIME_ZONE.

Värdet för den här inställningen beror på vilket operativsystem och vilken plan funktionsappen körs på.

Operativsystem Planera Värde
Windows Alla Ange värdet till namnet på önskad tidszon enligt den andra raden från varje par som anges av Windows-kommandot tzutil.exe /L
Linux Premium
Dedikerad
Ange värdet till namnet på den önskade tidszonen enligt tz-databasen.

Kommentar

WEBSITE_TIME_ZONE och TZ stöds inte för närvarande när de körs på Linux i en förbrukningsplan. I det här fallet kan du ange WEBSITE_TIME_ZONE eller TZ skapa SSL-relaterade problem och få mått att sluta fungera för din app.

Till exempel använder Eastern Time i USA (representeras av Eastern Standard Time (Windows) eller America/New_York (Linux)) för närvarande UTC-05:00 under standardtiden och UTC-04:00 under sommartid. Om du vill att en timerutlösare ska utlösas klockan 10:00 östlig tid varje dag skapar du en appinställning för funktionsappen med namnet WEBSITE_TIME_ZONE, anger värdet till Eastern Standard Time (Windows) eller America/New_York (Linux) och använder sedan följande NCRONTAB-uttryck:

"0 0 10 * * *"

När du använder WEBSITE_TIME_ZONE tiden justeras för tidsändringar i den specifika tidszonen, inklusive sommartid och ändringar i standardtiden.

TimeSpan

En TimeSpan kan endast användas för en funktionsapp som körs på en App Service-plan.

Till skillnad från ett NCRONTAB-uttryck anger ett TimeSpan värde tidsintervallet mellan varje funktionsanrop. När en funktion har slutförts efter att ha körts längre än det angivna intervallet anropar timern omedelbart funktionen igen.

Formatet uttrycks som en sträng TimeSpan och är hh:mm:ss när hh det är mindre än 24. När de två första siffrorna är 24 eller högre är dd:hh:mmformatet . Nedan följer några exempel:

Exempel När den utlöses
"01:00:00" varje timme
"00:01:00" varje minut
"25:00:00:00" var 25:e dag
"1.00:00:00" Varje dag

Skalbarhet

Om en funktionsapp skalas ut till flera instanser körs endast en enda instans av en timerutlöst funktion i alla instanser. Det utlöses inte igen om ett utestående anrop fortfarande körs.

Funktionsappar som delar Lagring

Om du delar lagringskonton mellan funktionsappar som inte distribueras till App Service kan du behöva tilldela värd-ID till varje app uttryckligen.

Funktionsversion Inställning
2.x (och högre) AzureFunctionsWebHost__hostid miljövariabel
1.x id i host.json

Du kan utelämna det identifierande värdet eller manuellt ange varje funktionsapps identifieringskonfiguration till ett annat värde.

Timerutlösaren använder ett lagringslås för att säkerställa att det bara finns en timerinstans när en funktionsapp skalar ut till flera instanser. Om två funktionsappar delar samma identifierande konfiguration och var och en använder en timerutlösare körs bara en timer.

Beteende för återförsök

Till skillnad från köutlösaren försöker inte timerutlösaren igen när en funktion misslyckas. När en funktion misslyckas anropas den inte igen förrän nästa gång enligt schemat.

Anropa en timerutlösare manuellt

Timerutlösaren för Azure Functions tillhandahåller en HTTP-webhook som kan anropas för att manuellt utlösa funktionen. Detta kan vara mycket användbart i följande scenarier.

  • Integreringstestning
  • Fackbyten som en del av ett röktest eller en uppvärmningsaktivitet
  • Inledande distribution av en funktion för att omedelbart fylla i en cache eller uppslagstabell i en databas

Mer information om hur du anropar en timerutlösad funktion manuellt finns i Köra en funktion som inte är HTTP-utlöst manuellt.

Felsökning

Information om vad du ska göra när timerutlösaren inte fungerar som förväntat finns i Undersöka och rapportera problem med timerutlösta funktioner som inte utlöses.

Nästa steg