Encadeamento de funções no Durable Functions – Exemplo de sequência hello

Artigo
03/24/2023

O encadeamento de funções refere-se ao padrão de execução de uma sequência de funções numa ordem específica. Muitas vezes, a saída de uma função tem de ser aplicada à entrada de outra função. Este artigo descreve a sequência de encadeamento que cria quando conclui o início rápido do Durable Functions (C#, JavaScript, TypeScript, Python, PowerShell ou Java). Para obter mais informações sobre Durable Functions, consulte Durable Functions descrição geral.

Pré-requisitos

Nota

A versão 4 do modelo de programação Node.js para Funções do Azure está geralmente disponível. O novo modelo v4 foi concebido para ter uma experiência mais flexível e intuitiva para programadores JavaScript e TypeScript. Saiba mais sobre as diferenças entre v3 e v4 no guia de migração.

Nos fragmentos de código seguintes, o JavaScript (PM4) indica o modelo de programação V4, a nova experiência.

As funções

Este artigo explica as seguintes funções na aplicação de exemplo:

E1_HelloSequence: uma função de orquestrador que chama E1_SayHello várias vezes numa sequência. Armazena as saídas das E1_SayHello chamadas e regista os resultados.
E1_SayHello: uma função de atividade que prepara uma cadeia com "Hello".
HttpStart: uma função de cliente durável acionada por HTTP que inicia uma instância do orquestrador.

E1_HelloSequence função do orquestrador

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

Todas as funções de orquestração C# têm de ter um parâmetro do tipo DurableOrchestrationContext, que existe na Microsoft.Azure.WebJobs.Extensions.DurableTask assemblagem. Este objeto de contexto permite-lhe chamar outras funções de atividade e transmitir parâmetros de entrada com o respetivo CallActivityAsync método.

O código chama E1_SayHello três vezes em sequência com valores de parâmetros diferentes. O valor devolvido de cada chamada é adicionado à outputs lista, que é devolvida no final da função.

function.json

Se utilizar o Visual Studio Code ou o portal do Azure para desenvolvimento, eis o conteúdo do ficheiro function.json da função orchestrator. A maioria dos ficheiros function.json do orchestrator têm um aspeto quase exatamente semelhante a este.

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

O importante é o orchestrationTrigger tipo de enlace. Todas as funções do orquestrador têm de utilizar este tipo de acionador.

Aviso

Para cumprir a regra "sem E/S" das funções do orquestrador, não utilize quaisquer enlaces de entrada ou saída ao utilizar o enlace do acionador orchestrationTrigger . Se forem necessários outros enlaces de entrada ou saída, devem ser utilizados no contexto das activityTrigger funções, que são chamadas pelo orquestrador. Para obter mais informações, veja o artigo orchestrator function code constraints (Restrições de código de função do orquestrador ).

index.js

Eis a função orchestrator:

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

Todas as funções de orquestração JavaScript têm de incluir o durable-functions módulo. É uma biblioteca que lhe permite escrever Durable Functions em JavaScript. Existem três diferenças significativas entre uma função de orquestrador e outras funções JavaScript:

A função orchestrator é uma função geradora.
A função está encapsulada numa chamada para o durable-functions método do orchestrator módulo (aqui df).
A função tem de ser síncrona. Uma vez que o método "orchestrator" processa a chamada final para "context.done", a função deve simplesmente "devolver".

O context objeto contém um df objeto de contexto de orquestração durável que lhe permite chamar outras funções de atividade e transmitir parâmetros de entrada com o respetivo callActivity método. O código chama E1_SayHello três vezes em sequência com valores de parâmetros diferentes, utilizando yield para indicar que a execução deve aguardar que as chamadas da função de atividade assíncrona sejam devolvidas. O valor devolvido de cada chamada é adicionado à outputs matriz, que é devolvida no final da função.

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

Todas as funções de orquestração JavaScript têm de incluir o durable-functions módulo. Este módulo permite-lhe escrever Durable Functions no JavaScript. Para utilizar o modelo de programação de nós V4, tem de instalar a versão de pré-visualização v3.x do durable-functions.

Existem duas diferenças significativas entre uma função de orquestrador e outras funções JavaScript:

A função orchestrator é uma função geradora.
A função tem de ser síncrona. A função deve simplesmente "devolver".

O context objeto contém um df objeto de contexto de orquestração durável que lhe permite chamar outras funções de atividade e transmitir parâmetros de entrada com o respetivo callActivity método. O código chama sayHello três vezes em sequência com valores de parâmetros diferentes, utilizando yield para indicar que a execução deve aguardar que as chamadas da função de atividade assíncrona sejam devolvidas. O valor devolvido de cada chamada é adicionado à outputs matriz, que é devolvida no final da função.

Nota

Os Durable Functions python estão disponíveis apenas para o runtime das Funções 3.0.

function.json

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

O importante é o orchestrationTrigger tipo de enlace. Todas as funções do orquestrador têm de utilizar este tipo de acionador.

Aviso

init.py

Eis a função orchestrator:

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)

Todas as funções de orquestração do Python têm de incluir o durable-functions pacote. É uma biblioteca que lhe permite escrever Durable Functions no Python. Existem duas diferenças significativas entre uma função de orquestrador e outras funções python:

A função orchestrator é uma função geradora.
O ficheiro deve registar a função do orquestrador como orquestrador ao indicar main = df.Orchestrator.create(<orchestrator function name>) no final do ficheiro. Isto ajuda a distingui-lo de outras funções auxiliares declaradas no ficheiro.

O context objeto permite-lhe chamar outras funções de atividade e transmitir parâmetros de entrada com o respetivo call_activity método. O código chama E1_SayHello três vezes em sequência com valores de parâmetros diferentes, utilizando yield para indicar que a execução deve aguardar que as chamadas da função de atividade assíncrona sejam devolvidas. O valor devolvido de cada chamada é devolvido no final da função.

E1_SayHello função de atividade

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

As atividades utilizam o ActivityTrigger atributo. Utilize o fornecido IDurableActivityContext para efetuar ações relacionadas com a atividade, como aceder ao valor de entrada com GetInput<T>.

A implementação de E1_SayHello é uma operação de formatação de cadeia relativamente trivial.

Em vez de vincular a um IDurableActivityContext, pode vincular diretamente ao tipo que é transmitido para a função de atividade. Por exemplo:

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

E1_SayHello/function.json

O ficheiro function.json da função E1_SayHello activity é semelhante ao de, E1_HelloSequence exceto que utiliza um activityTrigger tipo de enlace em vez de um orchestrationTrigger tipo de enlace.

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

Nota

Todas as funções de atividade chamadas por uma função de orquestração têm de utilizar o activityTrigger enlace.

A implementação de E1_SayHello é uma operação de formatação de cadeia relativamente trivial.

E1_SayHello/index.js

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

Ao contrário da função orchestration, uma função de atividade não precisa de uma configuração especial. A entrada transmitida pela função orchestrator está localizada no context.bindings objeto sob o nome do activityTrigger enlace – neste caso, context.bindings.name. O nome do enlace pode ser definido como um parâmetro da função exportada e acedido diretamente, que é o que o código de exemplo faz.

A implementação de sayHello é uma operação de formatação de cadeia relativamente trivial.

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

const helloActivityName = "sayHello";

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

Ao contrário da função orchestration, uma função de atividade não precisa de uma configuração especial. A entrada transmitida pela função orchestrator é o primeiro argumento para a função. O segundo argumento é o contexto de invocação, que não é utilizado neste exemplo.

E1_SayHello/function.json

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

Nota

Todas as funções de atividade chamadas por uma função de orquestração têm de utilizar o activityTrigger enlace.

A implementação de E1_SayHello é uma operação de formatação de cadeia relativamente trivial.

E1_SayHello/init.py

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

Ao contrário da função orchestrator, uma função de atividade não precisa de uma configuração especial. A entrada transmitida pela função orchestrator é diretamente acessível como o parâmetro para a função.

HttpStart client function (Função de cliente HttpStart)

Pode iniciar uma instância da função orchestrator com uma função de cliente. Irá utilizar a função acionada HttpStart por HTTP para iniciar instâncias do 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);
    }
}

Para interagir com orquestradores, a função tem de incluir um DurableClient enlace de entrada. Utilize o cliente para iniciar uma orquestração. Também pode ajudá-lo a devolver uma resposta HTTP que contém URLs para verificar o estado da nova orquestração.

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
  }

Para interagir com orquestradores, a função tem de incluir um durableClient enlace de entrada.

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

Utilize df.getClient para obter um DurableOrchestrationClient objeto. Utilize o cliente para iniciar uma orquestração. Também pode ajudá-lo a devolver uma resposta HTTP que contém URLs para verificar o estado da nova orquestração.

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

Para gerir e interagir com orquestradores, a função precisa de um durableClient enlace de entrada. Este enlace tem de ser especificado no argumento ao extraInputs registar a função. Uma durableClient entrada pode ser obtida ao chamar df.input.durableClient().

Utilize df.getClient para obter um DurableClient objeto. Utilize o cliente para iniciar uma orquestração. Também pode ajudá-lo a devolver uma resposta HTTP que contém URLs para verificar o estado da nova orquestração.

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

Para interagir com orquestradores, a função tem de incluir um durableClient enlace de entrada.

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)

Utilize o DurableOrchestrationClient construtor para obter um cliente Durable Functions. Utilize o cliente para iniciar uma orquestração. Também pode ajudá-lo a devolver uma resposta HTTP que contém URLs para verificar o estado da nova orquestração.

Executar o exemplo

Para executar a E1_HelloSequence orquestração, envie o seguinte pedido HTTP POST para a HttpStart função.

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

Nota

O fragmento HTTP anterior pressupõe que existe uma entrada no host.json ficheiro que remove o prefixo predefinido api/ de todos os URLs das funções de acionador HTTP. Pode encontrar a marcação para esta configuração no host.json ficheiro nos exemplos.

Por exemplo, se estiver a executar o exemplo numa aplicação de funções com o nome "myfunctionapp", substitua "{host}" por "myfunctionapp.azurewebsites.net".

O resultado é uma resposta HTTP 202, como esta (cortada por brevidade):

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

Neste momento, a orquestração está em fila de espera e começa a ser executada imediatamente. O URL no Location cabeçalho pode ser utilizado para verificar o estado da execução.

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

O resultado é o estado da orquestração. É executado e concluído rapidamente, para que o veja no estado Concluído com uma resposta semelhante a esta (cortada por brevidade):

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

Como pode ver, a runtimeStatus instância é Concluída e contém output o resultado serializado JSON da execução da função orchestrator.

Nota

Pode implementar lógica de arranque semelhante para outros tipos de acionadores, como queueTrigger, eventHubTriggerou timerTrigger.

Observe os registos de execução de funções. A E1_HelloSequence função foi iniciada e concluída várias vezes devido ao comportamento de repetição descrito no tópico de fiabilidade da orquestração . Por outro lado, houve apenas três execuções de, uma vez que essas execuções de E1_SayHello funções não são reproduzidas.

Passos seguintes

Este exemplo demonstrou uma orquestração simples de encadeamento de funções. O exemplo seguinte mostra como implementar o padrão fan-out/fan-in.

Executar o exemplo Fan-out/fan-in

Partilhar via

Encadeamento de funções no Durable Functions – Exemplo de sequência hello

Pré-requisitos

As funções

E1_HelloSequence função do orquestrador

function.json

index.js

function.json

init.py

E1_SayHello função de atividade

E1_SayHello/function.json

E1_SayHello/index.js

E1_SayHello/function.json

E1_SayHello/init.py

HttpStart client function (Função de cliente HttpStart)

HttpStart/function.json

HttpStart/index.js

HttpStart/function.json

HttpStart/init.py

Executar o exemplo

Passos seguintes

Recursos adicionais