Řetězení funkcí v Durable Functions – ukázka sekvence Hello

Článek
05/23/2023

Řetězení funkcí označuje vzor provádění posloupnosti funkcí v určitém pořadí. Výstup jedné funkce je často potřeba použít na vstup jiné funkce. Tento článek popisuje posloupnost řetězení, kterou vytvoříte při dokončení Durable Functions rychlého startu (C#, JavaScript, TypeScript, Python, PowerShell nebo Java). Další informace o Durable Functions najdete v přehledu Durable Functions.

Požadavky

Poznámka

Verze 4 programovacího modelu Node.js pro Azure Functions je obecně dostupná. Nový model v4 je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další informace o rozdílech mezi verzemi v3 a v4 najdete v průvodci migrací.

V následujících fragmentech kódu označuje JavaScript (PM4) programovací model V4, nové prostředí.

Funkce

Tento článek vysvětluje následující funkce v ukázkové aplikaci:

E1_HelloSequence: Funkce orchestrátoru , která volá E1_SayHello vícekrát v sekvenci. Ukládá výstupy z E1_SayHello volání a zaznamenává výsledky.
E1_SayHello: Funkce aktivity , která předsadí řetězec s "Hello".
HttpStart: Funkce odolného klienta aktivovaná protokolem HTTP, která spouští instanci orchestrátoru.

E1_HelloSequence funkce orchestrátoru

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

Všechny funkce orchestrace jazyka C# musí mít parametr typu DurableOrchestrationContext, který existuje v Microsoft.Azure.WebJobs.Extensions.DurableTask sestavení. Tento kontextový objekt umožňuje volat další funkce aktivit a předávat vstupní parametry pomocí své CallActivityAsync metody.

Kód volá E1_SayHello třikrát po sobě s různými hodnotami parametrů. Návratová hodnota každého volání se přidá do outputs seznamu, který se vrátí na konci funkce.

function.json

Pokud pro vývoj používáte Visual Studio Code nebo Azure Portal, tady je obsah souboru function.json pro funkci orchestrátoru. Většina souborů orchestrator function.json vypadá téměř přesně takto.

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

Důležité je typ vazby orchestrationTrigger . Tento typ triggeru musí používat všechny funkce orchestrátoru.

Upozornění

Pokud chcete dodržovat pravidlo "žádné vstupně-výstupní operace" funkcí orchestrátoru, nepoužívejte při použití orchestrationTrigger aktivační vazby žádné vstupní ani výstupní vazby. Pokud jsou potřeba jiné vstupní nebo výstupní vazby, měly by se místo toho používat v kontextu activityTrigger funkcí, které jsou volány orchestrátorem. Další informace najdete v článku Omezení kódu funkce orchestrátoru .

index.js

Tady je funkce orchestrátoru:

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

Všechny funkce orchestrace JavaScriptu musí obsahovat moduldurable-functions. Je to knihovna, která umožňuje psát Durable Functions v JavaScriptu. Existují tři významné rozdíly mezi funkcí orchestrátoru a dalšími funkcemi JavaScriptu:

Funkce orchestrátoru je funkce generátoru.
Funkce je zabalená do volání durable-functions metody modulu orchestrator (zde df).
Funkce musí být synchronní. Vzhledem k tomu, že metoda "orchestrator" zpracovává konečné volání "context.done", měla by funkce jednoduše "return".

Objekt context obsahuje df trvalý objekt kontextu orchestrace, který umožňuje volat další funkce aktivity a předávat vstupní parametry pomocí své callActivity metody. Kód volá E1_SayHello třikrát sekvenci s různými hodnotami parametrů, pomocí yield které indikuje, že spuštění by mělo počkat na vrácení volání funkce asynchronní aktivity. Návratová hodnota každého volání se přidá do outputs pole, které se vrátí na konci funkce.

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

Všechny funkce orchestrace JavaScriptu musí obsahovat moduldurable-functions. Tento modul umožňuje psát Durable Functions v JavaScriptu. Pokud chcete používat programovací model uzlů V4, musíte nainstalovat verzi Preview v3.x nástroje durable-functions.

Mezi funkcí orchestrátoru a dalšími funkcemi JavaScriptu existují dva významné rozdíly:

Funkce orchestrátoru je funkce generátoru.
Funkce musí být synchronní. Funkce by měla jednoduše "vrátit".

Objekt context obsahuje df trvalý objekt kontextu orchestrace, který umožňuje volat další funkce aktivity a předávat vstupní parametry pomocí své callActivity metody. Kód volá sayHello třikrát sekvenci s různými hodnotami parametrů, pomocí yield které indikuje, že spuštění by mělo počkat na vrácení volání funkce asynchronní aktivity. Návratová hodnota každého volání se přidá do outputs pole, které se vrátí na konci funkce.

Poznámka

Durable Functions Pythonu jsou k dispozici pouze pro modul runtime Functions 3.0.

function.json

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

Důležité je typ vazby orchestrationTrigger . Tento typ triggeru musí používat všechny funkce orchestrátoru.

Upozornění

init.py

Tady je funkce orchestrátoru:

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)

Všechny funkce orchestrace Pythonu durable-functionsmusí obsahovat balíček. Je to knihovna, která umožňuje psát Durable Functions v Pythonu. Mezi funkcí orchestrátoru a dalšími funkcemi Pythonu existují dva významné rozdíly:

Funkce orchestrátoru je funkce generátoru.
Soubor by měl zaregistrovat funkci orchestrátoru jako orchestrátor tak, že na konci souboru uvedemain = df.Orchestrator.create(<orchestrator function name>). To pomáhá odlišit ho od ostatních pomocných funkcí deklarovaných v souboru.

Objekt context umožňuje volat další funkce aktivit a předávat vstupní parametry pomocí své call_activity metody. Kód volá E1_SayHello třikrát sekvenci s různými hodnotami parametrů, pomocí yield které indikuje, že spuštění by mělo počkat na vrácení volání funkce asynchronní aktivity. Návratová hodnota každého volání se vrátí na konci funkce.

E1_SayHello funkce aktivity

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

Aktivity používají ActivityTrigger atribut . K provádění akcí souvisejících s aktivitami, jako je například přístup ke vstupní hodnotě pomocí GetInput<T>nástroje , použijte zadaný parametr IDurableActivityContext .

Implementace E1_SayHello je relativně triviální operace formátování řetězců.

Místo vazby na IDurableActivityContext, můžete vytvořit vazbu přímo na typ, který je předán do funkce aktivity. Příklad:

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

E1_SayHello/function.json

Soubor function.json pro funkci E1_SayHello aktivity je podobný souboru s tím rozdílem E1_HelloSequenceactivityTrigger , že místo typu vazby používá typ vazby orchestrationTrigger .

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

Poznámka

Všechny funkce aktivit volané orchestrační funkcí musí používat activityTrigger vazbu.

Implementace E1_SayHello je relativně triviální operace formátování řetězců.

E1_SayHello/index.js

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

Na rozdíl od funkce orchestrace nevyžaduje funkce aktivity žádné zvláštní nastavení. Vstup předaný funkci orchestrátoru se nachází na objektu context.bindings pod názvem activityTrigger vazby – v tomto případě context.bindings.name. Název vazby je možné nastavit jako parametr exportované funkce a přistupovat k ho přímo, což je to, co vzorový kód dělá.

Implementace sayHello je relativně triviální operace formátování řetězců.

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

const helloActivityName = "sayHello";

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

Na rozdíl od funkce orchestrace nevyžaduje funkce aktivity žádné zvláštní nastavení. Vstup předaný funkci orchestrátoru je prvním argumentem funkce. Druhým argumentem je kontext vyvolání, který se v tomto příkladu nepoužívá.

E1_SayHello/function.json

Soubor function.json pro funkci E1_SayHello aktivity je podobný souboru s tím rozdílem E1_HelloSequenceactivityTrigger , že místo typu vazby používá typ vazby orchestrationTrigger .

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

Poznámka

Všechny funkce aktivit volané orchestrační funkcí musí používat activityTrigger vazbu.

Implementace E1_SayHello je relativně triviální operace formátování řetězců.

E1_SayHello/init.py

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

Na rozdíl od funkce orchestrátoru nevyžaduje funkce aktivity žádné zvláštní nastavení. Vstup předaný funkci orchestrátoru je přímo přístupný jako parametr funkce.

Funkce klienta HttpStart

Instanci funkce orchestrátoru můžete spustit pomocí klientské funkce. Ke spuštění instancí použijete HttpStart funkci aktivovanou protokolem E1_HelloSequenceHTTP.

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

K interakci s orchestrátory musí funkce obsahovat DurableClient vstupní vazbu. Pomocí klienta spustíte orchestraci. Může vám také pomoct vrátit odpověď HTTP obsahující adresy URL pro kontrolu stavu nové orchestrace.

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
  }

K interakci s orchestrátory musí funkce obsahovat durableClient vstupní vazbu.

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

Slouží df.getClient k získání objektu DurableOrchestrationClient . Pomocí klienta spustíte orchestraci. Může vám také pomoct vrátit odpověď HTTP obsahující adresy URL pro kontrolu stavu nové orchestrace.

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

Ke správě orchestrátorů a interakci s nimi potřebuje durableClient funkce vstupní vazbu. Tuto vazbu je potřeba zadat v argumentu extraInputs při registraci funkce. Vstup durableClient lze získat voláním df.input.durableClient()příkazu .

Slouží df.getClient k získání objektu DurableClient . Pomocí klienta spustíte orchestraci. Může vám také pomoct vrátit odpověď HTTP obsahující adresy URL pro kontrolu stavu nové orchestrace.

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"
    }
  ]
}

K interakci s orchestrátory musí funkce obsahovat durableClient vstupní vazbu.

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)

Pomocí konstruktoru DurableOrchestrationClient získejte klienta Durable Functions. Pomocí klienta spustíte orchestraci. Může vám také pomoct vrátit odpověď HTTP obsahující adresy URL pro kontrolu stavu nové orchestrace.

Spuštění ukázky

Pokud chcete orchestraci spustit E1_HelloSequence , odešlete do HttpStart funkce následující požadavek HTTP POST.

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

Poznámka

Předchozí fragment kódu HTTP předpokládá, že v host.json souboru je položka, která ze všech adres URL aktivačních funkcí HTTP odebere výchozí api/ předponu. Značky pro tuto konfiguraci najdete v host.json souboru v ukázkách.

Pokud například spouštíte ukázku v aplikaci funkcí s názvem "myfunctionapp", nahraďte {host} názvem "myfunctionapp.azurewebsites.net".

Výsledkem je odpověď HTTP 202, jako je tato (zkrácená pro stručnost):

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...)

V tomto okamžiku je orchestrace zařazena do fronty a začne se okamžitě spouštět. Adresu URL v hlavičce Location můžete použít ke kontrole stavu spuštění.

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

Výsledkem je stav orchestrace. Rychle se spustí a dokončí, takže se zobrazí ve stavu Dokončeno s odpovědí, která vypadá takto (zkráceně pro stručnost):

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

Jak vidíte, runtimeStatus instance je Dokončeno a output obsahuje serializovaný výsledek spuštění funkce orchestrátoru JSON.

Poznámka

Podobnou počáteční logiku můžete implementovat pro jiné typy triggerů, jako jsou queueTrigger, eventHubTriggernebo timerTrigger.

Podívejte se na protokoly provádění funkcí. Funkce se spustila E1_HelloSequence a dokončila několikrát kvůli chování přehrávání popsanému v tématu o spolehlivosti orchestrace . Na druhou stranu došlo pouze ke třem spuštěním E1_SayHello , protože tato spuštění funkcí se nepřehrávají.

Další kroky

Tato ukázka demonstrovala jednoduchou orchestraci zřetězení funkcí. Další ukázka ukazuje, jak implementovat model fan-out/fan-in.

Spuštění ukázky fan-out/fan-in

Řetězení funkcí v Durable Functions – ukázka sekvence Hello

Požadavky

Funkce

E1_HelloSequence funkce orchestrátoru

E1_SayHello funkce aktivity

Funkce klienta HttpStart

Spuštění ukázky

Další kroky

Další materiály