Trigger časovače pro Azure Functions
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:
Referenční informace pro vývojáře jazyka C#:
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.
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 true se 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 false vý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 NCRONTAB 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 true se 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 false vý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 NCRONTAB 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 true se 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 false vý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 NCRONTAB 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 true se 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 false vý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. Pro zkratky doporučujeme použít tři písmena. 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. Pokud je výraz CRON neplatný, test funkce webu Azure Portal zobrazí chybu 404, pokud je k ní připojena služba Application Insights, zaprotokolují se tam další podrobnosti.
Časová pásma NCRONTAB
Čísla ve výrazu NCRONTAB 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šechny | 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
NCRONTAB 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 běží nevyvolání, znovu 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.