Varaktig orkestrering

Durable Functions är ett tillägg till Azure Functions. Du kan använda en orchestrator-funktion för att samordna körningen av andra Durable-funktioner i en funktionsapp. Orchestrator-funktioner har följande egenskaper:

• Orchestrator-funktioner definierar funktionsarbetsflöden med hjälp av procedurkod. Inga deklarativa scheman eller designers behövs.
• Orchestrator-funktioner kan anropa andra varaktiga funktioner synkront och asynkront. Utdata från anropade funktioner kan sparas på ett tillförlitligt sätt i lokala variabler.
• Orchestrator-funktioner är hållbara och tillförlitliga. Körningsstatusen kontrollpunkteras automatiskt när funktionen "väntar" eller "ger". Det lokala tillståndet förloras aldrig när processen återanvänds eller den virtuella datorn startas om.
• Orchestrator-funktioner kan vara tidskrävande. Den totala livslängden för en orkestreringsinstans kan vara sekunder, dagar, månader eller aldrig slut.

Den här artikeln ger dig en översikt över orkestreringsfunktioner och hur de kan hjälpa dig att lösa olika apputvecklingsutmaningar. Om du inte redan är bekant med de typer av funktioner som är tillgängliga i en Durable Functions-app läser du artikeln Durable Function types först.

Orkestreringsidentitet

Varje instans av en orkestrering har en instansidentifierare (även kallat instans-ID). Som standard är varje instans-ID ett automatiskt genererat GUID. Instans-ID:t kan dock också vara valfritt användargenererat strängvärde. Varje orkestreringsinstans-ID måste vara unikt i en aktivitetshubb.

Följande är några regler om instans-ID:t:

• Instans-ID:t måste vara mellan 1 och 100 tecken.
• Instans-ID:t får inte börja med @.
• Instans-ID får inte innehålla /, \, #eller ? tecken.
• Instans-ID:t får inte innehålla kontrolltecken.

En orkestrerings instans-ID är en obligatorisk parameter för de flesta instanshanteringsåtgärder. De är också viktiga för diagnostik, till exempel genom att söka igenom orkestreringsspårningsdata i Application Insights i felsöknings- eller analyssyfte. Därför rekommenderar vi att du sparar genererade instans-ID:t på någon extern plats (till exempel en databas eller i programloggar) där de enkelt kan refereras senare.

Tillförlitlighet

Orchestrator-funktioner underhåller på ett tillförlitligt sätt sitt körningstillstånd med hjälp av designmönstret för händelsekällor . I stället för att direkt lagra det aktuella tillståndet för en orkestrering använder Durable Task Framework ett tilläggsarkiv för att registrera hela serien med åtgärder som funktionsorkestreringen vidtar. Ett tilläggslager har många fördelar jämfört med att "dumpa" hela körningstillståndet. Fördelarna är ökad prestanda, skalbarhet och svarstider. Du får också slutlig konsekvens för transaktionsdata och fullständiga spårningsspår och historik. Granskningsspåren stöder tillförlitliga kompenserande åtgärder.

Durable Functions använder händelsekällor transparent. I bakgrunden ger operatorn await (C#) eller yield (JavaScript/Python) i en orchestrator-funktion kontroll över orchestrator-tråden tillbaka till Durable Task Framework-avsändaren. När det gäller Java finns det inget särskilt språknyckelord. I stället ger anropande .await() av en uppgift kontroll tillbaka till avsändaren via en anpassad Throwable. Avsändaren genomför sedan alla nya åtgärder som orkestreringsfunktionen har schemalagt (till exempel att anropa en eller flera underordnade funktioner eller schemalägga en varaktig timer) till lagring. Den transparenta incheckningsåtgärden uppdaterar körningshistoriken för orkestreringsinstansen genom att lägga till alla nya händelser i lagringen, ungefär som en logg med endast tillägg. På samma sätt skapar incheckningsåtgärden meddelanden i lagringen för att schemalägga det faktiska arbetet. Nu kan orkestreringsfunktionen tas bort från minnet. Durable Functions använder som standard Azure Storage som sitt körningstillståndslager, men andra lagringsleverantörer stöds också.

När en orkestreringsfunktion får mer arbete att göra (till exempel ett svarsmeddelande tas emot eller en varaktig timer upphör att gälla) vaknar orkestratorn och kör hela funktionen igen från början för att återskapa det lokala tillståndet. Under reprisen, om koden försöker anropa en funktion (eller utföra något annat asynkront arbete), läser Durable Task Framework körningshistoriken för den aktuella orkestreringen. Om den upptäcker att aktivitetsfunktionen redan har körts och gett ett resultat, spelas funktionens resultat upp igen och orchestrator-koden fortsätter att köras. Reprisen fortsätter tills funktionskoden är klar eller tills den har schemalagt nytt asynkront arbete.

Orkestreringshistorik

Beteendet för händelsekällor i Durable Task Framework är nära kopplat till den orchestrator-funktionskod som du skriver. Anta att du har en aktivitetslänkande orkestreringsfunktion, till exempel följande orchestrator-funktion:

[FunctionName("HelloCities")]
public static async Task<List<string>> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var outputs = new List<string>();

    outputs.Add(await context.CallActivityAsync<string>("SayHello", "Tokyo"));
    outputs.Add(await context.CallActivityAsync<string>("SayHello", "Seattle"));
    outputs.Add(await context.CallActivityAsync<string>("SayHello", "London"));

    // returns ["Hello Tokyo!", "Hello Seattle!", "Hello London!"]
    return outputs;
}

[Function("HelloCities")]
public static async Task<List<string>> Run(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var outputs = new List<string>();

    outputs.Add(await context.CallActivityAsync<string>("SayHello", "Tokyo"));
    outputs.Add(await context.CallActivityAsync<string>("SayHello", "Seattle"));
    outputs.Add(await context.CallActivityAsync<string>("SayHello", "London"));

    // returns ["Hello Tokyo!", "Hello Seattle!", "Hello London!"]
    return outputs;
}

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

module.exports = df.orchestrator(function*(context) {
    const output = [];
    output.push(yield context.df.callActivity("SayHello", "Tokyo"));
    output.push(yield context.df.callActivity("SayHello", "Seattle"));
    output.push(yield context.df.callActivity("SayHello", "London"));

    // returns ["Hello Tokyo!", "Hello Seattle!", "Hello London!"]
    return output;
});

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

df.app.orchestration("helloSequence", function* (context) {
    const output = [];
    output.push(yield context.df.callActivity(helloActivityName, "Tokyo"));
    output.push(yield context.df.callActivity(helloActivityName, "Seattle"));
    output.push(yield context.df.callActivity(helloActivityName, "Cairo"));

    // returns ["Hello Tokyo!", "Hello Seattle!", "Hello Cairo!"]
    return output;
});

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

def orchestrator_function(context: df.DurableOrchestrationContext):
    result1 = yield context.call_activity('SayHello', "Tokyo")
    result2 = yield context.call_activity('SayHello', "Seattle")
    result3 = yield context.call_activity('SayHello', "London")
    return [result1, result2, result3]

main = df.Orchestrator.create(orchestrator_function)

param($Context)

$output = @()

$output += Invoke-DurableActivity -FunctionName 'SayHello' -Input 'Tokyo'
$output += Invoke-DurableActivity -FunctionName 'SayHello' -Input 'Seattle'
$output += Invoke-DurableActivity -FunctionName 'SayHello' -Input 'London'

$output

@FunctionName("HelloCities")
public String helloCitiesOrchestrator(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    String result = "";
    result += ctx.callActivity("SayHello", "Tokyo", String.class).await() + ", ";
    result += ctx.callActivity("SayHello", "Seattle", String.class).await() + ", ";
    result += ctx.callActivity("SayHello", "London", String.class).await();
    return result;
}

När en aktivitetsfunktion schemaläggs, styr Durable Task Framework körningstillståndet för funktionen till en beständig lagringsserverdel (Azure Table Storage som standard). Det här tillståndet kallas orkestreringshistorik.

Historiktabell

I allmänhet gör Durable Task Framework följande vid varje kontrollpunkt:

1. Sparar körningshistorik i beständig lagring.
2. Anger meddelanden för funktioner som orkestratorn vill anropa.
3. Lägger till meddelanden för själva orkestratorn – till exempel varaktiga timermeddelanden.

När kontrollpunkten är klar kan orkestreringsfunktionen tas bort från minnet tills det finns mer arbete att göra.

När den här funktionen har slutförts ser historiken för den tidigare funktionen ut ungefär som i följande tabell i Azure Table Storage (förkortad i illustrationssyfte):

Några kommentarer om kolumnvärdena:

• PartitionKey: Innehåller instans-ID:t för orkestreringen.
• EventType: Representerar typen av händelse. Du hittar detaljerade beskrivningar av alla typer av historikhändelser här.
• Tidsstämpel: UTC-tidsstämpeln för historikhändelsen.
• Namn: Namnet på den funktion som anropades.
• Indata: JSON-formaterade indata för funktionen.
• Resultat: Funktionens utdata, dvs. dess returvärde.

Varje gång funktionen återupptas efter att ha väntat på att en uppgift ska slutföras kör Durable Task Framework orchestrator-funktionen från grunden igen. Vid varje omkörning läser den körningshistoriken för att avgöra om den aktuella asynkrona aktiviteten har slutförts. Om körningshistoriken visar att aktiviteten redan har slutförts spelar ramverket upp utdata för aktiviteten och går vidare till nästa uppgift. Den här processen fortsätter tills hela körningshistoriken har spelats upp igen. När den aktuella körningshistoriken har spelats upp igen har de lokala variablerna återställts till sina tidigare värden.

Funktioner och mönster

I nästa avsnitt beskrivs funktionerna och mönstren för orkestreringsfunktioner.

Sub-orkestreringar

Orchestrator-funktioner kan anropa aktivitetsfunktioner, men även andra orkestreringsfunktioner. Du kan till exempel skapa en större orkestrering av ett bibliotek med orkestreringsfunktioner. Eller så kan du köra flera instanser av en orchestrator-funktion parallellt.

Mer information och exempel finns i artikeln Underorkestreringar .

Varaktiga timers

Orkestreringar kan schemalägga varaktiga timers för att implementera fördröjningar eller för att konfigurera timeouthantering för asynkrona åtgärder. Använd varaktiga timers i orchestrator-funktioner i stället för språkbaserade "sömn"-API:er.

Mer information och exempel finns i artikeln Durable timers (Varaktiga timers ).

Externa händelser

Orchestrator-funktioner kan vänta tills externa händelser uppdaterar en orkestreringsinstans. Den här durable functions-funktionen är ofta användbar för att hantera en mänsklig interaktion eller andra externa återanrop.

Mer information och exempel finns i artikeln Externa händelser .

Felhantering

Orchestrator-funktioner kan använda felhanteringsfunktionerna i programmeringsspråket. Befintliga mönster som try/catch stöds i orkestreringskod.

Orkestreringsfunktioner kan också lägga till återförsöksprinciper till de aktivitets- eller underorkestreringsfunktioner som de anropar. Om en aktivitet eller underorkestreringsfunktion misslyckas med ett undantag kan den angivna återförsöksprincipen automatiskt fördröja och försöka köra körningen igen upp till ett angivet antal gånger.

Mer information och exempel finns i artikeln Felhantering .

Kritiska avsnitt (Durable Functions 2.x, för närvarande endast .NET)

Orkestreringsinstanser är enkeltrådade så det är inte nödvändigt att oroa sig för rasförhållanden inom en orkestrering. Tävlingsförhållanden är dock möjliga när orkestreringar interagerar med externa system. För att minimera konkurrensförhållanden när du interagerar med externa system kan orkestreringsfunktioner definiera kritiska avsnitt med hjälp av en LockAsync metod i .NET.

Följande exempelkod visar en orchestrator-funktion som definierar ett kritiskt avsnitt. Den anger det kritiska avsnittet med hjälp av LockAsync -metoden. Den här metoden kräver att du skickar en eller flera referenser till en varaktig entitet som durably hanterar låstillståndet. Endast en enda instans av orkestreringen kan köra koden i det kritiska avsnittet i taget.

[FunctionName("Synchronize")]
public static async Task Synchronize(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var lockId = new EntityId("LockEntity", "MyLockIdentifier");
    using (await context.LockAsync(lockId))
    {
        // critical section - only one orchestration can enter at a time
    }
}

LockAsync Hämtar de varaktiga låsen och returnerar ett IDisposable som avslutar det kritiska avsnittet när det tas bort. Det här IDisposable resultatet kan användas tillsammans med ett using block för att få en syntaktisk representation av det kritiska avsnittet. När en orkestreringsfunktion anger ett kritiskt avsnitt kan endast en instans köra kodblocket. Andra instanser som försöker komma in i det kritiska avsnittet blockeras tills den föregående instansen avslutar det kritiska avsnittet.

Den viktiga avsnittsfunktionen är också användbar för att samordna ändringar i varaktiga entiteter. Mer information om kritiska avsnitt finns i avsnittet Durable entiteter "Entitetssamordning" .

Anropa HTTP-slutpunkter (Durable Functions 2.x)

Orchestrator-funktioner har inte behörighet att göra I/O, enligt beskrivningen i begränsningar för orchestrator-funktionskod. Den vanliga lösningen för den här begränsningen är att omsluta all kod som behöver göra I/O i en aktivitetsfunktion. Orkestreringar som interagerar med externa system använder ofta aktivitetsfunktioner för att göra HTTP-anrop och returnera resultatet till orkestreringen.

[FunctionName("CheckSiteAvailable")]
public static async Task CheckSiteAvailable(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    Uri url = context.GetInput<Uri>();

    // Makes an HTTP GET request to the specified endpoint
    DurableHttpResponse response = 
        await context.CallHttpAsync(HttpMethod.Get, url);

    if ((int)response.StatusCode == 400)
    {
        // handling of error codes goes here
    }
}

[Function("CheckSiteAvailable")]
public static async Task CheckSiteAvailable(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    Uri url = context.GetInput<Uri>();

    // Makes an HTTP GET request to the specified endpoint
    DurableHttpResponse response =
        await context.CallHttpAsync(HttpMethod.Get, url);

    if ((int)response.StatusCode == 400)
    {
        // handling of error codes goes here
    }
}

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

module.exports = df.orchestrator(function*(context) {
    const url = context.df.getInput();
    var res = yield context.df.callHttp("GET", url);
    if (res.statusCode >= 400) {
        // handling of error codes goes here
    }
});

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

df.app.orchestration("checkSiteAvailable", function* (context) {
    const url = context.df.getInput();
    var res = yield context.df.callHttp({ method: "GET", url });
    if (res.statusCode >= 400) {
        // handling of error codes goes here
    }
});

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

def orchestrator_function(context: df.DurableOrchestrationContext):
    url = context.get_input()
    res = yield context.call_http('GET', url)
    if res.status_code >= 400:
        # handing of error code goes here

Förutom att stödja grundläggande mönster för begäran/svar stöder metoden automatisk hantering av vanliga asynkrona HTTP 202-avsökningsmönster och stöder även autentisering med externa tjänster med hanterade identiteter.

Mer information och detaljerade exempel finns i artikeln HTTP-funktioner .

Skicka flera parametrar

Det går inte att skicka flera parametrar direkt till en aktivitetsfunktion. Rekommendationen är att skicka in en matris med objekt eller sammansatta objekt.

[FunctionName("GetCourseRecommendations")]
public static async Task<object> RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string major = "ComputerScience";
    int universityYear = context.GetInput<int>();

    object courseRecommendations = await context.CallActivityAsync<object>(
        "CourseRecommendations",
        (major, universityYear));
    return courseRecommendations;
}

[FunctionName("CourseRecommendations")]
public static async Task<object> Mapper([ActivityTrigger] IDurableActivityContext inputs)
{
    // parse input for student's major and year in university
    (string Major, int UniversityYear) studentInfo = inputs.GetInput<(string, int)>();

    // retrieve and return course recommendations by major and university year
    return new
    {
        major = studentInfo.Major,
        universityYear = studentInfo.UniversityYear,
        recommendedCourses = new []
        {
            "Introduction to .NET Programming",
            "Introduction to Linux",
            "Becoming an Entrepreneur"
        }
    };
}

[Function("GetCourseRecommendations")]
public static async Task<object> RunOrchestrator(
    [OrchestrationTrigger] TaskOrchestrationContext context, int universityYear)
{
    string major = "ComputerScience";

    object courseRecommendations = await context.CallActivityAsync<object>(
        "CourseRecommendations",
        (major, universityYear));
    return courseRecommendations;
}

[FunctionName("CourseRecommendations")]
public static async Task<object> Mapper(
    [ActivityTrigger] (string Major, int UniversityYear) studentInfo, FunctionContext executionContext)
{
    // retrieve and return course recommendations by major and university year
    return new
    {
        major = studentInfo.Major,
        universityYear = studentInfo.UniversityYear,
        recommendedCourses = new []
        {
            "Introduction to .NET Programming",
            "Introduction to Linux",
            "Becoming an Entrepreneur"
        }
    };
}

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

module.exports = df.orchestrator(function*(context) {
    const location = {
        city: "Seattle",
        state: "WA"
    };
    const weather = yield context.df.callActivity("GetWeather", location);

    // ...
});

module.exports = async function (context, location) {
    const {city, state} = location; // destructure properties into variables

    // ...
};

const getWeatherActivityName = "getWeather";

df.app.orchestration("getWeatherOrchestrator", function* (context) {
    const location = {
        city: "Seattle",
        state: "WA",
    };
    const weather = yield context.df.callActivity(getWeatherActivityName, location);

    // ...
});

df.app.activity(getWeatherActivityName, async function (location) {
    const { city, state } = location; // destructure properties into variables

    // ...
});

from collections import namedtuple
import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    Location = namedtuple('Location', ['city', 'state'])
    location = Location(city='Seattle', state= 'WA')

    weather = yield context.call_activity("GetWeather", location)

    # ...

from collections import namedtuple

Location = namedtuple('Location', ['city', 'state'])

def main(location: Location) -> str:
    city, state = location
    return f"Hello {city}, {state}!"

param($Context)

$output = @()

$location = @{
    City = 'Seattle'
    State  = 'WA'
}

Invoke-ActivityFunction -FunctionName 'GetWeather' -Input $location

# ...

param($location)

"Hello $($location.City), $($location.State)!"
# ...

@FunctionName("GetWeatherOrchestrator")
public String getWeatherOrchestrator(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    var location = new Location();
    location.city = "Seattle";
    location.state = "WA";
    String weather = ctx.callActivity("GetWeather", location, String.class).await();
    return weather;
}

@FunctionName("GetWeather")
public String getWeather(@DurableActivityTrigger(name = "location") Location location) {
    if (location.city.equals("Seattle") && location.state.equals("WA")) {
        return "Cloudy";
    } else {
        return "Unknown";
    }
}

class Location {
    public String city;
    public String state;
}

Nästa steg