Functiekoppeling in Durable Functions - Hello-reeksvoorbeeld

Artikel
07/27/2024

Functiekoppeling verwijst naar het patroon van het uitvoeren van een reeks functies in een bepaalde volgorde. Vaak moet de uitvoer van een functie worden toegepast op de invoer van een andere functie. In dit artikel wordt de ketenvolgorde beschreven die u maakt wanneer u de QuickStart voor Durable Functions (C#, JavaScript, TypeScript, Python, PowerShell of Java) voltooit. Zie het overzicht van Durable Functions voor meer informatie over Durable Functions.

Vereisten

Notitie

Versie 4 van het Node.js programmeermodel voor Azure Functions is algemeen beschikbaar. Het nieuwe v4-model is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Meer informatie over de verschillen tussen v3 en v4 in de migratiehandleiding.

In de volgende codefragmenten geeft JavaScript (PM4) het programmeermodel V4 aan, de nieuwe ervaring.

De functies

In dit artikel worden de volgende functies in de voorbeeld-app uitgelegd:

E1_HelloSequence: Een orchestratorfunctie die meerdere keren in een reeks aanroept E1_SayHello . Hiermee worden de uitvoer van de E1_SayHello aanroepen opgeslagen en worden de resultaten vastgelegd.
E1_SayHello: Een activiteitsfunctie die een tekenreeks voorbereidt met 'Hallo'.
HttpStart: Een door HTTP geactiveerde durable client-functie waarmee een exemplaar van de orchestrator wordt gestart.

E1_HelloSequence orchestratorfunctie

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

Alle C#-indelingsfuncties moeten een parameter van het type DurableOrchestrationContexthebben, die aanwezig is in de Microsoft.Azure.WebJobs.Extensions.DurableTask assembly. Met dit contextobject kunt u andere activiteitsfuncties aanroepen en invoerparameters doorgeven met behulp van de CallActivityAsync methode.

De code roept E1_SayHello drie keer op volgorde aan met verschillende parameterwaarden. De retourwaarde van elke aanroep wordt toegevoegd aan de outputs lijst, die aan het einde van de functie wordt geretourneerd.

function.json

Als u Visual Studio Code of Azure Portal gebruikt voor ontwikkeling, vindt u hier de inhoud van het function.json-bestand voor de orchestratorfunctie. De meeste orchestrator-function.json bestanden zien er bijna precies zo uit.

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

Het belangrijkste is het orchestrationTrigger bindingstype. Alle orchestratorfuncties moeten dit triggertype gebruiken.

Waarschuwing

Als u zich wilt houden aan de regel 'geen I/O' van orchestratorfuncties, gebruikt u geen invoer- of uitvoerbindingen wanneer u de orchestrationTrigger triggerbinding gebruikt. Als er andere invoer- of uitvoerbindingen nodig zijn, moeten ze in plaats daarvan worden gebruikt in de context van activityTrigger functies, die worden aangeroepen door de orchestrator. Zie het artikel codebeperkingen voor orchestratorfuncties voor meer informatie.

index.js

Dit is de orchestratorfunctie:

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

Alle JavaScript-indelingsfuncties moeten de durable-functions module bevatten. Het is een bibliotheek waarmee u Durable Functions kunt schrijven in JavaScript. Er zijn drie belangrijke verschillen tussen een orchestratorfunctie en andere JavaScript-functies:

De orchestratorfunctie is een generatorfunctie.
De functie wordt verpakt in een aanroep van de methode van orchestrator de durable-functions module (hierdf).
De functie moet synchroon zijn. Omdat de methode orchestrator de laatste aanroep naar context.done afhandelt, moet de functie gewoon 'return' zijn.

Het context object bevat een df duurzaam indelingscontextobject waarmee u andere activiteitsfuncties kunt aanroepen en invoerparameters kunt doorgeven met behulp van de callActivity methode. De code roept E1_SayHello drie keer in volgorde aan met verschillende parameterwaarden, waarbij yield wordt aangegeven dat de uitvoering moet wachten op de aanroepen van de asynchrone activiteitsfunctie worden geretourneerd. De retourwaarde van elke aanroep wordt toegevoegd aan de outputs matrix, die aan het einde van de functie wordt geretourneerd.

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

Alle JavaScript-indelingsfuncties moeten de durable-functions module bevatten. Met deze module kunt u Durable Functions schrijven in JavaScript. Als u het programmeermodel voor V4-knooppunten wilt gebruiken, moet u de preview-versie v3.x van durable-functions.

Er zijn twee belangrijke verschillen tussen een orchestratorfunctie en andere JavaScript-functies:

De orchestratorfunctie is een generatorfunctie.
De functie moet synchroon zijn. De functie moet gewoon 'return' zijn.

Het context object bevat een df duurzaam indelingscontextobject waarmee u andere activiteitsfuncties kunt aanroepen en invoerparameters kunt doorgeven met behulp van de callActivity methode. De code roept sayHello drie keer in volgorde aan met verschillende parameterwaarden, waarbij yield wordt aangegeven dat de uitvoering moet wachten op de aanroepen van de asynchrone activiteitsfunctie worden geretourneerd. De retourwaarde van elke aanroep wordt toegevoegd aan de outputs matrix, die aan het einde van de functie wordt geretourneerd.

Notitie

Python Durable Functions is alleen beschikbaar voor de Functions 3.0-runtime.

function.json

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

Het belangrijkste is het orchestrationTrigger bindingstype. Alle orchestratorfuncties moeten dit triggertype gebruiken.

Waarschuwing

init.py

Dit is de orchestratorfunctie:

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)

Alle Python-indelingsfuncties moeten het durable-functions pakket bevatten. Het is een bibliotheek waarmee u Durable Functions kunt schrijven in Python. Er zijn twee belangrijke verschillen tussen een orchestratorfunctie en andere Python-functies:

De orchestratorfunctie is een generatorfunctie.
Het bestand moet de orchestratorfunctie registreren als orchestrator door aan het einde van het bestand aan te geven main = df.Orchestrator.create(<orchestrator function name>) . Hiermee kunt u onderscheid maken tussen andere, helperfuncties en functies die in het bestand zijn gedeclareerd.

Met context het object kunt u andere activiteitsfuncties aanroepen en invoerparameters doorgeven met behulp van de call_activity methode. De code roept E1_SayHello drie keer in volgorde aan met verschillende parameterwaarden, waarbij yield wordt aangegeven dat de uitvoering moet wachten op de aanroepen van de asynchrone activiteitsfunctie worden geretourneerd. De retourwaarde van elke aanroep wordt aan het einde van de functie geretourneerd.

E1_SayHello activiteitsfunctie

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

Activiteiten gebruiken het ActivityTrigger kenmerk. Gebruik de opgegeven IDurableActivityContext opdracht om activiteitengerelateerde acties uit te voeren, zoals toegang tot de invoerwaarde met behulp van GetInput<T>.

De implementatie van E1_SayHello is een relatief triviale tekenreeksopmaakbewerking.

In plaats van een binding met een IDurableActivityContext, kunt u rechtstreeks verbinden met het type dat wordt doorgegeven aan de activiteitsfunctie. Voorbeeld:

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

E1_SayHello/function.json

Het function.json-bestand voor de activiteitsfunctie E1_SayHello is vergelijkbaar met E1_HelloSequence het bestand, behalve dat het een activityTrigger bindingstype gebruikt in plaats van een orchestrationTrigger bindingstype.

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

Notitie

Alle activiteitsfuncties die worden aangeroepen door een indelingsfunctie, moeten de activityTrigger binding gebruiken.

De implementatie van E1_SayHello is een relatief triviale tekenreeksopmaakbewerking.

E1_SayHello/index.js

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

In tegenstelling tot de indelingsfunctie heeft een activiteitsfunctie geen speciale installatie nodig. De invoer die door de orchestratorfunctie wordt doorgegeven, bevindt zich in het context.bindings object onder de naam van de activityTrigger binding, context.bindings.namein dit geval. De bindingsnaam kan worden ingesteld als een parameter van de geëxporteerde functie en rechtstreeks worden geopend. Dit is wat de voorbeeldcode doet.

De implementatie van sayHello is een relatief triviale tekenreeksopmaakbewerking.

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

const helloActivityName = "sayHello";

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

In tegenstelling tot de indelingsfunctie heeft een activiteitsfunctie geen speciale installatie nodig. De invoer die door de orchestratorfunctie wordt doorgegeven, is het eerste argument voor de functie. Het tweede argument is de aanroepcontext, die in dit voorbeeld niet wordt gebruikt.

E1_SayHello/function.json

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

Notitie

Alle activiteitsfuncties die worden aangeroepen door een indelingsfunctie, moeten de activityTrigger binding gebruiken.

De implementatie van E1_SayHello is een relatief triviale tekenreeksopmaakbewerking.

E1_SayHello/init.py

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

In tegenstelling tot de orchestratorfunctie heeft een activiteitsfunctie geen speciale installatie nodig. De invoer die door de orchestratorfunctie wordt doorgegeven, is rechtstreeks toegankelijk als parameter voor de functie.

HttpStart-clientfunctie

U kunt een exemplaar van orchestratorfunctie starten met behulp van een clientfunctie. U gebruikt de HttpStart door HTTP geactiveerde functie om exemplaren van 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);
    }
}

Als u wilt communiceren met orchestrators, moet de functie een DurableClient invoerbinding bevatten. U gebruikt de client om een indeling te starten. U kunt ook een HTTP-antwoord met URL's retourneren om de status van de nieuwe indeling te controleren.

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
  }

Als u wilt communiceren met orchestrators, moet de functie een durableClient invoerbinding bevatten.

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

Gebruik df.getClient dit om een DurableOrchestrationClient object te verkrijgen. U gebruikt de client om een indeling te starten. U kunt ook een HTTP-antwoord met URL's retourneren om de status van de nieuwe indeling te controleren.

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

Voor het beheren en communiceren met orchestrators heeft de functie een durableClient invoerbinding nodig. Deze binding moet worden opgegeven in het argument bij het extraInputs registreren van de functie. Een durableClient invoer kan worden verkregen door aan te roepen df.input.durableClient().

Gebruik df.getClient dit om een DurableClient object te verkrijgen. U gebruikt de client om een indeling te starten. U kunt ook een HTTP-antwoord met URL's retourneren om de status van de nieuwe indeling te controleren.

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

Als u wilt communiceren met orchestrators, moet de functie een durableClient invoerbinding bevatten.

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)

Gebruik de DurableOrchestrationClient constructor om een Durable Functions-client te verkrijgen. U gebruikt de client om een indeling te starten. U kunt ook een HTTP-antwoord met URL's retourneren om de status van de nieuwe indeling te controleren.

De voorbeeldtoepassing uitvoeren

Als u de E1_HelloSequence indeling wilt uitvoeren, verzendt u de volgende HTTP POST-aanvraag naar de HttpStart functie.

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

Notitie

In het host.json vorige HTTP-fragment wordt ervan uitgegaan dat het bestand een vermelding bevat waarmee het standaardvoorvoegsel api/ wordt verwijderd uit alle URL's van HTTP-triggerfuncties. U vindt de opmaak voor deze configuratie in het host.json bestand in de voorbeelden.

Als u bijvoorbeeld het voorbeeld uitvoert in een functie-app met de naam 'myfunctionapp', vervangt u {host} door 'myfunctionapp.azurewebsites.net'.

Het resultaat is een HTTP 202-antwoord, zoals dit (ingekort voor beknoptheid):

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

Op dit moment wordt de indeling in de wachtrij geplaatst en wordt deze onmiddellijk uitgevoerd. De URL in de Location header kan worden gebruikt om de status van de uitvoering te controleren.

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

Het resultaat is de status van de indeling. Het wordt uitgevoerd en wordt snel voltooid, zodat u deze in de status Voltooid ziet met een antwoord dat er als volgt uitziet (ingekort voor beknoptheid):

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

Zoals u ziet, is het runtimeStatus exemplaar voltooid en bevat het output JSON-geserialiseerde resultaat van de uitvoering van de orchestratorfunctie.

Notitie

U kunt vergelijkbare starterslogica implementeren voor andere triggertypen, zoals queueTrigger, eventHubTriggerof timerTrigger.

Bekijk de uitvoeringslogboeken van de functie. De E1_HelloSequence functie is gestart en meerdere keren voltooid vanwege het gedrag van opnieuw afspelen dat wordt beschreven in het onderwerp betrouwbaarheid van indelingen. Aan de andere kant waren er slechts drie uitvoeringen E1_SayHello van omdat deze functie-uitvoeringen niet opnieuw worden afgespeeld.

Volgende stappen

In dit voorbeeld is een eenvoudige indeling voor functiekoppelingen gedemonstreerd. In het volgende voorbeeld ziet u hoe u het fan-out-/fan-in-patroon implementeert.

Het voorbeeld van fan-out/fan-in uitvoeren

Share via

Functiekoppeling in Durable Functions - Hello-reeksvoorbeeld

Vereisten

De functies

E1_HelloSequence orchestratorfunctie

function.json

index.js

function.json

init.py

E1_SayHello activiteitsfunctie

E1_SayHello/function.json

E1_SayHello/index.js

E1_SayHello/function.json

E1_SayHello/init.py

HttpStart-clientfunctie

HttpStart/function.json

HttpStart/index.js

HttpStart/function.json

HttpStart/init.py

De voorbeeldtoepassing uitvoeren

Volgende stappen

Feedback

Aanvullende resources