Dayanıklı İşlevler dış olayları işleme (Azure İşlevleri)

Makale
05/07/2024

Orchestrator işlevleri, dış olayları bekleme ve dinleme özelliğine sahiptir. bu Dayanıklı İşlevler özelliği genellikle insan etkileşimini veya diğer dış tetikleyicileri işlemek için yararlıdır.

Not

Dış olaylar tek yönlü zaman uyumsuz işlemlerdir. Olayı gönderen istemcinin orchestrator işlevinden zaman uyumlu bir yanıta ihtiyaç duyduğu durumlar için uygun değildir.

Olayları bekleme

Düzenleme tetikleyicisi bağlamasının "wait-for-external-event" API'si, bir düzenleyici işlevinin zaman uyumsuz olarak bir dış istemci tarafından teslim edilen bir olayı beklemesine ve dinlemesine olanak tanır. Dinleme düzenleyici işlevi olayın adını ve almayı beklediği verilerin şeklini bildirir.

[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
    }
}

Not

Önceki C# kodu Dayanıklı İşlevler 2.x içindir. Dayanıklı İşlevler 1.x için yerine IDurableOrchestrationContextkullanmanız DurableOrchestrationContext gerekir. Sürümler arasındaki farklar hakkında daha fazla bilgi için Dayanıklı İşlevler sürümleri makalesine bakın.

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

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)

param($Context)

$approved = Start-DurableExternalEventListener -EventName "Approval"

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

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

Yukarıdaki örnek, belirli bir olayı dinler ve alındığında işlem yapar.

Aşağıdaki örnekte olduğu gibi, üç olası olay bildiriminden birini bekleyen birden çok olayı eşzamanlı olarak dinleyebilirsiniz.

[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)
    {
        // ...
    }
}

Not

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) {
        // ...
    }
});

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)

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) {
    # ...
}

@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) {
        // ...
    }
}

Önceki örnek birden çok olaydan herhangi birini dinler. Tüm olayları beklemek de mümkündür.

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

Not

Önceki kod Dayanıklı İşlevler 2.x içindir. Dayanıklı İşlevler 1.x için yerine IDurableOrchestrationContextkullanmanız DurableOrchestrationContext gerekir. Sürümler arasındaki farklar hakkında daha fazla bilgi için Dayanıklı İşlevler sürümleri makalesine bakın.

.NET'te, olay yükü beklenen türe Tdönüştürülemiyorsa bir özel durum oluşturulur.

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

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)

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

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

"Wait-for-external-event" API'sinin bazı girişler için süresiz olarak beklemesi gerekir. İşlev uygulaması beklerken güvenli bir şekilde kaldırılabilir. Bu düzenleme örneği için bir olay gelirse ve geldiğinde, olay otomatik olarak uyandırılır ve olayı hemen işler.

Not

İşlev uygulamanız Tüketim Planı'nı kullanıyorsa, düzenleyici işlevi ne kadar beklerse beklesin bir dış olay görevi beklerken faturalama ücreti uygulanmaz.

Etkinlik İşlevleri'nde olduğu gibi dış olayların da en az bir kez teslim garantisi vardır. Bu, belirli koşullar altında (yeniden başlatmalar, ölçeklendirme, kilitlenmeler vb.) uygulamanızın aynı dış olayın yinelenenlerini alabileceği anlamına gelir. Bu nedenle, dış olayların düzenleyicilerde el ile çoğaltılmasını sağlayan bir tür kimlik içermesini öneririz.

Olayları gönderme

Düzenleme istemci bağlaması tarafından tanımlanan "raise-event" API'sini kullanarak bir düzenlemeye dış olay gönderebilirsiniz. Ayrıca, bir düzenlemeye dış olay göndermek için yerleşik yükseltme olayı HTTP API'sini de kullanabilirsiniz.

Tetiklenen olay parametre olarak bir örnek kimliği, eventName ve eventData içerir. Orchestrator işlevleri bu olayları "wait-for-external-event" API'lerini kullanarak işler. Olayın işlenmesi için eventName öğesinin hem gönderen hem de alan uçlarda eşleşmesi gerekir. Olay verileri de JSON serileştirilebilir olmalıdır.

Dahili olarak, "raise-event" mekanizmaları, bekleyen orchestrator işlevi tarafından alınmış bir iletiyi kuyruhlar. Örnek belirtilen olay adını beklemiyorsa, olay iletisi bellek içi kuyruğa eklenir. Düzenleme örneği daha sonra bu olay adını dinlemeye başlarsa, olay iletileri için kuyruğu denetler.

Not

Belirtilen örnek kimliğine sahip bir düzenleme örneği yoksa, olay iletisi atılır.

Aşağıda, bir orchestrator işlev örneğine "Approval" olayı gönderen kuyrukla tetiklenen bir işlev örneği verilmiştir. Düzenleme örneği kimliği, kuyruk iletisinin gövdesinden gelir.

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

Not

Önceki C# kodu Dayanıklı İşlevler 2.x içindir. Dayanıklı İşlevler 1.x için özniteliği OrchestrationClient yerine DurableClient özniteliğini ve yerine IDurableOrchestrationClientparametre türünü kullanmanız DurableOrchestrationClient gerekir. Sürümler arasındaki farklar hakkında daha fazla bilgi için Dayanıklı İşlevler sürümleri makalesine bakın.

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

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

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)

param($instanceId)

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

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

Dahili olarak, "raise-event" API'si, bekleyen orchestrator işlevi tarafından alınmış bir iletiyi sıralar. Örnek belirtilen olay adını beklemiyorsa, olay iletisi bellek içi arabelleğe eklenir. Düzenleme örneği daha sonra bu olay adını dinlemeye başlarsa, olay iletileri için arabelleği denetler ve bekleyen görevi tetikler.

Not

Belirtilen örnek kimliğine sahip bir düzenleme örneği yoksa, olay iletisi atılır.

HTTP

Aşağıda, bir düzenleme örneğine "Onay" olayı oluşturan bir HTTP isteği örneği verilmiştir.

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

"true"

Bu durumda örnek kimliği MyInstanceId olarak sabit kodlanır.

Sonraki adımlar

Hata işlemeyi uygulamayı öğrenin

İnsan etkileşimlerini bekleyen bir örnek çalıştırma

Aracılığıyla paylaş

Dayanıklı İşlevler dış olayları işleme (Azure İşlevleri)

Olayları bekleme

Olayları gönderme

HTTP

Sonraki adımlar

Geri Bildirim

Ek kaynaklar