Hantera externa händelser i Durable Functions (Azure Functions)

Orchestrator-funktioner har möjlighet att vänta och lyssna efter externa händelser. Den här funktionen i Durable Functions är ofta användbar för att hantera mänsklig interaktion eller andra externa utlösare.

Kommentar

Externa händelser är envägsasynkrona åtgärder. De är inte lämpliga för situationer där klienten som skickar händelsen behöver ett synkront svar från orchestrator-funktionen.

Vänta på händelser

API:et "wait-for-external-event" för orkestreringsutlösarbindningen gör att en orchestrator-funktion asynkront kan vänta och lyssna efter en händelse som levereras av en extern klient. Den lyssnande orchestrator-funktionen deklarerar namnet på händelsen och formen på de data som förväntas ta emot.

C#

[FunctionName("BudgetApproval")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    bool approved = await context.WaitForExternalEvent<bool>("Approval");
    if (approved)
    {
        // approval granted - do the approved action
    }
    else
    {
        // approval denied - send a notification
    }
}

Kommentar

Den tidigare C#-koden är för Durable Functions 2.x. För Durable Functions 1.x måste du använda DurableOrchestrationContext i stället för IDurableOrchestrationContext. Mer information om skillnaderna mellan versioner finns i artikeln Durable Functions-versioner .

JavaScript

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const approved = yield context.df.waitForExternalEvent("Approval");
    if (approved) {
        // approval granted - do the approved action
    } else {
        // approval denied - send a notification
    }
});

Python

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    approved = yield context.wait_for_external_event('Approval')
    if approved:
        # approval granted - do the approved action
    else:
        # approval denied - send a notification

main = df.Orchestrator.create(orchestrator_function)

PowerShell

param($Context)

$approved = Start-DurableExternalEventListener -EventName "Approval"

if ($approved) {
    # approval granted - do the approved action
} else {
    # approval denied - send a notification
}

Java

@FunctionName("WaitForExternalEvent")
public void waitForExternalEvent(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    boolean approved = ctx.waitForExternalEvent("Approval", boolean.class).await();
    if (approved) {
        // approval granted - do the approved action
    } else {
        // approval denied - send a notification
    }
}

Föregående exempel lyssnar efter en specifik enskild händelse och vidtar åtgärder när den tas emot.

Du kan lyssna efter flera händelser samtidigt, som i följande exempel, som väntar på någon av tre möjliga händelseaviseringar.

C#

[FunctionName("Select")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var event1 = context.WaitForExternalEvent<float>("Event1");
    var event2 = context.WaitForExternalEvent<bool>("Event2");
    var event3 = context.WaitForExternalEvent<int>("Event3");

    var winner = await Task.WhenAny(event1, event2, event3);
    if (winner == event1)
    {
        // ...
    }
    else if (winner == event2)
    {
        // ...
    }
    else if (winner == event3)
    {
        // ...
    }
}

Kommentar

Den tidigare C#-koden är för Durable Functions 2.x. För Durable Functions 1.x måste du använda DurableOrchestrationContext i stället för IDurableOrchestrationContext. Mer information om skillnaderna mellan versioner finns i artikeln Durable Functions-versioner .

JavaScript

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const event1 = context.df.waitForExternalEvent("Event1");
    const event2 = context.df.waitForExternalEvent("Event2");
    const event3 = context.df.waitForExternalEvent("Event3");

    const winner = yield context.df.Task.any([event1, event2, event3]);
    if (winner === event1) {
        // ...
    } else if (winner === event2) {
        // ...
    } else if (winner === event3) {
        // ...
    }
});

Python

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    event1 = context.wait_for_external_event('Event1')
    event2 = context.wait_for_external_event('Event2')
    event3 = context.wait_for_external_event('Event3')

    winner = yield context.task_any([event1, event2, event3])
    if winner == event1:
        # ...
    elif winner == event2:
        # ...
    elif winner == event3:
        # ...

main = df.Orchestrator.create(orchestrator_function)

PowerShell

param($Context)

$event1 = Start-DurableExternalEventListener -EventName "Event1" -NoWait
$event2 = Start-DurableExternalEventListener -EventName "Event2" -NoWait
$event3 = Start-DurableExternalEventListener -EventName "Event3" -NoWait

$winner = Wait-DurableTask -Task @($event1, $event2, $event3) -Any

if ($winner -eq $event1) {
    # ...
} else if ($winner -eq $event2) {
    # ...
} else if ($winner -eq $event3) {
    # ...
}

Java

@FunctionName("Select")
public void selectOrchestrator(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    Task<Void> event1 = ctx.waitForExternalEvent("Event1");
    Task<Void> event2 = ctx.waitForExternalEvent("Event2");
    Task<Void> event3 = ctx.waitForExternalEvent("Event3");

    Task<?> winner = ctx.anyOf(event1, event2, event3).await();
    if (winner == event1) {
        // ...
    } else if (winner == event2) {
        // ...
    } else if (winner == event3) {
        // ...
    }
}

Föregående exempel lyssnar efter någon av flera händelser. Det går också att vänta på alla händelser.

C#

[FunctionName("NewBuildingPermit")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string applicationId = context.GetInput<string>();

    var gate1 = context.WaitForExternalEvent("CityPlanningApproval");
    var gate2 = context.WaitForExternalEvent("FireDeptApproval");
    var gate3 = context.WaitForExternalEvent("BuildingDeptApproval");

    // all three departments must grant approval before a permit can be issued
    await Task.WhenAll(gate1, gate2, gate3);

    await context.CallActivityAsync("IssueBuildingPermit", applicationId);
}

Kommentar

Föregående kod är för Durable Functions 2.x. För Durable Functions 1.x måste du använda DurableOrchestrationContext i stället för IDurableOrchestrationContext. Mer information om skillnaderna mellan versioner finns i artikeln Durable Functions-versioner .

Om händelsenyttolasten inte kan konverteras till den förväntade typen Ti .NET genereras ett undantag.

JavaScript

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const applicationId = context.df.getInput();

    const gate1 = context.df.waitForExternalEvent("CityPlanningApproval");
    const gate2 = context.df.waitForExternalEvent("FireDeptApproval");
    const gate3 = context.df.waitForExternalEvent("BuildingDeptApproval");

    // all three departments must grant approval before a permit can be issued
    yield context.df.Task.all([gate1, gate2, gate3]);

    yield context.df.callActivity("IssueBuildingPermit", applicationId);
});

Python

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    application_id = context.get_input()
    
    gate1 = context.wait_for_external_event('CityPlanningApproval')
    gate2 = context.wait_for_external_event('FireDeptApproval')
    gate3 = context.wait_for_external_event('BuildingDeptApproval')

    yield context.task_all([gate1, gate2, gate3])
    yield context.call_activity('IssueBuildingPermit', application_id)

main = df.Orchestrator.create(orchestrator_function)

PowerShell

param($Context)

$applicationId = $Context.Input
$gate1 = Start-DurableExternalEventListener -EventName "CityPlanningApproval" -NoWait
$gate2 = Start-DurableExternalEventListener -EventName "FireDeptApproval" -NoWait
$gate3 = Start-DurableExternalEventListener -EventName "BuildingDeptApproval" -NoWait

Wait-DurableTask -Task @($gate1, $gate2, $gate3)

Invoke-ActivityFunction -FunctionName 'IssueBuildingPermit' -Input $applicationId

Java

@FunctionName("NewBuildingPermit")
public void newBuildingPermit(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    String applicationId = ctx.getInput(String.class);

    Task<Void> gate1 = ctx.waitForExternalEvent("CityPlanningApproval");
    Task<Void> gate2 = ctx.waitForExternalEvent("FireDeptApproval");
    Task<Void> gate3 = ctx.waitForExternalEvent("BuildingDeptApproval");

    // all three departments must grant approval before a permit can be issued
    ctx.allOf(List.of(gate1, gate2, gate3)).await();

    ctx.callActivity("IssueBuildingPermit", applicationId).await();
}

API:et "wait-for-external-event" väntar på obestämd tid på vissa indata. Funktionsappen kan tas bort på ett säkert sätt i väntan. Om och när en händelse anländer för den här orkestreringsinstansen, aktiveras den automatiskt och bearbetar händelsen omedelbart.

Kommentar

Om din funktionsapp använder förbrukningsplanen debiteras inga faktureringsavgifter medan en orkestreringsfunktion väntar på en extern händelseaktivitet, oavsett hur länge den väntar.

Precis som med Aktivitetsfunktioner har externa händelser en leveransgaranti minst en gång . Det innebär att programmet under vissa förhållanden (till exempel omstarter, skalning, krascher osv.) kan ta emot dubbletter av samma externa händelse. Därför rekommenderar vi att externa händelser innehåller någon form av ID som gör att de kan avdupliceras manuellt i orchestrators.

Skicka händelser

Du kan använda API:et "raise-event" som definieras av orkestreringsklientbindningen för att skicka en extern händelse till en orkestrering. Du kan också använda det inbyggda HTTP-API :et för höjningshändelse för att skicka en extern händelse till en orkestrering.

En upphöjd händelse innehåller ett instans-ID, ett eventName och eventData som parametrar. Orchestrator-funktioner hanterar dessa händelser med API:erna "wait-for-external-event". EventName måste matcha både sändnings- och mottagarsluten för att händelsen ska kunna bearbetas. Händelsedata måste också vara JSON-serialiserbara.

Internt anger mekanismerna "raise-event" ett meddelande som hämtas av den väntande orkestreringsfunktionen. Om instansen inte väntar på det angivna händelsenamnet läggs händelsemeddelandet till i en minnesintern kö. Om orkestreringsinstansen senare börjar lyssna efter det händelsenamnet kontrollerar den kön efter händelsemeddelanden.

Kommentar

Om det inte finns någon orkestreringsinstans med det angivna instans-ID:t ignoreras händelsemeddelandet.

Nedan visas ett exempel på en köutlöst funktion som skickar en "Approval"-händelse till en orchestrator-funktionsinstans. Orkestreringsinstans-ID:t kommer från brödtexten i kömeddelandet.

C#

[FunctionName("ApprovalQueueProcessor")]
public static async Task Run(
    [QueueTrigger("approval-queue")] string instanceId,
    [DurableClient] IDurableOrchestrationClient client)
{
    await client.RaiseEventAsync(instanceId, "Approval", true);
}

Kommentar

Den tidigare C#-koden är för Durable Functions 2.x. För Durable Functions 1.x måste du använda OrchestrationClient attributet i stället för DurableClient attributet och du måste använda DurableOrchestrationClient parametertypen i stället för IDurableOrchestrationClient. Mer information om skillnaderna mellan versioner finns i artikeln Durable Functions-versioner .

JavaScript

const df = require("durable-functions");

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);
    await client.raiseEvent(instanceId, "Approval", true);
};

Python

import azure.functions as func
import azure.durable_functions as df

async def main(instance_id:str, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    await client.raise_event(instance_id, 'Approval', True)

PowerShell

param($instanceId)

Send-DurableExternalEvent -InstanceId $InstanceId -EventName "Approval"

Java

@FunctionName("ApprovalQueueProcessor")
public void approvalQueueProcessor(
        @QueueTrigger(name = "instanceID", queueName = "approval-queue") String instanceID,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    durableContext.getClient().raiseEvent(instanceID, "Approval", true);
}

Internt visar API:et "raise-event" ett meddelande som hämtas av den väntande orkestreringsfunktionen. Om instansen inte väntar på det angivna händelsenamnet läggs händelsemeddelandet till i en minnesintern buffert. Om orkestreringsinstansen senare börjar lyssna efter det händelsenamnet kontrollerar den bufferten efter händelsemeddelanden och utlöser den uppgift som väntade på den.

Kommentar

Om det inte finns någon orkestreringsinstans med det angivna instans-ID:t ignoreras händelsemeddelandet.

HTTP

Följande är ett exempel på en HTTP-begäran som genererar en "Godkännande"-händelse till en orkestreringsinstans.

POST /runtime/webhooks/durabletask/instances/MyInstanceId/raiseEvent/Approval&code=XXX
Content-Type: application/json

"true"

I det här fallet är instans-ID:t hårdkodat som MyInstanceId.

Nästa steg

Lär dig hur du implementerar felhantering

Kör ett exempel som väntar på mänsklig interaktion