Funktionslänkning i Durable Functions – Hello-sekvensexempel

Artikel
10/01/2023

Funktionslänkning refererar till mönstret för att köra en sekvens med funktioner i en viss ordning. Ofta måste utdata från en funktion tillämpas på indata för en annan funktion. Den här artikeln beskriver den länkningssekvens som du skapar när du slutför snabbstarten för Durable Functions (C#, JavaScript, TypeScript, Python, PowerShell eller Java). Mer information om Durable Functions finns i Durable Functions översikt.

Förutsättningar

Anteckning

Version 4 av Node.js programmeringsmodell för Azure Functions är allmänt tillgänglig. Den nya v4-modellen är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Läs mer om skillnaderna mellan v3 och v4 i migreringsguiden.

I följande kodfragment anger JavaScript (PM4) programmeringsmodellen V4, den nya upplevelsen.

Funktionerna

Den här artikeln förklarar följande funktioner i exempelappen:

E1_HelloSequence: En orkestreringsfunktion som anropar E1_SayHello flera gånger i en sekvens. Den lagrar utdata från anropen E1_SayHello och registrerar resultatet.
E1_SayHello: En aktivitetsfunktion som förbereder en sträng med "Hello".
HttpStart: En HTTP-utlöst varaktig klientfunktion som startar en instans av orkestreraren.

E1_HelloSequence orchestrator-funktion

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

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

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

Alla C#-orkestreringsfunktioner måste ha en parameter av typen DurableOrchestrationContext, som finns i Microsoft.Azure.WebJobs.Extensions.DurableTask sammansättningen. Med det här kontextobjektet kan du anropa andra aktivitetsfunktioner och skicka indataparametrar med hjälp av dess CallActivityAsync -metod.

Koden anropar E1_SayHello tre gånger i följd med olika parametervärden. Returvärdet för varje anrop läggs till i outputs listan, som returneras i slutet av funktionen.

function.json

Om du använder Visual Studio Code eller Azure Portal för utveckling, här är innehållet i filen function.json för orchestrator-funktionen. De flesta orchestrator function.json-filer ser nästan exakt ut så här.

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

Det viktiga är bindningstypen orchestrationTrigger . Alla orkestreringsfunktioner måste använda den här utlösartypen.

Varning

Om du vill följa regeln "ingen I/O" för orchestrator-funktioner ska du inte använda några indata- eller utdatabindningar när du använder utlösarbindningen orchestrationTrigger . Om andra indata- eller utdatabindningar behövs bör de i stället användas i kontexten för activityTrigger funktioner, som anropas av orkestreraren. Mer information finns i artikeln om begränsningar för orchestrator-funktionskod .

index.js

Här är orkestreringsfunktionen:

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

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

    return output;
});

Alla JavaScript-orkestreringsfunktioner måste innehålla modulendurable-functions . Det är ett bibliotek som gör att du kan skriva Durable Functions i JavaScript. Det finns tre viktiga skillnader mellan en orkestreringsfunktion och andra JavaScript-funktioner:

Orchestrator-funktionen är en generatorfunktion.
Funktionen omsluts av ett anrop till modulens durable-functionsorchestrator -metod (här df).
Funktionen måste vara synkron. Eftersom metoden "orchestrator" hanterar det sista anropet till "context.done" ska funktionen helt enkelt "returnera".

Objektet context innehåller ett df varaktigt orkestreringskontextobjekt som gör att du kan anropa andra aktivitetsfunktioner och skicka indataparametrar med hjälp av dess callActivity -metod. Koden anropar E1_SayHello tre gånger i följd med olika parametervärden, med hjälp av yield för att ange att körningen ska vänta på att asynkrona aktivitetsfunktionsanrop returneras. Returvärdet för varje anrop läggs till i matrisen outputs , som returneras i slutet av funktionen.

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

const helloActivityName = "sayHello";

df.app.orchestration("helloSequence", function* (context) {
    context.log("Starting chain sample");

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

    return output;
});

Alla JavaScript-orkestreringsfunktioner måste innehålla modulendurable-functions . Med den här modulen kan du skriva Durable Functions i JavaScript. Om du vill använda V4-nodprogrammeringsmodellen måste du installera förhandsversionen v3.x av durable-functions.

Det finns två betydande skillnader mellan en orkestreringsfunktion och andra JavaScript-funktioner:

Orchestrator-funktionen är en generatorfunktion.
Funktionen måste vara synkron. Funktionen bör helt enkelt "returnera".

Objektet context innehåller ett df varaktigt orkestreringskontextobjekt som gör att du kan anropa andra aktivitetsfunktioner och skicka indataparametrar med hjälp av dess callActivity -metod. Koden anropar sayHello tre gånger i följd med olika parametervärden, med hjälp av yield för att ange att körningen ska vänta på att asynkrona aktivitetsfunktionsanrop returneras. Returvärdet för varje anrop läggs till i matrisen outputs , som returneras i slutet av funktionen.

Anteckning

Python-Durable Functions är endast tillgängliga för Functions 3.0-körning.

function.json

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

Det viktiga är bindningstypen orchestrationTrigger . Alla orkestreringsfunktioner måste använda den här utlösartypen.

Varning

init.py

Här är orkestreringsfunktionen:

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


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

main = df.Orchestrator.create(orchestrator_function)

Alla Python-orkestreringsfunktioner måste innehålla durable-functions paketet. Det är ett bibliotek som gör att du kan skriva Durable Functions i Python. Det finns två betydande skillnader mellan en orkestreringsfunktion och andra Python-funktioner:

Orchestrator-funktionen är en generatorfunktion.
Filen bör registrera orchestrator-funktionen som orkestrerare genom att ange main = df.Orchestrator.create(<orchestrator function name>) i slutet av filen. På så sätt kan du skilja den från andra hjälpfunktioner som deklarerats i filen.

Med context objektet kan du anropa andra aktivitetsfunktioner och skicka indataparametrar med hjälp av dess call_activity -metod. Koden anropar E1_SayHello tre gånger i följd med olika parametervärden, med hjälp av yield för att ange att körningen ska vänta på att asynkrona aktivitetsfunktionsanrop returneras. Returvärdet för varje anrop returneras i slutet av funktionen.

E1_SayHello aktivitetsfunktion

[FunctionName("E1_SayHello")]
public static string SayHello([ActivityTrigger] IDurableActivityContext context)
{
    string name = context.GetInput<string>();
    return $"Hello {name}!";
}

Aktiviteter använder attributet ActivityTrigger . Använd som tillhandahålls IDurableActivityContext för att utföra aktivitetsrelaterade åtgärder, till exempel åtkomst till indatavärdet med hjälp av GetInput<T>.

Implementeringen av E1_SayHello är en relativt trivial strängformateringsåtgärd.

I stället för att binda till en IDurableActivityContextkan du binda direkt till den typ som skickas till aktivitetsfunktionen. Exempel:

[FunctionName("E1_SayHello_DirectInput")]
public static string SayHelloDirectInput([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

E1_SayHello/function.json

Filen function.json för aktivitetsfunktionen E1_SayHello liknar E1_HelloSequence den för förutom att den använder en activityTrigger bindningstyp i stället för en orchestrationTrigger bindningstyp.

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

Anteckning

Alla aktivitetsfunktioner som anropas av en orkestreringsfunktion måste använda bindningen activityTrigger .

Implementeringen av E1_SayHello är en relativt trivial strängformateringsåtgärd.

E1_SayHello/index.js

module.exports = function (context) {
    context.done(null, `Hello ${context.bindings.name}!`);
};

Till skillnad från orkestreringsfunktionen behöver en aktivitetsfunktion ingen särskild konfiguration. Indata som skickas till den av orchestrator-funktionen finns på objektet under namnet på context.bindings bindningen activityTrigger – i det här fallet context.bindings.name. Bindningsnamnet kan anges som en parameter för den exporterade funktionen och nås direkt, vilket är vad exempelkoden gör.

Implementeringen av sayHello är en relativt trivial strängformateringsåtgärd.

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

const helloActivityName = "sayHello";

df.app.activity(helloActivityName, {
    handler: function (input) {
        return `Hello ${input}`;
    },
});

Till skillnad från orkestreringsfunktionen behöver en aktivitetsfunktion ingen särskild konfiguration. Indata som skickas till den av orchestrator-funktionen är det första argumentet till funktionen. Det andra argumentet är anropskontexten, som inte används i det här exemplet.

E1_SayHello/function.json

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

Anteckning

Alla aktivitetsfunktioner som anropas av en orkestreringsfunktion måste använda bindningen activityTrigger .

Implementeringen av E1_SayHello är en relativt trivial strängformateringsåtgärd.

E1_SayHello/init.py

def main(name: str) -> str:
    return f"Hello {name}!"

Till skillnad från orchestrator-funktionen behöver en aktivitetsfunktion ingen särskild konfiguration. Indata som skickas till den av orchestrator-funktionen är direkt åtkomliga som parametern för funktionen.

HttpStart-klientfunktion

Du kan starta en instans av orchestrator-funktionen med hjälp av en klientfunktion. Du kommer att använda den HttpStart HTTP-utlösta funktionen för att starta instanser av E1_HelloSequence.

public static class HttpStart
{
    [FunctionName("HttpStart")]
    public static async Task<HttpResponseMessage> Run(
        [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}")] HttpRequestMessage req,
        [DurableClient] IDurableClient starter,
        string functionName,
        ILogger log)
    {
        // Function input comes from the request content.
        object eventData = await req.Content.ReadAsAsync<object>();
        string instanceId = await starter.StartNewAsync(functionName, eventData);

        log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

        return starter.CreateCheckStatusResponse(req, instanceId);
    }
}

Om du vill interagera med orkestrerare måste funktionen innehålla en DurableClient indatabindning. Du använder klienten för att starta en orkestrering. Det kan också hjälpa dig att returnera ett HTTP-svar som innehåller URL:er för att kontrollera status för den nya orkestreringen.

HttpStart/function.json

{
    "bindings": [
      {
        "authLevel": "anonymous",
        "name": "req",
        "type": "httpTrigger",
        "direction": "in",
        "route": "orchestrators/{functionName}",
        "methods": ["post"]
      },
      {
        "name": "$return",
        "type": "http",
        "direction": "out"
      },
      {
        "name": "starter",
        "type": "orchestrationClient",
        "direction": "in"
      }
    ],
    "disabled": false
  }

Om du vill interagera med orkestrerare måste funktionen innehålla en durableClient indatabindning.

HttpStart/index.js

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

module.exports = async function (context, req) {
    const client = df.getClient(context);
    const instanceId = await client.startNew(req.params.functionName, undefined, req.body);

    context.log(`Started orchestration with ID = '${instanceId}'.`);

    return client.createCheckStatusResponse(context.bindingData.req, instanceId);
};

Använd df.getClient för att hämta ett DurableOrchestrationClient -objekt. Du använder klienten för att starta en orkestrering. Det kan också hjälpa dig att returnera ett HTTP-svar som innehåller URL:er för att kontrollera status för den nya orkestreringen.

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

app.http("httpStart", {
    route: "orchestrators/{orchestratorName}",
    extraInputs: [df.input.durableClient()],
    handler: async (request, context) => {
        const client = df.getClient(context);
        const body = await request.json();
        const instanceId = await client.startNew(request.params.orchestratorName, { input: body });

        context.log(`Started orchestration with ID = '${instanceId}'.`);

        return client.createCheckStatusResponse(request, instanceId);
    },
});

För att hantera och interagera med orkestrerare behöver funktionen en durableClient indatabindning. Den här bindningen måste anges i extraInputs argumentet när funktionen registreras. Du durableClient kan hämta indata genom att anropa df.input.durableClient().

Använd df.getClient för att hämta ett DurableClient -objekt. Du använder klienten för att starta en orkestrering. Det kan också hjälpa dig att returnera ett HTTP-svar som innehåller URL:er för att kontrollera status för den nya orkestreringen.

HttpStart/function.json

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{functionName}",
      "methods": [
        "post",
        "get"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

Om du vill interagera med orkestrerare måste funktionen innehålla en durableClient indatabindning.

HttpStart/init.py

import logging

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


async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    instance_id = await client.start_new(req.route_params["functionName"], None, None)

    logging.info(f"Started orchestration with ID = '{instance_id}'.")

    return client.create_check_status_response(req, instance_id)

DurableOrchestrationClient Använd konstruktorn för att hämta en Durable Functions-klient. Du använder klienten för att starta en orkestrering. Det kan också hjälpa dig att returnera ett HTTP-svar som innehåller URL:er för att kontrollera status för den nya orkestreringen.

Kör exemplet

Skicka följande HTTP POST-begäran till HttpStart funktionen för att köra E1_HelloSequence orkestreringen.

POST http://{host}/orchestrators/E1_HelloSequence

Anteckning

Det tidigare HTTP-kodfragmentet förutsätter att det finns en post i host.json filen som tar bort standardprefixet api/ från alla URL:er för HTTP-utlösarfunktioner. Du hittar koden för den här konfigurationen host.json i filen i exemplen.

Om du till exempel kör exemplet i en funktionsapp med namnet "myfunctionapp" ersätter du "{host}" med "myfunctionapp.azurewebsites.net".

Resultatet är ett HTTP 202-svar, så här (trimmat för korthet):

HTTP/1.1 202 Accepted
Content-Length: 719
Content-Type: application/json; charset=utf-8
Location: http://{host}/runtime/webhooks/durabletask/instances/96924899c16d43b08a536de376ac786b?taskHub=DurableFunctionsHub&connection=Storage&code={systemKey}

(...trimmed...)

Nu köas orkestreringen och börjar köras omedelbart. URL:en i Location rubriken kan användas för att kontrollera körningens status.

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

Resultatet är orkestreringens status. Den körs och slutförs snabbt, så du ser den i tillståndet Slutfört med ett svar som ser ut så här (trimmat för korthet):

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

{"runtimeStatus":"Completed","input":null,"output":["Hello Tokyo!","Hello Seattle!","Hello London!"],"createdTime":"2017-06-29T05:24:57Z","lastUpdatedTime":"2017-06-29T05:24:59Z"}

Som du ser är instansen runtimeStatusSlutförd och output innehåller det JSON-serialiserade resultatet av orchestrator-funktionskörningen.

Anteckning

Du kan implementera liknande startlogik för andra utlösartyper, till exempel queueTrigger, eventHubTriggereller timerTrigger.

Titta på funktionskörningsloggarna. Funktionen E1_HelloSequence startades och slutfördes flera gånger på grund av återuppspelningsbeteendet som beskrivs i avsnittet om orkestreringstillförlitlighet . Å andra sidan fanns det bara tre körningar av E1_SayHello eftersom dessa funktionskörningar inte spelas upp igen.

Nästa steg

Det här exemplet har demonstrerat en enkel funktionslänkningsorkestrering. Nästa exempel visar hur du implementerar fan-out/fan-in-mönstret.

Kör exemplet Fan-out/fan-in

Share via

Funktionslänkning i Durable Functions – Hello-sekvensexempel

Förutsättningar

Funktionerna

E1_HelloSequence orchestrator-funktion

function.json

index.js

function.json

init.py

E1_SayHello aktivitetsfunktion

E1_SayHello/function.json

E1_SayHello/index.js

E1_SayHello/function.json

E1_SayHello/init.py

HttpStart-klientfunktion

HttpStart/function.json

HttpStart/index.js

HttpStart/function.json

HttpStart/init.py

Kör exemplet

Nästa steg

Ytterligare resurser