Timer in Funzioni permanenti (Funzioni di Azure)

Articolo
11/08/2023

Funzioni permanenti fornisce timer permanenti da usare nelle funzioni di orchestrazione per implementare ritardi o per impostare timeout nelle azioni asincrone. I timer durevoli devono essere usati nelle funzioni dell'agente di orchestrazione anziché nelle API "sospensione" o "ritardo" che possono essere integrate nel linguaggio.

I timer durevoli sono attività create usando l'API "crea timer" appropriata per il linguaggio fornito, come illustrato di seguito e richiedono un tempo di scadenza o una durata come argomento.

// Put the orchestrator to sleep for 72 hours
DateTime dueTime = context.CurrentUtcDateTime.AddHours(72);
await context.CreateTimer(dueTime, CancellationToken.None);

// Put the orchestrator to sleep for 72 hours
// Note that DateTime comes from the "luxon" module
const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime, {zone: 'utc'}).plus({ hours: 72 });
yield context.df.createTimer(deadline.toJSDate());

# Put the orchestrator to sleep for 72 hours
due_time = context.current_utc_datetime + timedelta(hours=72)
durable_timeout_task = context.create_timer(due_time)

# Put the orchestrator to sleep for 72 hours
$duration = New-TimeSpan -Hours 72
Start-DurableTimer -Duration $duration

// Put the orchestrator to sleep for 72 hours
ctx.createTimer(Duration.ofHours(72)).await();

Quando si "await" l'attività timer, la funzione dell'agente di orchestrazione rimarrà in sospensione fino all'ora di scadenza specificata.

Nota

Le orchestrazioni continueranno a elaborare altri eventi in ingresso durante l'attesa della scadenza di un'attività timer.

Limitazioni dei timer

Quando si crea un timer che scade alle 14:30 UTC, durable task Framework sottostante accoda un messaggio che diventa visibile solo alle 14:30 UTC. Se l'app per le funzioni viene ridotta a zero istanze nel frattempo, il messaggio timer appena visibile garantisce che l'app per le funzioni venga riattivata in una macchina virtuale appropriata.

Nota

Per le app JavaScript, Python e PowerShell, i timer durevoli sono limitati a sei giorni. Per ovviare a questa limitazione, è possibile usare le API timer in un while ciclo per simulare un ritardo più lungo. Le app .NET e Java aggiornate supportano timer arbitrariamente lunghi.
A seconda della versione dell'SDK e del provider di archiviazione in uso, i timer lunghi di 6 giorni o più possono essere implementati internamente usando una serie di timer più brevi (ad esempio, di 3 durate di 3 giorni) fino al raggiungimento dell'ora di scadenza desiderata. Questa operazione può essere osservata nell'archivio dati sottostante, ma non influisce sul comportamento dell'orchestrazione.
Non usare le API predefinite di data/ora per ottenere l'ora corrente. Quando si calcola una data futura per la scadenza di un timer, usare sempre l'API ora corrente della funzione dell'agente di orchestrazione. Per altre informazioni, vedere l'articolo Vincoli di codice della funzione dell'agente di orchestrazione.

Uso per il ritardo

L'esempio seguente illustra come usare i timer permanenti per ritardare l'esecuzione. L'esempio invia una notifica di fatturazione ogni giorno per 10 giorni.

[FunctionName("BillingIssuer")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    for (int i = 0; i < 10; i++)
    {
        DateTime deadline = context.CurrentUtcDateTime.Add(TimeSpan.FromDays(1));
        await context.CreateTimer(deadline, CancellationToken.None);
        await context.CallActivityAsync("SendBillingEvent");
    }
}

Nota

L'esempio C# precedente è destinato a Durable Functions 2.x. Per Durable Functions 1.x, è necessario usare DurableOrchestrationContext anziché IDurableOrchestrationContext. Per altre informazioni sulle differenze tra le versioni, vedere l'articolo Versioni di Durable Functions.

const df = require("durable-functions");
const { DateTime } = require("luxon");

module.exports = df.orchestrator(function*(context) {
    for (let i = 0; i < 10; i++) {
        const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime, {zone: 'utc'}).plus({ days: 1 });
        yield context.df.createTimer(deadline.toJSDate());
        yield context.df.callActivity("SendBillingEvent");
    }
});

import azure.functions as func
import azure.durable_functions as df
from datetime import datetime, timedelta

def orchestrator_function(context: df.DurableOrchestrationContext):
    for i in range(0, 9):
        deadline = context.current_utc_datetime + timedelta(days=1)
        yield context.create_timer(deadline)
        yield context.call_activity("SendBillingEvent")

main = df.Orchestrator.create(orchestrator_function)

param($Context)

for ($num = 0 ; $num -le 9 ; $num++){    
    $expiryTime =  New-TimeSpan -Days 1
    $timerTask = Start-DurableTimer -Duration $expiryTime
    Invoke-DurableActivity -FunctionName 'SendBillingEvent'
}

@FunctionName("BillingIssuer")
public String billingIssuer(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    for (int i = 0; i < 10; i++) {
        ctx.createTimer(Duration.ofDays(1)).await();
        ctx.callActivity("SendBillingEvent").await();
    }
    return "done";
}

Avviso

Evitare i cicli infiniti nelle funzioni di orchestrazione. Per informazioni su come implementare scenari di ciclo infinito in modo sicuro ed efficiente, vedere Orchestrazioni perenni.

Utilizzo per i timeout

Questo esempio illustra come usare i timer durevoli per implementare i timeout.

[FunctionName("TryGetQuote")]
public static async Task<bool> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    TimeSpan timeout = TimeSpan.FromSeconds(30);
    DateTime deadline = context.CurrentUtcDateTime.Add(timeout);

    using (var cts = new CancellationTokenSource())
    {
        Task activityTask = context.CallActivityAsync("GetQuote");
        Task timeoutTask = context.CreateTimer(deadline, cts.Token);

        Task winner = await Task.WhenAny(activityTask, timeoutTask);
        if (winner == activityTask)
        {
            // success case
            cts.Cancel();
            return true;
        }
        else
        {
            // timeout case
            return false;
        }
    }
}

Nota

const df = require("durable-functions");
const { DateTime } = require("luxon");

module.exports = df.orchestrator(function*(context) {
    const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime, {zone: 'utc'}).plus({ seconds: 30 });

    const activityTask = context.df.callActivity("GetQuote");
    const timeoutTask = context.df.createTimer(deadline.toJSDate());

    const winner = yield context.df.Task.any([activityTask, timeoutTask]);
    if (winner === activityTask) {
        // success case
        timeoutTask.cancel();
        return true;
    }
    else
    {
        // timeout case
        return false;
    }
});

import azure.functions as func
import azure.durable_functions as df
from datetime import datetime, timedelta

def orchestrator_function(context: df.DurableOrchestrationContext):
    deadline = context.current_utc_datetime + timedelta(seconds=30)
    activity_task = context.call_activity("GetQuote")
    timeout_task = context.create_timer(deadline)

    winner = yield context.task_any([activity_task, timeout_task])
    if winner == activity_task:
        timeout_task.cancel()
        return True
    elif winner == timeout_task:
        return False

main = df.Orchestrator.create(orchestrator_function)

param($Context)

$expiryTime =  New-TimeSpan -Seconds 30

$activityTask = Invoke-DurableActivity -FunctionName 'GetQuote'-NoWait
$timerTask = Start-DurableTimer -Duration $expiryTime -NoWait

$winner = Wait-DurableTask -Task @($activityTask, $timerTask) -Any

if ($winner -eq $activityTask) {
    Stop-DurableTimerTask -Task $timerTask
    return $True
}
else {
    return $False
}

@FunctionName("TryGetQuote")
public boolean tryGetQuote(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    Task<Double> activityTask = ctx.callActivity("GetQuote", Double.class);
    Task<Void> timerTask = ctx.createTimer(Duration.ofSeconds(30));

    Task<?> winner = ctx.anyOf(activityTask, timerTask);
    if (winner == activityTask) {
        // success case
        return true;
    } else {
        // timeout case
        return false;
    }
}

Avviso

In .NET, JavaScript, Python e PowerShell è necessario annullare tutti i timer durevoli creati se il codice non attenderà il completamento. Vedere gli esempi precedenti per come annullare i timer in sospeso. Durable Task Framework non modificherà lo stato di un'orchestrazione in "Completato" fino a quando tutte le attività in sospeso, incluse le attività timer durevoli, non verranno completate o annullate.

Questo meccanismo di annullamento che usa il modello when-any non termina le esecuzioni di attività in corso o di sotto orchestrazione. ma consente semplicemente alla funzione di orchestrazione di ignorare il risultato e continuare. Se l'app per le funzioni usa il piano a consumo, verrà comunque addebitata la quantità di tempo e memoria utilizzata dalla funzione di attività abbandonata. Per impostazione predefinita, le funzioni in esecuzione nel piano a consumo hanno un timeout di cinque minuti. Se questo limite viene superato, l'host di Funzioni di Azure viene riciclato per interrompere ogni esecuzione e impedire una fatturazione eccessiva. Il timeout delle funzioni è configurabile.

Per un esempio più approfondito di come implementare i timeout nelle funzioni dell'agente di orchestrazione, vedere l'articolo Interazione umana e timeout - Telefono verifica.

Passaggi successivi

Informazioni su come generare e gestire eventi esterni

Timer in Funzioni permanenti (Funzioni di Azure)

Limitazioni dei timer

Uso per il ritardo

Utilizzo per i timeout

Passaggi successivi

Risorse aggiuntive