Trigger časovače pro Azure Functions

  • Článek

Tento článek vysvětluje, jak pracovat s triggery časovače ve službě Azure Functions. Trigger časovače umožňuje spustit funkci podle plánu.

Toto jsou referenční informace pro vývojáře Azure Functions. Pokud s Azure Functions začínáte, začněte s následujícími prostředky:

Informace o ručním spuštění funkce aktivované časovačem najdete v tématu Ruční spuštění funkce neaktivované protokolem HTTP.

Podpora této vazby se automaticky poskytuje ve všech vývojových prostředích. Balíček nemusíte instalovat ručně ani registrovat rozšíření.

Zdrojový kód balíčku rozšíření časovače je v úložišti GitHubu azure-webjobs-sdk-extensions .

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Příklad

Tento příklad ukazuje funkci jazyka C#, která se spustí pokaždé, když minuty mají dělitelnou hodnotu o pět. Například když funkce začíná na 18:55:00, další spuštění je v 19:00:00. TimerInfo Objekt je předán funkci.

Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají Microsoft.Azure.Functions.Worker.Extensions.* obory názvů.
  • Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají Microsoft.Azure.WebJobs.Extensions.* obory názvů.

Důležité

Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

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

Následující příklad funkce aktivuje a spustí každých pět minut. Poznámka @TimerTrigger funkce definuje plán pomocí stejného formátu řetězce jako výrazy CRON.

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

Následující příklad ukazuje vazbu triggeru časovače a kód funkce, který používá vazbu, kde instance představující časovač se předává funkci. Funkce zapíše protokol označující, jestli je vyvolání této funkce způsobeno zmeškaným výskytem plánu. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

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)

Následující příklad ukazuje funkci TypeScript triggeru časovače.

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

Následující příklad ukazuje funkci javascriptového triggeru časovače.

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

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

Tady jsou data vazby v souboru function.json :

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

Následuje kód funkce časovače v souboru 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"

Atributy

Knihovna jazyka C# v procesu používá TimerTriggerAttribute z Microsoft.Azure.WebJobs.Extensions , zatímco knihovna C# izolovaného pracovního procesu používá k definování funkce TimerTriggerAttribute z Microsoft.Azure.Functions.Worker.Extensions.Timer . Skript jazyka C# místo toho používá konfigurační soubor function.json.

Vlastnost atributu Popis
Plán Výraz CRON nebo hodnota TimeSpan Dá TimeSpan se použít jenom pro aplikaci funkcí, která běží v plánu služby App Service. Výraz plánu můžete vložit do nastavení aplikace a nastavit tuto vlastnost na název nastavení aplikace zabalený jako %%ScheduleAppSetting%.
RunOnStartup Pokud truese funkce vyvolá při spuštění modulu runtime. Modul runtime se například spustí, když se aplikace funkcí probudí po nečinnosti z důvodu neaktivity, když se aplikace funkcí restartuje kvůli změnám funkce a když se aplikace funkcí škáluje na více instancí. Používejte s opatrností.RunOnStartup by mělo být zřídka, pokud je někdy nastaveno na true, zejména v produkčním prostředí.
UseMonitor Nastavením na hodnotu true nebo false určíte, jestli se má plán monitorovat. Monitorování plánu zachovává výskyty plánu, aby bylo zajištěno, že je plán správně udržován i v případě, že se instance aplikace funkcí restartují. Pokud není nastavené explicitně, výchozí hodnota je true pro plány, které mají interval opakování větší nebo roven 1 minutě. Pro plány, které se aktivují více než jednou za minutu, je falsevýchozí hodnota .

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

Pro funkce Pythonu v2 definované pomocí dekorátoru následující vlastnosti:schedule

Vlastnost Popis
arg_name Název proměnné, která představuje objekt časovače v kódu funkce.
schedule Výraz CRON nebo hodnota TimeSpan Dá TimeSpan se použít jenom pro aplikaci funkcí, která běží v plánu služby App Service. Výraz plánu můžete vložit do nastavení aplikace a nastavit tuto vlastnost na název nastavení aplikace zabalený jako v % tomto příkladu: %ScheduleAppSetting%.
run_on_startup Pokud truese funkce vyvolá při spuštění modulu runtime. Modul runtime se například spustí, když se aplikace funkcí probudí po nečinnosti z důvodu neaktivity, když se aplikace funkcí restartuje kvůli změnám funkce a když se aplikace funkcí škáluje na více instancí. Používejte s opatrností.RunOnStartup by mělo být zřídka, pokud je někdy nastaveno na true, zejména v produkčním prostředí.
use_monitor Nastavením na hodnotu true nebo false určíte, jestli se má plán monitorovat. Monitorování plánu zachovává výskyty plánu, aby bylo zajištěno, že je plán správně udržován i v případě, že se instance aplikace funkcí restartují. Pokud není nastavené explicitně, výchozí hodnota je true pro plány, které mají interval opakování větší nebo roven 1 minutě. Pro plány, které se aktivují více než jednou za minutu, je falsevýchozí hodnota .

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .

Poznámky

Poznámka @TimerTrigger funkce definuje schedule použití stejného formátu řetězce jako výrazy CRON. Poznámka podporuje následující nastavení:

Konfigurace

Platí pouze pro programovací model Pythonu v1.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě app.timer() .

Vlastnost Popis
schedule Výraz CRON nebo hodnota TimeSpan Dá TimeSpan se použít jenom pro aplikaci funkcí, která běží v plánu služby App Service. Výraz plánu můžete vložit do nastavení aplikace a nastavit tuto vlastnost na název nastavení aplikace zabalený jako v % tomto příkladu: %ScheduleAppSetting%.
runOnStartup Pokud truese funkce vyvolá při spuštění modulu runtime. Modul runtime se například spustí, když se aplikace funkcí probudí po nečinnosti z důvodu neaktivity, když se aplikace funkcí restartuje kvůli změnám funkce a když se aplikace funkcí škáluje na více instancí. Používejte s opatrností.RunOnStartup by mělo být zřídka, pokud je někdy nastaveno na true, zejména v produkčním prostředí.
useMonitor Nastavením na hodnotu true nebo false určíte, jestli se má plán monitorovat. Monitorování plánu zachovává výskyty plánu, aby bylo zajištěno, že je plán správně udržován i v případě, že se instance aplikace funkcí restartují. Pokud není nastavené explicitně, výchozí hodnota je true pro plány, které mají interval opakování větší nebo roven 1 minutě. Pro plány, které se aktivují více než jednou za minutu, je falsevýchozí hodnota .

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json .

vlastnost function.json Popis
type Musí být nastavena na "timerTrigger". Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
direction Musí být nastavená na "in". Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
Jméno Název proměnné, která představuje objekt časovače v kódu funkce.
schedule Výraz CRON nebo hodnota TimeSpan Dá TimeSpan se použít jenom pro aplikaci funkcí, která běží v plánu služby App Service. Výraz plánu můžete vložit do nastavení aplikace a nastavit tuto vlastnost na název nastavení aplikace zabalený jako v % tomto příkladu: %ScheduleAppSetting%.
runOnStartup Pokud truese funkce vyvolá při spuštění modulu runtime. Modul runtime se například spustí, když se aplikace funkcí probudí po nečinnosti z důvodu neaktivity, když se aplikace funkcí restartuje kvůli změnám funkce a když se aplikace funkcí škáluje na více instancí. Používejte s opatrností.RunOnStartup by mělo být zřídka, pokud je někdy nastaveno na true, zejména v produkčním prostředí.
useMonitor Nastavením na hodnotu true nebo false určíte, jestli se má plán monitorovat. Monitorování plánu zachovává výskyty plánu, aby bylo zajištěno, že je plán správně udržován i v případě, že se instance aplikace funkcí restartují. Pokud není nastavené explicitně, výchozí hodnota je true pro plány, které mají interval opakování větší nebo roven 1 minutě. Pro plány, které se aktivují více než jednou za minutu, je falsevýchozí hodnota .

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Upozornění

Nenastavujte runOnStartup na true v produkčním prostředí. Při použití tohoto nastavení se kód spouští v vysoce nepředvídatelných časech. V některých produkčních nastaveních můžou tato nadbytečná spuštění způsobit výrazně vyšší náklady na aplikace hostované v plánu Consumption. Například s povolenou funkcí runOnStartup se trigger vyvolá pokaždé, když se vaše aplikace funkcí škáluje. Než v produkčním prostředí povolíte runOnStartup , ujistěte se, že plně rozumíte provoznímu chování vašich funkcí.

Kompletní příklady najdete v části Příklad.

Využití

Při vyvolání funkce triggeru časovače se do funkce předá objekt časovače. Následující JSON je příkladem reprezentace objektu časovače.

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

Vlastnost isPastDue je true , když aktuální vyvolání funkce je pozdější než naplánované. Restartování aplikace funkcí může například způsobit zmeškané vyvolání.

Výrazy NCRONTAB

Azure Functions používá knihovnu NCronTab k interpretaci výrazů NCRONTAB. Výraz NCRONTAB se podobá výrazu CRON s tím rozdílem, že obsahuje další šesté pole na začátku, které se použije pro přesnost času v sekundách:

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

Každé pole může mít jeden z následujících typů hodnot:

Typ Příklad Při aktivaci
Konkrétní hodnota 0 5 * * * * Jednou za hodinu dne v minutě 5 každé hodiny
Všechny hodnoty (*) 0 * 5 * * * Za každou minutu v hodině během hodiny 5
Oblast (- operátor) 5-7 * * * * * Třikrát minuta – v sekundách 5 až 7 během každé minuty každé hodiny každého dne
Množina hodnot (, operátor) 5,8,10 * * * * * Třikrát minuta – v sekundách 5, 8 a 10 v každé minutě každé hodiny každého dne
Hodnota intervalu (/ operátor) 0 */5 * * * * 12krát hodina – při sekundách 0 každých 5. minuta každé hodiny každého dne

Pokud chcete zadat měsíce nebo dny, můžete použít číselné hodnoty, názvy nebo zkratky názvů:

  • Pro dny jsou číselné hodnoty 0 až 6, kde 0 začíná v neděli.
  • Názvy jsou v angličtině. Příklad: Monday, January.
  • Názvy nerozlišují malá a velká písmena.
  • Názvy mohou být zkráceny. Tři písmena jsou doporučená délka zkratky. Příklad: Mon, Jan.

Příklady NCRONTAB

Tady je několik příkladů výrazů NCRONTAB, které můžete použít pro trigger časovače ve službě Azure Functions.

Příklad Při aktivaci
0 */5 * * * * každých pět minut
0 0 * * * * jednou v horní části každé hodiny
0 0 */2 * * * jednou za dvě hodiny
0 0 9-17 * * * jednou za hodinu od 9:00 do 5:00
0 30 9 * * * v 9:30 každý den
0 30 9 * * 1-5 v 9:30 každý pracovní den
0 30 9 * Jan Mon v 9:30 každé pondělí v lednu

Poznámka:

Výraz NCRONTAB podporuje pět polí i šest formátů pole . Šestá pozice pole je hodnota pro sekundy, která je umístěna na začátku výrazu.

Časová pásma NCRONTAB

Čísla ve výrazu CRON odkazují na čas a datum, nikoli časové rozpětí. Například hodnota 5 v hour poli odkazuje na 5:00, ne každých 5 hodin.

Výchozím časovým pásmem používaným pro výrazy CRON je koordinovaný univerzální čas (UTC). Pokud chcete, aby byl výraz CRON založený na jiném časovém pásmu, vytvořte nastavení aplikace pro aplikaci funkcí s názvem WEBSITE_TIME_ZONE.

Hodnota tohoto nastavení závisí na operačním systému a plánu, ve kterém příslušná aplikace funkcí běží.

Operační systém Plánování Hodnota
Windows Vše Nastavte hodnotu na název požadovaného časového pásma podle druhého řádku z každého páru zadaného příkazem Windows. tzutil.exe /L
Linux Premium
Vyhrazené		 Nastavte hodnotu na název požadovaného časového pásma, jak je znázorněno v databázi tz.

Poznámka:

WEBSITE_TIME_ZONE a TZ nejsou v současné době podporovány při spuštění v Linuxu v plánu Consumption. V takovém případě můžete nastavit WEBSITE_TIME_ZONE nebo TZ vytvořit problémy související s PROTOKOLem SSL a způsobit, že metriky přestanou fungovat pro vaši aplikaci.

Například východní čas v USA (reprezentovaný Eastern Standard Time (Windows) nebo America/New_York (Linux)) v současné době používá UTC-05:00 ve standardním čase a UTC-04:00 během letního času. Pokud chcete mít aktivaci časovače každý den v 10:00 východního času, vytvořte nastavení aplikace pro aplikaci funkcí s názvem WEBSITE_TIME_ZONE, nastavte hodnotu na Eastern Standard Time (Windows) nebo America/New_York (Linux) a pak použijte následující výraz NCRONTAB:

"0 0 10 * * *"

Když použijete WEBSITE_TIME_ZONE čas, upraví se pro změny času v konkrétním časovém pásmu, včetně letního času a změn ve standardním čase.

TimeSpan

Dá TimeSpan se použít jenom pro aplikaci funkcí, která běží v plánu služby App Service.

Na rozdíl od výrazu TimeSpan CRON určuje hodnota časový interval mezi voláním jednotlivých funkcí. Po dokončení funkce po spuštění delšího než zadaného intervalu časovač okamžitě vyvolá funkci znovu.

Vyjádřeno jako řetězec je TimeSpan formát hh:mm:ss , pokud hh je menší než 24. Pokud jsou první dvě číslice 24 nebo větší, formát je dd:hh:mm. Několik příkladů:

Příklad Při aktivaci
"01:00:00" každou hodinu
"00:01:00" každou minutu
"25:00:00:00" každých 25 dnů
"1.00:00:00" Každý den

Škálování na víc systémů

Pokud aplikace funkcí škáluje kapacitu na více instancí, spustí se ve všech instancích pouze jedna instance funkce aktivované časovačem. Pokud stále probíhá nějaké volání, další časovač se neaktivuje.

Aplikace funkcí sdílejí úložiště

Pokud sdílíte účty úložiště mezi aplikacemi funkcí, které nejsou nasazené ve službě App Service, budete možná muset každému aplikaci explicitně přiřadit ID hostitele.

Verze služby Functions Nastavení
2.x (a vyšší) AzureFunctionsWebHost__hostid proměnná prostředí
1.x id v host.json

Můžete vynechat identifikační hodnotu nebo ručně nastavit konfiguraci identifikující jednotlivé aplikace funkcí na jinou hodnotu.

Trigger časovače používá zámek úložiště k zajištění, že existuje pouze jedna instance časovače, když aplikace funkcí škáluje kapacitu na více instancí. Pokud dvě aplikace funkcí sdílejí stejnou identifikaci konfigurace a každý používá trigger časovače, spustí se jenom jeden časovač.

Chování opakování

Na rozdíl od triggeru fronty se trigger časovače po selhání funkce neopakuje. Pokud se funkce nezdaří, nebude znovu volána až do příštího spuštění plánu.

Ruční vyvolání triggeru časovače

Trigger časovače pro Azure Functions poskytuje webhook HTTP, který se dá vyvolat, aby funkci aktivoval ručně. To může být velmi užitečné v následujících scénářích.

  • Testování integrace
  • Prohození slotů v rámci orientačního testu nebo aktivity zahřátí
  • Počáteční nasazení funkce pro okamžité naplnění mezipaměti nebo vyhledávací tabulky v databázi

Podrobnosti o tom, jak ručně vyvolat funkci aktivovanou časovačem, najdete v článku o ručním spuštění funkce, která není aktivovaná protokolem HTTP.

Řešení problému

Informace o tom, co dělat, když trigger časovače nefunguje podle očekávání, najdete v tématu Zkoumání a hlášení problémů s neaktivovanými funkcemi časovače.

Další kroky

Přejděte do rychlého startu, který používá trigger časovače.

Další informace o triggerech a vazbách Azure Functions