지속성 함수에 대한 바인딩(Azure Functions)

Azure Functions용 Python 프로그래밍 모델의 두 버전은 모두 Durable Functions에서 지원됩니다. Python v2가 권장 버전이므로 이 문서의 예제에서는 이 버전만 제공합니다.

필수 조건

• Durable Functions SDK는 PyPI(Python 패키지 인덱스) 패키지 azure-functions-durable이며, 버전 1.2.2 또는 그 이후의 버전입니다.
• host.json 프로젝트 파일에 설정된 확장 번들 버전 4.x(이상 버전)

Python용 Durable Functions SDK 리포지토리에서 피드백과 제안을 제공할 수 있습니다.

.NET에서 함수를 개발할 때 OrchestrationTriggerAttribute .NET 특성을 사용하여 오케스트레이션 트리거를 구성합니다.

Java의 경우 주석을 @DurableOrchestrationTrigger 사용하여 오케스트레이션 트리거를 구성합니다.

Node.js 프로그래밍 모델의 버전 4를 사용하여 함수를 개발하는 경우 모듈에서 개체를 app@azure/functions npm 가져옵니다. 그런 다음 함수 코드에서 Durable Functions API의 메서드를 직접 호출 app.orchestration 합니다. 이 메서드는 Durable Functions 프레임워크에 오케스트레이터 함수를 등록합니다.

오케스트레이터 함수를 작성할 때 bindings 파일 배열에서 다음 JSON 개체를 사용하여 오케스트레이션 트리거를 정의합니다.

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

값은 orchestration 클라이언트가 오케스트레이터 함수의 새 인스턴스를 시작하려는 경우 사용해야 하는 오케스트레이션의 이름입니다. 이 속성은 선택 사항입니다. 지정하지 않으면 함수 이름이 사용됩니다.

Python v2 프로그래밍 모델을 사용하는 경우 Python 함수 코드에서 직접 데코레이터를 orchestration_trigger 사용하여 오케스트레이션 트리거를 정의할 수 있습니다.

v2 모델에서는 DFApp 인스턴스를 통해 Durable Functions의 트리거 및 바인딩에 액세스합니다. 이 하위 클래스를 FunctionApp 사용하여 Durable Functions와 관련된 데코레이터를 내보낼 수 있습니다.

트리거를 정의하는 데 사용하는 특성은 Functions 호스트 프로세스와 동일한 프로세스에서 또는 격리된 작업자 프로세스에서 C# 함수를 실행할지 여부에 따라 달라집니다.

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

대부분의 오케스트레이터 함수는 작업 함수를 호출합니다. 다음 코드는 활동 함수를 호출하는 방법을 보여 주는 Hello World 예제를 제공합니다.

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

ActivityTriggerAttribute .NET 특성을 사용하여 활동 트리거를 구성합니다.

@DurableActivityTrigger 주석을 사용하여 활동 트리거를 구성합니다.

활동 함수를 등록하려면 app 모듈에서 @azure/functions npm 개체를 가져옵니다. 그런 다음 함수 코드에서 Durable Functions API의 메서드를 직접 호출 app.activity 합니다.

활동 트리거를 정의하려면 bindings배열에서 다음 JSON 개체를 사용합니다.

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

값은 activity 활동의 이름입니다. 이 값은 오케스트레이터 함수가 이 작업 함수를 호출하는 데 사용하는 이름입니다. 이 속성은 선택 사항입니다. 지정하지 않으면 함수 이름이 사용됩니다.

Python 함수 코드에서 직접 데코레이터를 activity_trigger 사용하여 활동 트리거를 정의할 수 있습니다.

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

예를 들어 작업 함수는 오케스트레이터 함수에서 입력을 받을 수 있습니다. 그런 다음 활동 함수는 해당 입력을 Azure Event Hubs에 메시지로 보낼 수 있습니다.

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

DurableClientAttribute 특성을 사용하여 오케스트레이션 클라이언트에 바인딩할 수 있습니다 (Durable Functions 1.x의 OrchestrationClientAttribute).

@DurableClientInput 주석을 사용하여 오케스트레이션 클라이언트에 바인딩할 수 있습니다.

클라이언트 함수를 등록하려면 app 모듈에서 @azure/functions npm 객체를 가져옵니다. 그런 다음 트리거 유형과 관련된 Durable Functions API 메서드를 호출합니다. 예를 들어 HTTP 트리거의 경우 메서드를 호출합니다 app.http . 큐 트리거의 경우 메서드를 호출합니다 app.storageQueue .

지속성 클라이언트 트리거를 정의하려면 bindings배열에서 다음 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"
}

• 이 taskHub 속성은 여러 함수 앱이 동일한 스토리지 계정을 공유하지만 서로 격리해야 하는 경우에 사용됩니다. 이 속성을 지정하지 않으면 host.json 기본값이 사용됩니다. 이 값은 대상 오케스트레이터 함수가 사용하는 값과 일치해야 합니다.
• 값은 connectionName 스토리지 계정 연결 문자열을 포함하는 앱 설정의 이름입니다. 이 연결 문자열로 표시되는 스토리지 계정은 대상 오케스트레이터 함수가 사용하는 것과 동일해야 합니다. 이 속성을 지정하지 않으면 함수 앱의 기본 스토리지 계정 연결 문자열이 사용됩니다.

Python 함수 코드에서 직접 데코레이터를 durable_client_input 사용하여 지속성 클라이언트 트리거를 정의할 수 있습니다.

일반적으로 IDurableClient의 구현에 바인딩하며, 이는 Durable Functions 1.x에서는 DurableOrchestrationClient로 불립니다. 이를 통해 지속성 함수가 지원하는 모든 오케스트레이션 클라이언트 API에 완전한 액세스 권한을 제공합니다.

일반적으로 DurableClientContext 클래스에 바인딩합니다.

클라이언트 개체에 액세스하려면 언어별 SDK를 사용해야 합니다.

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

EntityTriggerAttribute .NET 특성을 사용하여 엔터티 트리거를 구성합니다.

엔터티 트리거를 등록하려면 app 모듈에서 @azure/functions npm 개체를 가져옵니다. 그런 다음 함수 코드에서 Durable Functions API의 메서드를 직접 호출 app.entity 합니다.

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

Python 함수 코드에서 직접 데코레이터를 entity_trigger 사용하여 엔터티 트리거를 정의할 수 있습니다.

.NET 클래스 라이브러리 함수에서 DurableClientAttribute .NET 특성을 사용하여 엔터티 클라이언트에 바인딩할 수 있습니다.

엔터티 클라이언트를 등록하는 대신 등록된 함수에서 엔터티 트리거 메서드를 signalEntity 또는 callEntity으로 호출합니다.

• 큐 트리거 함수에서 다음을 사용할 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);
      },
  });
  

• 오케스트레이터 함수에서 다음을 사용할 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;
  });
  

Python 함수 코드에서 직접 데코레이터를 durable_client_input 사용하여 엔터티 클라이언트를 정의할 수 있습니다.