Ligações para Durable Functions ​​(Azure Functions)

Ambas as versões do modelo de programação python para o Azure Functions têm suporte do Durable Functions. Como o Python v2 é a versão recomendada, os exemplos neste artigo apresentam exclusivamente essa versão.

Pré-requisitos

• SDK do Durable Functions, que é o pacote PyPI (Python Package Index) 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 de projeto host.json

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

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

Para Java, use a @DurableOrchestrationTrigger anotação para configurar o gatilho de orquestração.

Quando você usa a versão 4 do modelo de programação Node.js para desenvolver funções, 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 o framework 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 é o nome da orquestração que os clientes devem usar quando desejam iniciar novas instâncias da função de orquestrador. Esta propriedade é opcional. Se você não especificá-la, o nome da função será usado.

Ao usar 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 gatilhos e associações do Durable Functions de uma instância de DFApp. Você pode usar essa subclasse de FunctionApp para exportar decoradores específicos para Durable Functions.

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

Use 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 de orquestrador usam para invocar essa função de atividade. Esta propriedade é opcional. Se você não especificá-la, o nome da função será usado.

Você pode definir um gatilho de atividade usando o activity_trigger decorador diretamente no código da 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 orquestrador. A função de atividade 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 associar a um cliente de orquestração usando o atributo DurableClientAttribute (OrchestrationClientAttribute em Durable Functions 1.x).

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

Para registrar sua função 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 específico ao 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 método app.storageQueue.

Para definir o gatilho de cliente durável, use o seguinte objeto JSON na bindings matriz 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ções 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 de orquestrador de destino usam.
• O connectionName valor é o nome de uma configuração de aplicativo que contém uma string 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 de orquestrador de destino usam. Se você não especificar essa propriedade, a cadeia de conexão da conta de armazenamento padrão para o aplicativo de funções será usada.

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

Normalmente, você se vincula a uma implementação de IDurableClient (DurableOrchestrationClient no Durable Functions 1.x), que fornece acesso total a todas as APIs de cliente de orquestração compatíveis com o Durable Functions.

Normalmente, você se vincula à 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 .NET EntityTriggerAttribute para configurar o gatilho 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 diretamente o decorador entity_trigger no código da função Python.

Você pode associar-se ao cliente da entidade usando o atributo DurableClientAttribute .NET em funções da biblioteca de classes do .NET.

Em vez de registrar um cliente de entidade, você usa signalEntity ou callEntity para chamar um método disparador de entidade de qualquer função registrada.

• Em uma função disparada 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);
      },
  });
  

• Em uma função de orquestrador, você pode usar 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 no código da função Python.