Modello di interazione umana

Il modello di interazione umana descrive i flussi di lavoro che sospendono e attendono l'input da una persona prima di continuare. Il modello è utile per i flussi di lavoro di approvazione, l'autenticazione a più fattori e qualsiasi scenario in cui una persona risponde entro un limite di tempo.

A livello generale, il modello funziona come segue:

1. L'orchestratore chiama un'attività per notificare una persona (inviare un codice SMS, inviare un messaggio di posta elettronica a un approvatore e così via).
2. L'orchestratore avvia un timer durevole e attende simultaneamente un evento esterno dall'utente.
3. Se la persona risponde prima dell'attivazione del timer, l'agente di orchestrazione elabora la risposta.
4. Se il timer viene attivato per primo, l'agente di orchestrazione gestisce il timeout, ad esempio rifiutando la richiesta.

Contenuto dell'articolo:

• Panoramica dello scenario di interazione umana - Perché questo modello è importante
• Definire l'agente di orchestrazione : implementare la gara timer-vs-event
• Definire le attività - Inviare notifiche ed elaborare i risultati
• Eseguire l'esempio di interazione umana - Testare il flusso di lavoro di testa a coda

Annotazioni

Gli esempi di Durable Functions e Durable Task SDK illustrano lo stesso modello con scenari diversi: Durable Functions usa un esempio di verifica SMS, mentre Durable Task SDK utilizza un esempio di flusso di lavoro di approvazione.

Questo esempio illustra come creare un'orchestrazione Durable Functions che include l'interazione umana. L'esempio implementa un sistema di verifica telefono basato su SMS. È comune nei flussi di verifica dei numeri di telefono e dell'autenticazione a più fattori (MFA).

Annotazioni

Gli esempi di codice completi sono disponibili per C#, JavaScript e Python. Gli esempi di PowerShell e Java non sono attualmente disponibili.

Annotazioni

La versione 4 del modello di programmazione Node.js per Funzioni di Azure è disponibile a livello generale. Il modello v4 è progettato per offrire un'esperienza più flessibile e intuitiva per sviluppatori JavaScript e TypeScript. Per altre informazioni sulle differenze tra v3 e v4, vedere la guida alla migrazione.

Nei frammenti di codice seguenti JavaScript (PM4) indica il modello di programmazione v4, la nuova esperienza.

Prerequisiti

C#

• Completare l'articolo introduttivo
• Clonare o scaricare il progetto di esempio da GitHub (utilizza il modello in-process)

JavaScript

Modello di programmazione V3

• Completare l'articolo introduttivo
• Clona o scarica il progetto di esempio da GitHub

Modello di programmazione V4

• Completare l'articolo introduttivo
• Clona o scarica il progetto di esempio da GitHub

Python

• Completare l'articolo introduttivo
• Clona o scarica il progetto di esempio da GitHub

PowerShell

• Completare l'articolo introduttivo
• Clona o scarica il progetto di esempio da GitHub

Java

• Completare l'articolo introduttivo

Questo articolo illustra come implementare il modello di interazione umana usando gli SDK di Durable Task. Nell'esempio viene implementato un flusso di lavoro di approvazione in cui un'orchestrazione attende che una persona approvi o rifiuti una richiesta prima che continui.

Panoramica dello scenario di interazione umana

La verifica telefonica consente di verificare che le persone che usano l'app non siano spammer e che controllino il numero di telefono fornito. L'autenticazione a più fattori è un modo comune per proteggere gli account. La creazione di una verifica tramite telefono personalizzata richiede un'interazione con stato con una persona. Un utente ottiene in genere un codice (ad esempio, un numero a quattro cifre) e deve rispondere in un periodo di tempo ragionevole.

I Funzioni di Azure standard sono senza stato (come molti altri endpoint cloud), quindi questo tipo di interazione richiede di archiviare lo stato in un database o in un altro archivio permanente. È anche possibile suddividere l'interazione tra più funzioni e coordinarle. Ad esempio, una funzione genera un codice, lo archivia e lo invia al telefono dell'utente. Un'altra funzione riceve la risposta dell'utente e la mappa alla richiesta originale per convalidare il codice. Aggiungere un timeout per proteggere la sicurezza. Questo flusso di lavoro diventa rapidamente complesso.

Durable Functions riduce la complessità di questo scenario. In questo esempio, una funzione di orchestrazione gestisce l'interazione stateful senza un archivio dati esterno. Poiché le funzioni dell'agente di orchestrazione sono durevoli, questi flussi interattivi sono altamente affidabili.

I flussi di lavoro di approvazione sono comuni nelle applicazioni aziendali in cui una richiesta deve essere esaminata da un essere umano prima di procedere. I requisiti del flusso di lavoro sono:

• Attendere indefinitamente per una risposta umana o fino a un timeout
• Gestire sia i risultati di approvazione che di rifiuto
• Timeout di supporto quando non si riceve alcuna risposta
• Tenere traccia dello stato in modo che il richiedente possa controllare lo stato di avanzamento

Gli SDK per attività durevoli semplificano questo scenario con:

• Eventi esterni: l'orchestrazione può sospendere e attendere un evento generato da un sistema esterno o da un utente
• Timer durevoli: impostare un timeout che si attiva se non si riceve alcuna risposta
• Stato personalizzato: tenere traccia ed esporre lo stato corrente del flusso di lavoro ai client

Configurare l'integrazione di Twilio

Questo esempio prevede l'uso del servizio Twilio per inviare messaggi SMS al telefono cellulare. Funzioni di Azure ha già supporto per Twilio tramite l'associazione Twilio e l'esempio usa tale funzionalità.

È necessario per prima cosa disporre di un account Twilio. È possibile crearne uno gratuitamente all'indirizzo https://www.twilio.com/try-twilio. Dopo aver creato un account, aggiungere le seguenti tre impostazioni dell'app alla propria app per le funzioni.

Nome dell'impostazione dell'app	Descrizione del valore
TwilioAccountSid	SID dell'account Twilio
TwilioAuthToken	Token di autenticazione per l'account Twilio
TwilioPhoneNumber	Numero di telefono associato all'account Twilio usato per inviare messaggi SMS.

Definire l'orchestratore

Funzione di orchestrazione E4_SmsPhoneVerification

C#

[FunctionName("E4_SmsPhoneVerification")]
public static async Task<bool> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string phoneNumber = context.GetInput<string>();
    if (string.IsNullOrEmpty(phoneNumber))
    {
        throw new ArgumentNullException(
            nameof(phoneNumber),
            "A phone number input is required.");
    }

    int challengeCode = await context.CallActivityAsync<int>(
        "E4_SendSmsChallenge",
        phoneNumber);

    using (var timeoutCts = new CancellationTokenSource())
    {
        // The user has 90 seconds to respond with the code they received in the SMS message.
        DateTime expiration = context.CurrentUtcDateTime.AddSeconds(90);
        Task timeoutTask = context.CreateTimer(expiration, timeoutCts.Token);

        bool authorized = false;
        for (int retryCount = 0; retryCount <= 3; retryCount++)
        {
            Task<int> challengeResponseTask =
                context.WaitForExternalEvent<int>("SmsChallengeResponse");

            Task winner = await Task.WhenAny(challengeResponseTask, timeoutTask);
            if (winner == challengeResponseTask)
            {
                // We got back a response! Compare it to the challenge code.
                if (challengeResponseTask.Result == challengeCode)
                {
                    authorized = true;
                    break;
                }
            }
            else
            {
                // Timeout expired
                break;
            }
        }

        if (!timeoutTask.IsCompleted)
        {
            // All pending timers must be complete or canceled before the function exits.
            timeoutCts.Cancel();
        }

        return authorized;
    }
}

Annotazioni

Potrebbe non essere ovvio in un primo momento, ma questo agente di orchestrazione non viola il vincolo di orchestrazione deterministico. È deterministico perché la CurrentUtcDateTime proprietà calcola l'ora di scadenza del timer e restituisce lo stesso valore in ogni riproduzione in questo punto nel codice dell'agente di orchestrazione. Questo comportamento garantisce che winner sia lo stesso per ogni chiamata ripetuta a Task.WhenAny.

JavaScript

Modello di programmazione V3

La funzione E4_SmsPhoneVerification usa il codice function.json standard per le funzioni dell'agente di orchestrazione.

{
  "bindings": [
    {
      "name": "context",
      "type": "orchestrationTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

Il codice che implementa la funzione è il seguente:

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

module.exports = df.orchestrator(function* (context) {
    const phoneNumber = context.df.getInput();
    if (!phoneNumber) {
        throw "A phone number input is required.";
    }

    const challengeCode = yield context.df.callActivity("E4_SendSmsChallenge", phoneNumber);

    // The user has 90 seconds to respond with the code they received in the SMS message.
    const expiration = moment.utc(context.df.currentUtcDateTime).add(90, "s");
    const timeoutTask = context.df.createTimer(expiration.toDate());

    let authorized = false;
    for (let i = 0; i <= 3; i++) {
        const challengeResponseTask = context.df.waitForExternalEvent("SmsChallengeResponse");

        const winner = yield context.df.Task.any([challengeResponseTask, timeoutTask]);

        if (winner === challengeResponseTask) {
            // We got back a response! Compare it to the challenge code.
            if (challengeResponseTask.result === challengeCode) {
                authorized = true;
                break;
            }
        } else {
            // Timeout expired
            break;
        }
    }

    if (!timeoutTask.isCompleted) {
        // All pending timers must be complete or canceled before the function exits.
        timeoutTask.cancel();
    }

    return authorized;
});

Annotazioni

Potrebbe non essere ovvio in un primo momento, ma questo agente di orchestrazione non viola il vincolo di orchestrazione deterministico. È deterministico perché la currentUtcDateTime proprietà calcola l'ora di scadenza del timer e restituisce lo stesso valore in ogni riproduzione in questo punto nel codice dell'agente di orchestrazione. Questo comportamento garantisce che winner sia lo stesso per ogni chiamata ripetuta a context.df.Task.any.

Modello di programmazione V4

Ecco il codice che implementa la smsPhoneVerification funzione di orchestrazione:

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

const sendSmsChallengeActivityName = "sendSmsChallenge";

df.app.orchestration("smsPhoneVerification", function* (context) {
    const phoneNumber = context.df.getInput();
    if (!phoneNumber) {
        throw new Error("A phone number input is required.");
    }

    const challengeCode = yield context.df.callActivity(sendSmsChallengeActivityName, phoneNumber);

    // The user has 90 seconds to respond with the code they received in the SMS message.
    const expiration = DateTime.fromJSDate(context.df.currentUtcDateTime).plus({ seconds: 90 });
    const timeoutTask = context.df.createTimer(expiration.toJSDate());

    let authorized = false;
    for (let i = 0; i <= 3; i++) {
        const challengeResponseTask = context.df.waitForExternalEvent("SmsChallengeResponse");

        const winner = yield context.df.Task.any([challengeResponseTask, timeoutTask]);

        if (winner === timeoutTask) {
            // Timeout expired
            break;
        }

        // We got back a response! Compare it to the challenge code.
        if (challengeResponseTask.result === challengeCode) {
            authorized = true;
            break;
        }
    }

    if (!timeoutTask.isCompleted) {
        // All pending timers must be complete or canceled before the function exits.
        timeoutTask.cancel();
    }

    return authorized;
});

Python

La funzione E4_SmsPhoneVerification usa il codice function.json standard per le funzioni dell'agente di orchestrazione.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "context",
      "type": "orchestrationTrigger",
      "direction": "in"
    }
  ]
}

Il codice che implementa la funzione è il seguente:

import azure.durable_functions as df
from datetime import timedelta

def is_valid_phone_number(phone_number: str):
    has_area_code = phone_number[0] == "+"
    is_positive_num = phone_number[1:].isdigit()
    return has_area_code and is_positive_num

def orchestrator_function(context: df.DurableOrchestrationContext):

    phone_number = context.get_input()

    if (not phone_number) or (not is_valid_phone_number(phone_number)):
        msg = "Please provide a phone number beginning with an international dialing prefix"+\
            "(+) followed by the country code, and then rest of the phone number. Example:"\
            "'+1425XXXXXXX'"
        raise Exception(msg)

    challenge_code = yield context.call_activity("SendSMSChallenge", phone_number)

    expiration = context.current_utc_datetime + timedelta(seconds=180)
    timeout_task = context.create_timer(expiration)

    authorized = False
    for _ in range(3):
        challenge_response_task = context.wait_for_external_event("SmsChallengeResponse")
        winner = yield context.task_any([challenge_response_task, timeout_task])

        if (winner == challenge_response_task):
            # We got back a response! Compare it to the challenge code
            if (challenge_response_task.result == challenge_code):
                authorized = True
                break
        else:
            # Timeout expired
            break
    
    if not timeout_task.is_completed:
        # All pending timers must be complete or canceled before the function exits.
        timeout_task.cancel()

    return authorized

main = df.Orchestrator.create(orchestrator_function)

Annotazioni

Benché non sia immediatamente ovvio, questo agente di orchestrazione non viola il vincolo di orchestrazione deterministico. È deterministico perché la proprietà currentUtcDateTime viene usata per calcolare l'ora di scadenza del timer e restituisce lo stesso valore a ogni riesecuzione in questo punto del codice dell'agente di orchestrazione. Questo comportamento è importante per garantire gli stessi risultati winner da ogni chiamata ripetuta a context.df.Task.any.

PowerShell

L'esempio di PowerShell sarà presto disponibile.

Java

Java esempio presto disponibile.

Una volta avviata, questa funzione di orchestrazione esegue le seguenti operazioni:

1. Ottiene un numero di telefono a cui inviare la notifica SMS.
2. Chiama E4_SendSmsChallenge per inviare un messaggio SMS all'utente e restituisce il codice di verifica a quattro cifre previsto.
3. Crea un timer durevole che attiva 90 secondi dopo l'ora corrente.
4. In parallelo con il timer, si attende un evento SmsChallengeResponse da parte dell'utente.

L'utente riceve un messaggio SMS con un codice di quattro cifre Hanno 90 secondi per inviare lo stesso codice all'istanza orchestratore per completare la verifica. Se inviano il codice errato, ottengono altri tre tentativi nella stessa finestra di 90 secondi.

Avvertimento

Annullare i timer non più necessari. Nell'esempio precedente, l'orchestrazione annulla il timer quando accetta una risposta alla sfida.

L'agente di orchestrazione invia una richiesta di approvazione, quindi attende una risposta umana o un timeout.

C#

using Microsoft.DurableTask;
using System;
using System.Threading;
using System.Threading.Tasks;

[DurableTask(nameof(ApprovalOrchestration))]
public class ApprovalOrchestration : TaskOrchestrator<ApprovalRequestData, ApprovalResult>
{
    public override async Task<ApprovalResult> RunAsync(
        TaskOrchestrationContext context, ApprovalRequestData input)
    {
        string requestId = input.RequestId;
        double timeoutHours = input.TimeoutHours;

        // Step 1: Submit the approval request (notify approver)
        SubmissionResult submissionResult = await context.CallActivityAsync<SubmissionResult>(
            nameof(SubmitApprovalRequestActivity), input);

        // Make the status available via custom status
        context.SetCustomStatus(submissionResult);

        // Step 2: Create a durable timer for the timeout
        DateTime timeoutDeadline = context.CurrentUtcDateTime.AddHours(timeoutHours);

        using var timeoutCts = new CancellationTokenSource();
        Task timeoutTask = context.CreateTimer(timeoutDeadline, timeoutCts.Token);

        // Step 3: Wait for an external event (approval/rejection)
        Task<ApprovalResponseData> approvalTask = context.WaitForExternalEvent<ApprovalResponseData>(
            "approval_response");

        // Step 4: Wait for either the timeout or the approval response
        Task completedTask = await Task.WhenAny(approvalTask, timeoutTask);

        // Step 5: Process based on which task completed
        ApprovalResult result;

        if (completedTask == approvalTask)
        {
            // Human responded in time - cancel the timeout timer
            timeoutCts.Cancel();

            ApprovalResponseData approvalData = approvalTask.Result;

            // Process the approval
            result = await context.CallActivityAsync<ApprovalResult>(
                nameof(ProcessApprovalActivity),
                new ProcessApprovalInput
                {
                    RequestId = requestId,
                    IsApproved = approvalData.IsApproved,
                    Approver = approvalData.Approver
                });
        }
        else
        {
            // Timeout occurred
            result = new ApprovalResult
            {
                RequestId = requestId,
                Status = "Timeout",
                ProcessedAt = context.CurrentUtcDateTime.ToString("o")
            };
        }

        return result;
    }
}

JavaScript

import {
  OrchestrationContext,
  TOrchestrator,
  whenAny,
} from "@microsoft/durabletask-js";

const approvalOrchestrator: TOrchestrator = async function* (
  ctx: OrchestrationContext,
  amount: number
): any {
  // Step 1: Submit the request
  const requestId: string = yield ctx.callActivity(submitRequest, { amount });

  ctx.setCustomStatus({ stage: "Awaiting approval", requestId });

  // Step 2: Race external event vs timer
  const approvalEvent = ctx.waitForExternalEvent<{ approved: boolean }>(
    "approval"
  );
  const timeout = ctx.createTimer(5); // 5-second timeout

  const winner = yield whenAny([approvalEvent, timeout]);

  let result: string;
  if (winner === approvalEvent) {
    // Human responded in time
    const decision = approvalEvent.getResult();
    ctx.setCustomStatus({
      stage: "Processing",
      requestId,
      approved: decision.approved,
    });
    result = yield ctx.callActivity(processApproval, {
      requestId,
      approved: decision.approved,
    });
  } else {
    // Timer fired first — timed out
    ctx.setCustomStatus({ stage: "Timed out", requestId });
    result = yield ctx.callActivity(notifyTimeout, requestId);
  }

  ctx.setCustomStatus({ stage: "Completed", requestId });
  return result;
};

Python

import datetime
from durabletask import task

def human_interaction_orchestrator(ctx: task.OrchestrationContext, input_data: dict) -> dict:
    """
    Orchestrator that demonstrates the human interaction pattern.

    Submits an approval request, then waits for a human to approve or reject.
    """
    request_id = input_data.get("request_id")
    timeout_hours = input_data.get("timeout_hours", 24)

    # Step 1: Submit the approval request (notify approver)
    request_data = {
        "request_id": request_id,
        "requester": input_data.get("requester"),
        "item": input_data.get("item")
    }

    submission_result = yield ctx.call_activity("submit_approval_request", input=request_data)

    # Make the status available via custom status
    ctx.set_custom_status(submission_result)

    # Step 2: Create a durable timer for the timeout
    timeout_deadline = ctx.current_utc_datetime + datetime.timedelta(hours=timeout_hours)
    timeout_task = ctx.create_timer(timeout_deadline)

    # Step 3: Wait for an external event (approval/rejection)
    approval_task = ctx.wait_for_external_event("approval_response")

    # Step 4: Wait for either the timeout or the approval response
    winner_task = yield task.when_any([approval_task, timeout_task])

    # Step 5: Process based on which task completed
    if winner_task == approval_task:
        # Human responded in time
        approval_data = yield approval_task

        # Process the approval
        result = yield ctx.call_activity("process_approval", input={
            "request_id": request_id,
            "is_approved": approval_data.get("is_approved", False),
            "approver": approval_data.get("approver", "Unknown")
        })
    else:
        # Timeout occurred
        result = {
            "request_id": request_id,
            "status": "Timeout",
            "timed_out_at": ctx.current_utc_datetime.isoformat()
        }

    return result

PowerShell

Questo esempio viene illustrato per .NET, JavaScript, Java e Python.

Java

import com.microsoft.durabletask.*;
import com.microsoft.durabletask.azuremanaged.DurableTaskSchedulerWorkerExtensions;
import java.time.Duration;

DurableTaskGrpcWorker worker = DurableTaskSchedulerWorkerExtensions.createWorkerBuilder(connectionString)
    .addOrchestration(new TaskOrchestrationFactory() {
        @Override
        public String getName() { return "ApprovalWorkflow"; }

        @Override
        public TaskOrchestration create() {
            return ctx -> {
                // Get the approval request
                ApprovalRequest request = ctx.getInput(ApprovalRequest.class);

                // Set initial status
                ctx.setCustomStatus(new WorkflowStatus("Waiting for approval", null));

                // Create a timeout timer
                Task timeoutTask = ctx.createTimer(
                    Duration.ofHours((long) request.timeoutHours));

                // Wait for external event (approval response)
                Task<ApprovalResponse> approvalTask = ctx.waitForExternalEvent(
                    "approval_response", ApprovalResponse.class);

                // Wait for either approval or timeout
                Task<?> winner = ctx.anyOf(approvalTask, timeoutTask).await();

                if (winner == approvalTask) {
                    // Human responded in time
                    ApprovalResponse response = approvalTask.await();
                    String status = response.isApproved ? "APPROVED" : "REJECTED";
                    ctx.setCustomStatus(new WorkflowStatus(status, response));
                    ctx.complete(new WorkflowResult(
                        status,
                        response.isApproved ? "Request approved" : "Request rejected"));
                } else {
                    // Timeout occurred
                    ctx.setCustomStatus(new WorkflowStatus("Timed out", null));
                    ctx.complete(new WorkflowResult("TIMEOUT", "Request timed out"));
                }
            };
        }
    })
    .build();

Questo agente di orchestrazione esegue le azioni seguenti:

1. Invia la richiesta di approvazione chiamando un'attività che invia una notifica al responsabile dell'approvazione.
2. Imposta lo stato personalizzato in modo che i client possano tenere traccia dello stato di avanzamento.
3. Crea un timer durevole per la scadenza del timeout.
4. Attende un evento esterno (approval_response) generato dal responsabile approvazione.
5. Usa WhenAny, when_any o anyOf per attendere quella che si completa per prima: l'approvazione o il timeout.
6. Elabora il risultato in base all'attività completata.

Avvertimento

Annullare i timer non più necessari. Nell'esempio C# l'orchestrazione annulla il timer di timeout quando riceve l'approvazione.

Definire le attività

Funzione dell’attività E4_SendSmsChallenge

La funzione E4_SendSmsChallenge usa l'associazione Twilio per inviare un messaggio SMS che include un codice a quattro cifre all'utente.

C#

[FunctionName("E4_SendSmsChallenge")]
public static int SendSmsChallenge(
    [ActivityTrigger] string phoneNumber,
    ILogger log,
    [TwilioSms(AccountSidSetting = "TwilioAccountSid", AuthTokenSetting = "TwilioAuthToken", From = "%TwilioPhoneNumber%")]
        out CreateMessageOptions message)
{
    // Get a random number generator with a random seed (not time-based)
    var rand = new Random(Guid.NewGuid().GetHashCode());
    int challengeCode = rand.Next(10000);

    log.LogInformation($"Sending verification code {challengeCode} to {phoneNumber}.");

    message = new CreateMessageOptions(new PhoneNumber(phoneNumber));
    message.Body = $"Your verification code is {challengeCode:0000}";

    return challengeCode;
}

Annotazioni

Per eseguire l'esempio, installare il pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.Twilio. Non installare il pacchetto NuGet Twilio principale perché può causare conflitti di versione ed errori di compilazione.

JavaScript

Modello di programmazione V3

Il filefunction.json è definito come segue:

{
  "bindings": [
    {
      "name": "phoneNumber",
      "type": "activityTrigger",
      "direction": "in"
    },
    {
      "type": "twilioSms",
      "name": "message",
      "from": "%TwilioPhoneNumber%",
      "accountSidSetting": "TwilioAccountSid",
      "authTokenSetting": "TwilioAuthToken",
      "direction": "out"
    }
  ],
  "disabled": false
}

Questo codice genera il codice di verifica a quattro cifre e invia il messaggio SMS:

const seedrandom = require("seedrandom");
const uuidv1 = require("uuid/v1");

module.exports = function (context, phoneNumber) {
    // Get a random number generator with a random seed (not time-based)
    const rand = seedrandom(uuidv1());
    const challengeCode = Math.floor(rand() * 10000);

    context.log(`Sending verification code ${challengeCode} to ${phoneNumber}.`);

    context.bindings.message = {
        body: `Your verification code is ${challengeCode.toPrecision(4)}`,
        to: phoneNumber,
    };

    context.done(null, challengeCode);
};

Modello di programmazione V4

Ecco il codice che genera il codice di verifica a quattro cifre e invia il messaggio SMS:

const { output } = require("@azure/functions");
const df = require("durable-functions");

const sendSmsChallengeActivityName = "sendSmsChallenge";

const twilioOutput = output.generic({
    type: "twilioSms",
    from: "%TwilioPhoneNumber%",
    accountSidSetting: "TwilioAccountSid",
    authTokenSetting: "TwilioAuthToken",
});

df.app.activity(sendSmsChallengeActivityName, {
    extraOutputs: [twilioOutput],
    handler: function (phoneNumber, context) {
        // Get a random challenge code
        const challengeCode = Math.floor(Math.random() * 10000);

        context.log(`Sending verification code ${challengeCode} to ${phoneNumber}.`);

        context.extraOutputs.set(twilioOutput, {
            body: `Your verification code is ${challengeCode.toPrecision(4)}`,
            to: phoneNumber,
        });

        return challengeCode;
    },
});

Python

Il filefunction.json è definito come segue:

{
  "bindings": [
    {
      "name": "phoneNumber",
      "type": "activityTrigger",
      "direction": "in"
    },
    {
      "type": "twilioSms",
      "name": "message",
      "from": "%TwilioPhoneNumber%",
      "accountSidSetting": "TwilioAccountSid",
      "authTokenSetting": "TwilioAuthToken",
      "direction": "out"
    }
  ]
}

Questo codice genera il codice di verifica a quattro cifre e invia il messaggio SMS:

import json
import random

random.seed(10)

def main(phoneNumber, message):
  code = random.randint(0, 10000)
  payload = {
    "body": f"Your verification code is {code}",
    "to": phoneNumber
  }

  message.set(json.dumps(payload))
  code_str = str(code)
  return code_str

PowerShell

L'esempio di PowerShell sarà presto disponibile.

Java

Java esempio presto disponibile.

Le attività inviano la richiesta di approvazione ed elaborano la risposta.

Invia l'attività di richiesta di approvazione

C#

using Microsoft.DurableTask;
using Microsoft.Extensions.Logging;
using System;
using System.Threading.Tasks;

[DurableTask(nameof(SubmitApprovalRequestActivity))]
public class SubmitApprovalRequestActivity : TaskActivity<ApprovalRequestData, SubmissionResult>
{
    private readonly ILogger<SubmitApprovalRequestActivity> _logger;

    public SubmitApprovalRequestActivity(ILogger<SubmitApprovalRequestActivity> logger)
    {
        _logger = logger;
    }

    public override Task<SubmissionResult> RunAsync(
        TaskActivityContext context, ApprovalRequestData input)
    {
        _logger.LogInformation(
            "Submitting approval request {RequestId} from {Requester} for {Item}",
            input.RequestId, input.Requester, input.Item);

        // In a real system, this would send an email, notification, or update a database
        var result = new SubmissionResult
        {
            RequestId = input.RequestId,
            Status = "Pending",
            SubmittedAt = DateTime.UtcNow.ToString("o"),
            ApprovalUrl = $"http://localhost:8000/api/approvals/{input.RequestId}"
        };

        return Task.FromResult(result);
    }
}

JavaScript

import { ActivityContext } from "@microsoft/durabletask-js";

const submitRequest = async (
  _ctx: ActivityContext,
  request: { amount: number }
): Promise<string> => {
  console.log(
    `[submitRequest] Purchase request submitted: $${request.amount}`
  );
  return `REQ-${Date.now()}`;
};

Python

import datetime
from durabletask import task

def submit_approval_request(ctx: task.ActivityContext, request_data: dict) -> dict:
    """
    Activity that submits an approval request.
    In a real application, this would notify a human approver via email, message, etc.
    """
    request_id = request_data.get("request_id")
    requester = request_data.get("requester")
    item = request_data.get("item")

    # In a real system, this would send an email, notification, or update a database
    return {
        "request_id": request_id,
        "status": "Pending",
        "submitted_at": datetime.datetime.now().isoformat(),
        "approval_url": f"http://localhost:8000/api/approvals/{request_id}"
    }

PowerShell

Questo esempio viene illustrato per .NET, JavaScript, Java e Python.

Java

L'esempio di Java invia direttamente la richiesta di approvazione. Per un'app di produzione, creare un'attività separata:

.addActivity(new TaskActivityFactory() {
    @Override
    public String getName() { return "SubmitApprovalRequest"; }

    @Override
    public TaskActivity create() {
        return ctx -> {
            ApprovalRequest request = ctx.getInput(ApprovalRequest.class);

            // In a real system, send email/notification
            logger.info("Submitting approval request for " + request.item);

            return new SubmissionResult(
                "Pending",
                Instant.now().toString(),
                "http://localhost:8000/api/approvals/" + request.requester);
        };
    }
})

Attività di approvazione del processo

C#

using Microsoft.DurableTask;
using Microsoft.Extensions.Logging;
using System;
using System.Threading.Tasks;

[DurableTask(nameof(ProcessApprovalActivity))]
public class ProcessApprovalActivity : TaskActivity<ProcessApprovalInput, ApprovalResult>
{
    private readonly ILogger<ProcessApprovalActivity> _logger;

    public ProcessApprovalActivity(ILogger<ProcessApprovalActivity> logger)
    {
        _logger = logger;
    }

    public override Task<ApprovalResult> RunAsync(
        TaskActivityContext context, ProcessApprovalInput input)
    {
        string status = input.IsApproved ? "Approved" : "Rejected";
        _logger.LogInformation(
            "Processing {Status} request {RequestId} by {Approver}",
            status, input.RequestId, input.Approver);

        // In a real system, this would update a database, trigger workflows, etc.
        var result = new ApprovalResult
        {
            RequestId = input.RequestId,
            Status = status,
            ProcessedAt = DateTime.UtcNow.ToString("o"),
            Approver = input.Approver
        };

        return Task.FromResult(result);
    }
}

// Data classes
public class ApprovalRequestData
{
    public string RequestId { get; set; } = string.Empty;
    public string Requester { get; set; } = string.Empty;
    public string Item { get; set; } = string.Empty;
    public double TimeoutHours { get; set; } = 24.0;
}

public class ApprovalResponseData
{
    public bool IsApproved { get; set; }
    public string Approver { get; set; } = string.Empty;
}

public class SubmissionResult
{
    public string RequestId { get; set; } = string.Empty;
    public string Status { get; set; } = string.Empty;
    public string SubmittedAt { get; set; } = string.Empty;
    public string ApprovalUrl { get; set; } = string.Empty;
}

public class ProcessApprovalInput
{
    public string RequestId { get; set; } = string.Empty;
    public bool IsApproved { get; set; }
    public string Approver { get; set; } = string.Empty;
}

public class ApprovalResult
{
    public string RequestId { get; set; } = string.Empty;
    public string Status { get; set; } = string.Empty;
    public string ProcessedAt { get; set; } = string.Empty;
    public string? Approver { get; set; }
}

JavaScript

import { ActivityContext } from "@microsoft/durabletask-js";

const processApproval = async (
  _ctx: ActivityContext,
  data: { requestId: string; approved: boolean }
): Promise<string> => {
  console.log(
    `[processApproval] Request ${data.requestId}: ${
      data.approved ? "APPROVED" : "REJECTED"
    }`
  );
  return data.approved ? "Order placed" : "Order cancelled";
};

const notifyTimeout = async (
  _ctx: ActivityContext,
  requestId: string
): Promise<string> => {
  console.log(
    `[notifyTimeout] Request ${requestId} timed out — auto-rejected`
  );
  return "Timed out — auto-rejected";
};

Python

import datetime
from durabletask import task

def process_approval(ctx: task.ActivityContext, approval_data: dict) -> dict:
    """
    Activity that processes the approval once received.
    """
    request_id = approval_data.get("request_id")
    is_approved = approval_data.get("is_approved")
    approver = approval_data.get("approver")

    status = "Approved" if is_approved else "Rejected"

    # In a real system, this would update a database, trigger workflows, etc.
    return {
        "request_id": request_id,
        "status": status,
        "processed_at": datetime.datetime.now().isoformat(),
        "approver": approver
    }

PowerShell

Questo esempio viene illustrato per .NET, JavaScript, Java e Python.

Java

L'esempio Java elabora le approvazioni in linea nell'orchestratore. Per un'app di produzione, creare un'attività separata.

Eseguire l'esempio di interazione umana

Usare le funzioni attivate da HTTP nell'esempio per avviare l'orchestrazione inviando la richiesta HTTP POST seguente:

POST http://{host}/orchestrators/E4_SmsPhoneVerification
Content-Length: 14
Content-Type: application/json

"+1425XXXXXXX"

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8

{"id":"741c65651d4c40cea29acdd5bb47baf1",
 "sendEventPostUri":"http://{host}/runtime/webhooks/durabletask/instances/741c65651d4c40cea29acdd5bb47baf1/raiseEvent/{eventName}?taskHub=DurableFunctionsHub&connection=Storage&code={systemKey}",
 "statusQueryGetUri":"http://{host}/runtime/webhooks/durabletask/instances/741c65651d4c40cea29acdd5bb47baf1?taskHub=...&code={systemKey}",
 "terminatePostUri":"http://{host}/runtime/webhooks/durabletask/instances/741c65651d4c40cea29acdd5bb47baf1/terminate?reason={text}&taskHub=...&code={systemKey}"}

La funzione dell'agente di orchestrazione riceve il numero di telefono e invia immediatamente un messaggio SMS a tale numero con un codice di verifica a 4 cifre generato in modo casuale, 2168ad esempio . La funzione attende quindi 90 secondi per ricevere una risposta.

Per rispondere con il codice, usare RaiseEventAsync (.NET) o raiseEvent (JavaScript e TypeScript) in un'altra funzione oppure chiamare sendEventPostUri endpoint HTTP POST nella risposta 202. Sostituire {eventName} con SmsChallengeResponse:

POST http://{host}/runtime/webhooks/durabletask/instances/741c65651d4c40cea29acdd5bb47baf1/raiseEvent/SmsChallengeResponse?taskHub=DurableFunctionsHub&connection=Storage&code={systemKey}
Content-Length: 4
Content-Type: application/json

2168

Se si invia l'evento prima della scadenza del timer, l'orchestrazione viene completata e il campo output viene impostato su true, che indica un esito positivo della verifica.

GET http://{host}/runtime/webhooks/durabletask/instances/741c65651d4c40cea29acdd5bb47baf1?taskHub=DurableFunctionsHub&connection=Storage&code={systemKey}

HTTP/1.1 200 OK
Content-Length: 144
Content-Type: application/json; charset=utf-8

{"runtimeStatus":"Completed","input":"+1425XXXXXXX","output":true,"createdTime":"2026-04-23T19:10:49Z","lastUpdatedTime":"2026-04-23T19:12:23Z"}

Se il timer scade o si inserisce il codice errato quattro volte, eseguire una query di stato per vedere output impostato su false, che indica che la verifica del telefono non è riuscita.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 145

{"runtimeStatus":"Completed","input":"+1425XXXXXXX","output":false,"createdTime":"2026-04-23T19:20:49Z","lastUpdatedTime":"2026-04-23T19:22:23Z"}

Per eseguire l'esempio:

1. Avvia l'emulatore del Durable Task Scheduler per lo sviluppo locale. Docker deve essere installato.

   docker run -d -p 8080:8080 -p 8082:8082 --name dts-emulator mcr.microsoft.com/dts/dts-emulator:latest
   

2. Avviare il processo di lavoro per registrare l'agente di orchestrazione e le attività.

3. Eseguire il client per pianificare un flusso di lavoro di approvazione e inviare eventi.

C#

using System;
using System.Threading.Tasks;

var client = DurableTaskClientBuilder.UseDurableTaskScheduler(connectionString).Build();

// Schedule the approval workflow
var input = new ApprovalRequestData
{
    RequestId = "request-" + Guid.NewGuid().ToString(),
    Requester = "john.doe@example.com",
    Item = "Vacation Request - 5 days",
    TimeoutHours = 24
};

string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
    nameof(ApprovalOrchestration), input);

Console.WriteLine($"Started approval workflow: {instanceId}");

// Simulate human approving the request
Console.WriteLine("Simulating approval...");
await Task.Delay(2000);

// Raise the approval event
var approvalResponse = new ApprovalResponseData
{
    IsApproved = true,
    Approver = "manager@example.com"
};

await client.RaiseEventAsync(instanceId, "approval_response", approvalResponse);

// Wait for completion
var result = await client.WaitForInstanceCompletionAsync(instanceId, getInputsAndOutputs: true);
Console.WriteLine($"Result: {result.ReadOutputAs<ApprovalResult>().Status}");

JavaScript

import {
  DurableTaskAzureManagedClientBuilder,
  DurableTaskAzureManagedWorkerBuilder,
} from "@microsoft/durabletask-js-azuremanaged";

const client = new DurableTaskAzureManagedClientBuilder()
  .connectionString(connectionString)
  .build();

const worker = new DurableTaskAzureManagedWorkerBuilder()
  .connectionString(connectionString)
  .addOrchestrator(approvalOrchestrator)
  .addActivity(submitRequest)
  .addActivity(processApproval)
  .addActivity(notifyTimeout)
  .build();

await worker.start();

// Schedule the approval workflow
const approvalId = await client.scheduleNewOrchestration(
  approvalOrchestrator,
  500 // amount
);

console.log(`Orchestration started: ${approvalId}`);

// Wait for it to reach "Awaiting approval", then send approval
await new Promise((r) => setTimeout(r, 3000));

await client.raiseOrchestrationEvent(approvalId, "approval", {
  approved: true,
});
console.log("Sent approval event");

const result = await client.waitForOrchestrationCompletion(
  approvalId,
  true,
  60
);
console.log(`Result: ${result?.serializedOutput}`);

await worker.stop();
await client.stop();

Python

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
import time
import uuid

client = DurableTaskSchedulerClient(
    host_address=endpoint,
    secure_channel=endpoint != "http://localhost:8080",
    taskhub=taskhub,
    token_credential=credential
)

# Schedule the approval workflow
input_data = {
    "request_id": f"request-{uuid.uuid4()}",
    "requester": "john.doe@example.com",
    "item": "Vacation Request - 5 days",
    "timeout_hours": 24
}

instance_id = client.schedule_new_orchestration(
    human_interaction_orchestrator,
    input=input_data
)

print(f"Started approval workflow: {instance_id}")

# Simulate human approving the request
print("Simulating approval...")
time.sleep(2)

# Raise the approval event
approval_response = {
    "is_approved": True,
    "approver": "manager@example.com"
}

client.raise_orchestration_event(instance_id, "approval_response", data=approval_response)

# Wait for completion
result = client.wait_for_orchestration_completion(instance_id, timeout=60)
print(f"Result: {result.serialized_output}")

PowerShell

Questo esempio viene illustrato per .NET, JavaScript, Java e Python.

Java

import java.time.Duration;
import java.time.Instant;
import java.util.UUID;

DurableTaskClient client = DurableTaskSchedulerClientExtensions
    .createClientBuilder(connectionString).build();

// Schedule the approval workflow
ApprovalRequest request = new ApprovalRequest(
    "john.doe@example.com",
    "Vacation Request - 5 days",
    24  // timeout hours
);

String instanceId = client.scheduleNewOrchestrationInstance(
    "ApprovalWorkflow",
    new NewOrchestrationInstanceOptions()
        .setInput(request)
        .setInstanceId("request-" + UUID.randomUUID().toString()));

System.out.println("Started approval workflow: " + instanceId);

// Simulate human approving the request
System.out.println("Simulating approval...");
Thread.sleep(2000);

// Raise the approval event
ApprovalResponse response = new ApprovalResponse(
    true,  // isApproved
    "manager@example.com",
    "Approved",
    Instant.now().toString()
);

client.raiseEvent(instanceId, "approval_response", response);

// Wait for completion
OrchestrationMetadata result = client.waitForInstanceCompletion(
    instanceId, Duration.ofSeconds(60), true);

System.out.println("Result: " + result.readOutputAs(WorkflowResult.class).status);

Passaggi successivi

Questo esempio illustra le funzionalità avanzate di Durable Functions, incluse le API /> /. Illustra come combinare Task.WhenAny (C#), context.df.Task.any (JavaScript e TypeScript) o context.task_any (Python) per implementare un modello di timeout affidabile per i flussi di lavoro che attendono la risposta degli utenti.

Informazioni sulle associazioni Durable Functions

• Timer durevoli
• Eventi esterni e gestione delle istanze
• Orchestrazioni eterne

Questo esempio illustra come usare gli SDK di Durable Task per implementare flussi di lavoro che attendono che gli utenti rispondano, con timeout configurabili. Concetti chiave:

• Eventi esterni: uso di WaitForExternalEvent per attendere l'input
• Timer durevoli: utilizzo di CreateTimer per implementare i timeout
• Attività in corso: uso di WhenAny, when_any o anyOf per gestire qualsiasi attività venga completata per prima

Introduzione agli SDK per attività durevoli

• Timer durevoli
• Orchestrazioni eterne
• Durable Task JavaScript SDK in GitHub