Külső események kezelése a Durable Functionsben (Azure Functions)
Az Orchestrator-függvények képesek várni és figyelni a külső eseményeket. A Durable Functions ezen funkciója gyakran hasznos emberi interakciók vagy más külső eseményindítók kezelésére.
Feljegyzés
A külső események egyirányú aszinkron műveletek. Nem alkalmasak olyan helyzetekre, amikor az eseményt küldő ügyfélnek szinkron választ kell adni a vezénylő függvénytől.
Várakozás eseményekre
A vezénylési trigger kötésének "wait-for-external-event" API-ja lehetővé teszi, hogy a vezénylő függvény aszinkron módon várja meg és figyelje a külső ügyfél által küldött eseményeket. A figyelő vezénylő függvény deklarálja az esemény nevét és a várható adatok alakját.
[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
}
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetén a helyett IDurableOrchestrationContext
a DurableOrchestrationContext
. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Az előző példa egy adott eseményt figyel, és a fogadáskor műveletet hajt végre.
Egyszerre több eseményt is figyelhet, például az alábbi példában, amely a három lehetséges eseményértesítés egyikére vár.
[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)
{
// ...
}
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetén a helyett IDurableOrchestrationContext
a DurableOrchestrationContext
. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
Az előző példa több esemény bármelyikét figyeli. Az összes eseményre is lehet várni.
[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);
}
Feljegyzés
Az előző kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetén a helyett IDurableOrchestrationContext
a DurableOrchestrationContext
. A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
A .NET-ben, ha az esemény hasznos adatai nem konvertálhatók a várt típusra T
, a rendszer kivételt küld.
A "wait-for-external-event" API határozatlan ideig várakozik bizonyos bemenetekre. A függvényalkalmazás biztonságosan eltávolítható várakozás közben. Ha és amikor egy esemény érkezik erre a vezénylési példányra, a rendszer automatikusan felébred, és azonnal feldolgozza az eseményt.
Feljegyzés
Ha a függvényalkalmazás a Használati csomagot használja, a rendszer nem számol fel számlázási díjakat, miközben egy vezénylő függvény egy külső eseményfeladatra vár, függetlenül attól, hogy mennyi ideig vár.
A Tevékenységfüggvényekhez hasonlóan a külső események is legalább egyszeri kézbesítési garanciával rendelkeznek. Ez azt jelenti, hogy bizonyos feltételek mellett (például újraindítások, skálázás, összeomlások stb.) az alkalmazás ugyanahhoz a külső eseményhez duplikátumokat kaphat. Ezért azt javasoljuk, hogy a külső események valamilyen azonosítót tartalmazzanak, amely lehetővé teszi, hogy manuálisan duplikálják őket a vezénylőkben.
Események küldése
A vezénylési ügyfélkötés által definiált "raise-event" API használatával külső eseményt küldhet egy vezénylésnek. A beépített emelési esemény HTTP API-val külső eseményt is küldhet vezénylésre.
Az emelt esemény tartalmaz egy példányazonosítót, egy eventName és egy eventData paramétert. Az Orchestrator függvények ezeket az eseményeket a "wait-for-external-event" API-k használatával kezelik. Az eseménynévnek egyeznie kell mind a küldési, mind a fogadási végeken az esemény feldolgozásához. Az eseményadatoknak JSON-szerializálhatónak is kell lenniük.
A "raise-event" mechanizmusok belsőleg egy üzenetet idéznek elő, amelyet a várakozó vezénylő függvény fog át. Ha a példány nem a megadott eseménynévre vár, a rendszer hozzáadja az eseményüzenetet egy memóriabeli üzenetsorhoz. Ha a vezénylési példány később elkezdi figyelni az esemény nevét, ellenőrzi az üzenetsort az eseményüzenetek esetében.
Feljegyzés
Ha nincs vezénylési példány a megadott példányazonosítóval, a rendszer elveti az eseményüzenetet.
Az alábbiakban egy üzenetsor által aktivált függvény látható, amely egy "Jóváhagyási" eseményt küld egy vezénylő függvénypéldánynak. A vezénylési példány azonosítója az üzenetsor törzséből származik.
[FunctionName("ApprovalQueueProcessor")]
public static async Task Run(
[QueueTrigger("approval-queue")] string instanceId,
[DurableClient] IDurableOrchestrationClient client)
{
await client.RaiseEventAsync(instanceId, "Approval", true);
}
Feljegyzés
Az előző C# kód a Durable Functions 2.x-hez készült. A Durable Functions 1.x esetében az attribútum helyett attribútumot DurableClient
kell használniaOrchestrationClient
, és a DurableOrchestrationClient
paramétertípust kell használnia helyett.IDurableOrchestrationClient
A verziók közötti különbségekről további információt a Durable Functions verzióiról szóló cikkben talál.
A "raise-event" API belsőleg egy üzenetet küld, amelyet a várakozó vezénylő függvény fog átvenni. Ha a példány nem a megadott eseménynévre vár, a rendszer hozzáadja az eseményüzenetet egy memóriabeli pufferhez. Ha a vezénylési példány később elkezdi figyelni az esemény nevét, ellenőrzi az eseményüzenetek pufferét, és aktiválja a rá váró feladatot.
Feljegyzés
Ha nincs vezénylési példány a megadott példányazonosítóval, a rendszer elveti az eseményüzenetet.
HTTP
Az alábbi példa egy HTTP-kérésre mutat be egy "Jóváhagyási" eseményt egy vezénylési példányra.
POST /runtime/webhooks/durabletask/instances/MyInstanceId/raiseEvent/Approval&code=XXX
Content-Type: application/json
"true"
Ebben az esetben a példányazonosító a MyInstanceId kóddal van kódolva.