Ligações para funções duráveis (Azure Functions)

Ambas as versões do modelo de programação Python para Azure Functions são suportadas pelo Durable Functions. Como o Python v2 é a versão recomendada, os exemplos neste artigo apresentam exclusivamente essa versão.

Pré-requisitos

• Durable Functions SDK, que é o pacote Python Package Index (PyPI) azure-functions-durable, versão 1.2.2 ou uma versão posterior
• Pacote de extensão versão 4.x (ou uma versão posterior), que é definido no arquivo host.json do projeto

Você pode fornecer comentários e sugestões no repositório Durable Functions SDK for Python.

Ao desenvolver funções no .NET, você usa o atributo OrchestrationTriggerAttribute .NET para configurar o gatilho de orquestração.

Use a anotação @DurableOrchestrationTrigger para configurar o gatilho de orquestração para Java.

Quando você usa a versão 4 do modelo de programação Node.js para desenvolver funções, você importa o app objeto do @azure/functions npm módulo. Em seguida, você chama o app.orchestration método da API de funções duráveis diretamente em seu código de função. Esse método registra sua função de orquestrador com a estrutura Durable Functions.

Ao escrever funções de orquestrador, você define o gatilho de orquestração usando o seguinte objeto JSON na bindings matriz do arquivo function.json :

{
    "name": "<name-of-input-parameter-in-function-signature>",
    "orchestration": "<optional-name-of-orchestration>",
    "type": "orchestrationTrigger",
    "direction": "in"
}

O valor orchestration representa o nome da orquestração que os clientes devem usar quando desejam iniciar novas instâncias da função orquestrador. Esta propriedade é opcional. Se você não especificá-lo, o nome da função será usado.

Quando você usa o modelo de programação Python v2, você pode definir um gatilho de orquestração usando o orchestration_trigger decorador diretamente em seu código de função Python.

No modelo v2, você acessa os triggers e bindings de Durable Functions a partir de uma instância de DFApp. Você pode usar essa subclasse de FunctionApp para exportar decoradores específicos para funções duráveis.

O atributo que você usa para definir o gatilho depende se você executa suas funções C# no mesmo processo que o processo de host Functions ou em um processo de trabalho isolado.

[FunctionName("HelloWorld")]
public static string RunOrchestrator([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    return $"Hello {name}!";
}

[Function("HelloWorld")]
public static string RunOrchestrator([OrchestrationTrigger] TaskOrchestrationContext context, string name)
{
    return $"Hello {name}!";
}

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

df.app.orchestration('helloOrchestrator', function* (context) {
    const name = context.df.getInput();
    return `Hello ${name}`;
});

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

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.orchestration_trigger(context_name="context")
def my_orchestrator(context):
    result = yield context.call_activity("Hello", "Tokyo")
    return result

param($Context)

$InputData = $Context.Input
$InputData

@FunctionName("HelloWorldOrchestration")
public String helloWorldOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    return String.format("Hello %s!", ctx.getInput(String.class));
}

A maioria das funções do orquestrador chama funções de atividade. O código a seguir fornece um exemplo Hello World que demonstra como chamar uma função de atividade:

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

const activityName = 'hello';

df.app.orchestration('helloOrchestrator', function* (context) {
    const name = context.df.getInput();
    const result = yield context.df.callActivity(activityName, name);
    return result;
});

@FunctionName("HelloWorld")
public String helloWorldOrchestration(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    String input = ctx.getInput(String.class);
    String result = ctx.callActivity("SayHello", input, String.class).await();
    return result;
}

Use o atributo .NET ActivityTriggerAttribute para configurar o gatilho de atividade.

Você utiliza a anotação @DurableActivityTrigger para configurar o gatilho de atividade.

Para registrar sua função de atividade, importe o app objeto do @azure/functions npm módulo. Em seguida, você chama o app.activity método da API de funções duráveis diretamente em seu código de função.

Para definir o gatilho de atividade, use o seguinte objeto JSON na bindings matriz de function.json:

{
    "name": "<name-of-input-parameter-in-function-signature>",
    "activity": "<optional-name-of-activity>",
    "type": "activityTrigger",
    "direction": "in"
}

O activity valor é o nome da atividade. Esse valor é o nome que as funções do orquestrador usam para invocar essa função de atividade. Esta propriedade é opcional. Se você não especificá-lo, o nome da função será usado.

Você pode definir um gatilho de atividade usando o decorador activity_trigger diretamente em seu código de função Python.

const { app } = require('@azure/functions');
const df = require('durable-functions');
const activityName = 'hello';
df.app.activity(activityName, {
    handler: (input) => {
        return `Hello, ${input}`;
    },
});

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

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.activity_trigger(input_name="myInput")
def my_activity(myInput: str):
    return "Hello " + myInput

param($name)

"Hello $name!"

@FunctionName("SayHello")
public String sayHello(@DurableActivityTrigger(name = "name") String name) {
    return String.format("Hello %s!", name);
}

Por exemplo, uma função de atividade pode receber entrada de uma função de orquestração. A função activity pode enviar essa entrada como uma mensagem para os Hubs de Eventos do Azure.

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

df.app.orchestration('helloOrchestrator', function* (context) {
    const input = context.df.getInput();
    yield context.df.callActivity('sendToEventHub', input);
    return `Message sent: ${input}`;
});

const { EventHubProducerClient } = require("@azure/event-hubs");
const connectionString = process.env.EVENT_HUB_CONNECTION_STRING;
const eventHubName = process.env.EVENT_HUB_NAME;

df.app.activity("sendToEventHub", {
    handler: async (message, context) => {
        const producer = new EventHubProducerClient(connectionString, eventHubName);
        try {
            const batch = await producer.createBatch();
            batch.tryAdd({ body: message });
            await producer.sendBatch(batch);
            context.log(`Message sent to Event Hubs: ${message}`);
        } catch (err) {
            context.log.error("Failed to send message to Event Hubs:", err);
            throw err;
        } finally {
            await producer.close();
        }
    },
});

app.storageQueue('helloQueueStart', {
    queueName: 'start-orchestration',
    extraInputs: [df.input.durableClient()],
    handler: async (message, context) => {
        const client = df.getClient(context);
        const orchestratorName = message.orchestratorName || 'helloOrchestrator';
        const input = message.input || null;
        const instanceId = await client.startNew(orchestratorName, { input });
        context.log(`Started orchestration with ID = '${instanceId}'`);
    },
});

Você pode vincular a um cliente de orquestração usando o atributo DurableClientAttribute (OrchestrationClientAttribute em Durable Functions 1.x).

Você pode vincular a um cliente de orquestração usando a @DurableClientInput anotação.

Para registrar sua função de cliente, importe o app objeto do @azure/functions npm módulo. Em seguida, você chama um método de API de funções duráveis que é específico para o seu tipo de gatilho. Por exemplo, para um gatilho HTTP, você chama o app.http método. Para um gatilho de fila, você chama o app.storageQueue método.

Para definir o gatilho durável do cliente, use o objeto JSON seguinte na matriz bindings de function.json:

{
    "name": "<name-of-input-parameter-in-function-signature>",
    "taskHub": "<optional-name-of-task-hub>",
    "connectionName": "<optional-name-of-connection-string-app-setting>",
    "type": "orchestrationClient",
    "direction": "in"
}

• A taskHub propriedade é usada quando vários aplicativos de função compartilham a mesma conta de armazenamento, mas precisam ser isolados uns dos outros. Se você não especificar essa propriedade, o valor padrão de host.json será usado. Esse valor deve corresponder ao valor que as funções do orquestrador de destino usam.
• O connectionName valor é o nome de uma configuração de aplicativo que contém uma cadeia de conexão de conta de armazenamento. A conta de armazenamento representada por essa cadeia de conexão deve ser a mesma que as funções do orquestrador de destino usam. Se você não especificar essa propriedade, a cadeia de conexão de conta de armazenamento padrão para o aplicativo de função será usada.

Você pode definir um gatilho de cliente durável usando o decorador durable_client_input diretamente no seu código de função Python.

Você normalmente se associa a uma implementação de IDurableClient (DurableOrchestrationClient in Durable Functions 1.x), que lhe dá acesso total a todas as APIs de cliente de orquestração suportadas pelo Durable Functions.

Normalmente, você se liga à classe DurableClientContext.

Você deve usar o SDK específico do idioma para obter acesso a um objeto cliente.

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

app.storageQueue('helloQueueStart', {
    queueName: 'start-orchestration',
    extraInputs: [df.input.durableClient()],
    handler: async (message, context) => {
        const client = df.getClient(context);
        const orchestratorName = message.orchestratorName || 'helloOrchestrator';
        const input = message.input || null;
        const instanceId = await client.startNew(orchestratorName, { input });
        context.log(`Started orchestration with ID = '${instanceId}' from queue message.`);
    },
});

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

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.queue_trigger(
    arg_name="msg",
    queue_name="start-orchestration",
    connection="AzureWebJobsStorage"
)
@myApp.durable_client_input(client_name="client")
async def client_function(msg: func.QueueMessage, client: df.DurableOrchestrationClient):
    input_data = msg.get_body().decode("utf-8")
    await client.start_new("my_orchestrator", None, input_data)
    return None

function.json

{
  "bindings": [
    {
      "name": "InputData",
      "type": "queueTrigger",
      "queueName": "durable-function-trigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

run.ps1

param([string]$InputData, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld' -Input $InputData

@FunctionName("QueueStart")
public void queueStart(
        @QueueTrigger(name = "input", queueName = "durable-function-trigger", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    // Orchestration input comes from the queue message content.
    durableContext.getClient().scheduleNewOrchestrationInstance("HelloWorld", input);
}

Use o atributo EntityTriggerAttribute do .NET para configurar o ativador de entidade.

Para registrar o gatilho de entidade, importe o objeto app do módulo @azure/functions npm. Em seguida, você chama o app.entity método da API de funções duráveis diretamente em seu código de função.

const df = require('durable-functions');
df.app.entity('counter', (context) => {
    const currentValue = context.df.getState(() => 0);
    switch (context.df.operationName) {
        case 'add':
            context.df.setState(currentValue + context.df.getInput());
            break;
        case 'reset':
            context.df.setState(0);
            break;
        case 'get':
            context.df.return(currentValue);
            break;
    }
});

Você pode definir um gatilho de entidade usando o decorador entity_trigger diretamente em seu código de função Python.

Você pode vincular à entidade cliente usando o atributo DurableClientAttribute .NET em funções de biblioteca de classes .NET.

Em vez de registar um cliente de entidade, utiliza signalEntity ou callEntity para chamar um método de gatilho de entidade a partir de qualquer função registada.

• A partir de uma função acionada por fila, você pode usar client.signalEntity:

  const { app } = require('@azure/functions');
  const df = require('durable-functions');
  app.storageQueue('helloQueueStart', {
      queueName: 'start-orchestration',
      extraInputs: [df.input.durableClient()],
      handler: async (message, context) => {
          const client = df.getClient(context);
          const entityId = new df.EntityId('counter', 'myCounter');
          await client.signalEntity(entityId, 'add', 5);
      },
  });
  

• A partir de uma função de orquestração, podes utilizar context.df.callEntity:

  const { app } = require('@azure/functions');
  const df = require('durable-functions');
  df.app.orchestration('entityCaller', function* (context) {
      const entityId = new df.EntityId('counter', 'myCounter');
      yield context.df.callEntity(entityId, 'add', 5);
      yield context.df.callEntity(entityId, 'add', 5);
      const result = yield context.df.callEntity(entityId, 'get');
      return result;
  });
  

Você pode definir um cliente de entidade usando o durable_client_input decorador diretamente em seu código de função Python.