지속성 함수의 바인딩(Azure Functions)

아티클
03/15/2024

Durable Functions 확장은 오케스트레이터, 엔터티 및 작업 함수의 실행을 제어하는 3개의 트리거 바인딩을 도입합니다. 또한 지속성 함수 런타임에 대한 클라이언트 역할을 하는 출력 바인딩도 도입하고 있습니다.

문서의 맨 위에 있는 Durable Functions 개발 언어를 선택해야 합니다.

Important

이 문서에서는 Durable Functions에 대한 Python v1 및 Python v2 프로그래밍 모델을 모두 지원합니다.

Python v2 프로그래밍 모델

Durable Functions는 새 Python v2 프로그래밍 모델에서 지원됩니다. v2 모델을 사용하려면 PyPI 패키지 azure-functions-durable, 버전 1.2.2 또는 이후 버전인 Durable Functions SDK를 설치해야 합니다. 또한 host.json을 검사하여 앱이 Durable Functions에서 v2 모델을 사용하는 데 확장 번들 버전 4.x을 참조하고 있는지 확인해야 합니다.

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

오케스트레이션 트리거

오케스트레이션 트리거를 사용하여 지속성 오케스트레이터 함수를 작성할 수 있습니다. 이 트리거는 새 오케스트레이션 인스턴스가 예약되었을 때 그리고 기존 오케스트레이션 인스턴스가 이벤트를 수신할 때 실행됩니다. 오케스트레이터 함수를 트리거할 수 있는 이벤트 예로는 지속성 타이머 만료, 작업 함수 응답, 외부 클라이언트에 의해 발생하는 이벤트가 포함됩니다.

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

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

오케스트레이터 함수를 작성하는 경우 오케스트레이션 트리거는 function.json 파일의 bindings 배열에 있는 다음 JSON 개체에서 정의됩니다.

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

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

Azure Functions는 Python에 대해 두 가지 프로그래밍 모델을 지원합니다. 오케스트레이션 트리거를 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

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

v2 모델에서 Durable Functions 트리거 및 바인딩은 Durable Functions 특정 데코레이터를 추가로 내보내는 FunctionApp의 하위 클래스인 DFApp의 인스턴스에서 액세스합니다.

Python v1 프로그래밍 모델에서 오케스트레이터 함수를 작성하는 경우 오케스트레이션 트리거는 function.json 파일의 bindings 배열에 있는 다음 JSON 개체에서 정의됩니다.

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

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

내부적으로 이 트리거 바인딩은 오케스트레이션 시작 이벤트, 지속성 타이머 만료 이벤트, 작업 함수 응답 이벤트 및 다른 함수에 의해 발생한 외부 이벤트와 같은 새 오케스트레이션 이벤트에 대해 구성된 지속성 저장소를 폴링합니다.

트리거 동작

다음은 오케스트레이션 트리거에 대한 몇 가지 참고 사항입니다.

단일 스레드 - 단일 디스패처 스레드는 단일 호스트 인스턴스에서 모든 오케스트레이터 함수를 실행하는 데 사용됩니다. 이러한 이유로 오케스트레이터 함수 코드가 효율적이고 모든 I/O를 수행하지 않도록 하는 것이 중요합니다. 또한 이 스레드에서 지속성 함수 관련 작업 종류를 기다리는 경우를 제외하고는 비동기 작업을 수행하지 않도록 하는 것이 중요합니다.
포이즌 메시지 처리 - 오케스트레이션 트리거에는 포이즌 메시지 지원이 없습니다.
메시지 가시성 - 오케스트레이션 트리거 메시지가 구성 가능한 기간 동안 큐에서 제거되고 보이지 않게 유지됩니다. 함수 앱이 실행되고 있고 정상으로 유지되는 동안은 이러한 메시지의 가시성이 자동으로 갱신됩니다.
반환 값 - 반환 값은 JSON으로 직렬화되고 Azure Table Storage의 오케스트레이션 기록 테이블에 유지됩니다. 이러한 반환 값은 나중에 설명할 오케스트레이션 클라이언트 바인딩을 통해 쿼리할 수 있습니다.

Warning

오케스트레이터 함수는 오케스트레이션 트리거 바인딩 이외의 입력 또는 출력 바인딩을 절대로 사용하면 안됩니다. 이렇게 하면 그러한 바인딩에서 단일 스레딩 및 I/O 규칙을 따르지 않을 수 있으므로 지속성 작업 확장에서 문제가 발생할 수 있습니다. 다른 바인딩을 사용하려면, 이를 Orchestrator 함수에서 호출한 작업 함수에 추가합니다. 오케스트레이터 함수의 코딩 제약 조건에 대한 자세한 내용은 오케스트레이터 함수 코드 제약 조건 설명서를 참조하세요.

Warning

오케스트레이터 함수는 async로 선언되지 않아야 합니다.

트리거 사용

오케스트레이션 트리거 바인딩은 입력과 출력을 모두 지원합니다. 다음은 입력 및 출력 처리에 대해 알고 있어야 할 몇 가지 사항입니다.

입력 - 오케스트레이션 트리거는 컨텍스트 입력 개체를 통해 액세스되는 입력을 사용하여 호출될 수 있습니다. 모든 입력은 JSON 직렬화 가능 형식이어야 합니다.
출력 - 오케스트레이션 트리거는 입력뿐만 아니라 출력 값도 지원합니다. 함수의 반환 값은 출력 값을 할당하는 데 사용되며 JSON 직렬화 가능해야 합니다.

트리거 샘플

다음은 가장 간단한 "Hello World" 오케스트레이터 함수 예제입니다. 이 예제 오케스트레이터는 실제로 작업을 예약하지 않습니다.

트리거를 정의하는 데 사용되는 특정 특성은 C# 함수를 프로세스 내 또는 격리된 작업자 프로세스에서 실행 중인지에 따라 달라집니다.

In-process
격리된 프로세스

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

참고 항목

이전 코드는 Durable Functions 2.x용입니다. Durable Functions 1.x의 경우 IDurableOrchestrationContext 대신 DurableOrchestrationContext를 사용해야 합니다. 버전 간의 차이점에 대한 자세한 내용은 Durable Functions 버전 문서를 참조하세요.

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

참고 항목

프로세스 내 및 .NET 격리의 Durable 함수 모두에서 오케스트레이션 입력은 context.GetInput<T>()을 통해 추출할 수 있습니다. 그러나 .NET 격리는 위에 표시된 것처럼 매개 변수로 제공되는 입력도 지원합니다. 입력 바인딩은 바인딩 특성이 없고 이미 다른 입력 바인딩에서 다루는 잘 알려진 형식이 아닌 첫 번째 매개 변수에 바인딩됩니다(예: FunctionContext).

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

module.exports = df.orchestrator(function*(context) {
    const name = context.df.getInput();
    return `Hello ${name}!`;
});

참고 항목

durable-functions 라이브러리는 생성기 함수가 종료될 때 동기식 context.done 메서드의 호출을 처리합니다.

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

import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    input = context.get_input()
    return f"Hello {input['name']}!"

main = df.Orchestrator.create(orchestrator_function)

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" 예제가 여기에 있습니다.

In-process
격리된 프로세스

[FunctionName("HelloWorld")]
public static async Task<string> Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string name = context.GetInput<string>();
    string result = await context.CallActivityAsync<string>("SayHello", name);
    return result;
}

참고 항목

이전 코드는 Durable Functions 2.x용입니다. Durable Functions 1.x의 경우 IDurableOrchestrationContext 대신 DurableOrchestrationContext를 사용해야 합니다. 버전 간 차이점에 관한 자세한 내용은 Durable Functions 버전 문서를 참조하세요.

[Function("HelloWorld")]
public static async Task<string> Run(
    [OrchestrationTrigger] TaskOrchestrationContext context, string name)
{
    string result = await context.CallActivityAsync<string>("SayHello", name);
    return result;
}

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

module.exports = df.orchestrator(function*(context) {
    const name = context.df.getInput();
    const result = yield context.df.callActivity("SayHello", 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 주석을 사용하여 구성됩니다.

작업 트리거는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

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

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

작업 트리거를 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python 함수 코드에서 직접 activity_trigger 데코레이터를 사용합니다.

작업 트리거는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

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

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

내부적으로 이 트리거 바인딩은 새 작업 실행 이벤트에 대해 구성된 지속성 저장소를 폴링합니다.

트리거 동작

다음은 작업 트리거에 대한 몇 가지 참고 사항입니다.

스레딩 - 오케스트레이션 트리거와 달리 작업 트리거에는 스레딩 또는 I/O에 대한 제한이 없습니다. 일반 함수처럼 처리될 수 있습니다.
포이즌 메시지 처리 - 작업 트리거에는 포이즌 메시지 지원이 없습니다.
메시지 가시성 - 작업 트리거 메시지가 구성 가능한 기간 동안 큐에서 제거되고 보이지 않게 유지됩니다. 함수 앱이 실행되고 있고 정상으로 유지되는 동안은 이러한 메시지의 가시성이 자동으로 갱신됩니다.
반환 값 - 반환 값이 JSON으로 직렬화되고 구성된 지속성 저장소에 저장됩니다.

트리거 사용

작업 트리거 바인딩은 오케스트레이션 트리거와 마찬가지로 입력과 출력을 모두 지원합니다. 다음은 입력 및 출력 처리에 대해 알고 있어야 할 몇 가지 사항입니다.

입력 - 작업 트리거는 오케스트레이터 함수의 입력으로 호출될 수 있습니다. 모든 입력은 JSON 직렬화 가능 형식이어야 합니다.
출력 - 작업 함수는 입력뿐만 아니라 출력 값도 지원합니다. 함수의 반환 값은 출력 값을 할당하는 데 사용되며 JSON 직렬화 가능해야 합니다.
메타데이터 - .NET 작업 함수는 string instanceId 매개변수에 바인딩되어 호출 오케스트레이션의 인스턴스 ID를 가져올 수 있습니다.

트리거 샘플

다음 예제 코드는 간단한 SayHello 작업 함수가 어떻게 표시될 수 있는지를 보여 줍니다.

In-process
격리된 프로세스

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

.NET ActivityTriggerAttribute 바인딩의 기본 매개변수 유형은 IDurableActivityContext(또는 Durable Functions v1의 경우 DurableActivityContext)입니다. 그러나 .NET 작업 트리거는 JSON 직렬화 가능 형식(기본 형식 포함)에 대한 직접 바인딩도 지원하므로 동일한 함수를 다음과 같이 단순화할 수 있습니다.

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

.NET 격리 작업자는 입력을 나타내는 직렬화 가능한 형식만 [ActivityTrigger]에 대해 지원됩니다.

[Function("SayHello")]
public static string SayHello([ActivityTrigger] string name)
{
    return $"Hello {name}!";
}

module.exports = async function(context) {
    return `Hello ${context.bindings.name}!`;
};

JavaScript 바인딩도 추가 매개 변수로 전달될 수 있으므로 동일한 함수를 다음과 같이 단순화할 수 있습니다.

module.exports = async function(context, name) {
    return `Hello ${name}!`;
};

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

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

param($name)

"Hello $name!"

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

입력 및 출력 바인딩 사용

작업 트리거 바인딩 외에도 일반 입력 및 출력 바인딩을 사용할 수 있습니다.

예를 들면, 작업 바인딩에 입력을 가져오고 EventHub 출력 바인딩을 사용하여 EventHub에 메시지를 보낼 수 있습니다.

{
  "bindings": [
    {
      "name": "message",
      "type": "activityTrigger",
      "direction": "in"
    },
    {
      "type": "eventHub",
      "name": "outputEventHubMessage",
      "connection": "EventhubConnectionSetting",
      "eventHubName": "eh_messages",
      "direction": "out"
  }
  ]
}

module.exports = async function (context) {
    context.bindings.outputEventHubMessage = context.bindings.message;
};

오케스트레이션 클라이언트

오케스트레이션 클라이언트 바인딩을 사용하면 오케스트레이터 함수와 상호 작용하는 함수를 작성할 수 있습니다. 이러한 함수를 종종 클라이언트 함수라고 부릅니다. 예를 들어 오케스트레이션 인스턴스에서 다음과 같은 방법으로 작동할 수 있습니다.

인스턴스를 시작합니다.
해당 상태를 쿼리합니다.
인스턴스를 종료합니다.
실행하는 동안 이벤트를 보냅니다.
인스턴스 기록을 제거합니다.

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

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

지속형 클라이언트 트리거는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

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

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

참고 항목

대부분의 경우 이러한 속성을 생략하고 기본 동작을 사용하는 것이 좋습니다.

지속형 클라이언트 트리거를 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python 함수 코드에서 직접 durable_client_input 데코레이터를 사용합니다.

지속형 클라이언트 트리거는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

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

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

참고 항목

대부분의 경우 이러한 속성을 생략하고 기본 동작을 사용하는 것이 좋습니다.

클라이언트 사용

일반적으로 IDurableClient(Durable Functions v1.x의 DurableOrchestrationClient)에 바인딩합니다. 그러면 Durable Functions에서 지원되는 모든 오케스트레이션 클라이언트 API에 대해 모든 액세스 권한을 부여합니다.

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

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

다음은 "HelloWorld" 오케스트레이션을 시작하는 큐 트리거 함수 예제입니다.

In-process
격리된 프로세스

[FunctionName("QueueStart")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] IDurableOrchestrationClient starter)
{
    // Orchestration input comes from the queue message content.
    return starter.StartNewAsync<string>("HelloWorld", input);
}

참고 항목

이전 C# 코드는 Durable Functions 2.x용입니다. Durable Functions 1.x의 경우 DurableClient 특성 대신 OrchestrationClient 특성을 사용해야 하며 IDurableOrchestrationClient 대신 DurableOrchestrationClient 매개 변수 형식을 사용해야 합니다. 버전 간의 차이점에 대한 자세한 내용은 Durable Functions 버전 문서를 참조하세요.

[Function("QueueStart")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] DurableTaskClient client)
{
    // Orchestration input comes from the queue message content.
    return client.ScheduleNewOrchestrationInstanceAsync("HelloWorld", input);
}

function.json

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

index.js

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

module.exports = async function (context) {
    const client = df.getClient(context);
    return instanceId = await client.startNew("HelloWorld", undefined, context.bindings.input);
};

run.ps1

param([string] $input, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName $FunctionName -Input $input

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

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

@myApp.route(route="orchestrators/{functionName}")
@myApp.durable_client_input(client_name="client")
async def durable_trigger(req: func.HttpRequest, client):
    function_name = req.route_params.get('functionName')
    instance_id = await client.start_new(function_name)
    response = client.create_check_status_response(req, instance_id)
    return response

function.json

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

__init__.py

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

async def main(msg: func.QueueMessage, starter: str) -> None:
    client = df.DurableOrchestrationClient(starter)
    payload = msg.get_body().decode('utf-8')
    instance_id = await client.start_new("HelloWorld", client_input=payload)

function.json

{
  "bindings": [
    {
      "name": "input",
      "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);
}

인스턴스 시작에 대한 자세한 내용은 인스턴스 관리에서 찾을 수 있습니다.

엔터티 트리거

엔터티 트리거를 사용하면 엔터티 함수를 작성할 수 있습니다. 이 트리거는 특정 엔터티 인스턴스에 대한 이벤트 처리를 지원합니다.

참고 항목

엔터티 트리거는 Durable Functions 2.x부터 사용할 수 있습니다.

내부적으로 이 트리거 바인딩은 실행해야 할 새 엔터티 작업에 대해 구성된 지속성 저장소를 폴링합니다.

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

엔터티 트리거는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

{
    "name": "<Name of input parameter in function signature>",
    "entityName": "<Optional - name of the entity>",
    "type": "entityTrigger",
    "direction": "in"
}

기본적으로 엔터티의 이름은 함수의 이름입니다.

참고 항목

엔터티 트리거는 Java에서 아직 지원되지 않습니다.

엔터티 트리거를 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python 함수 코드에서 직접 entity_trigger 데코레이터를 사용합니다.

엔터티 트리거는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

{
    "name": "<Name of input parameter in function signature>",
    "entityName": "<Optional - name of the entity>",
    "type": "entityTrigger",
    "direction": "in"
}

기본적으로 엔터티의 이름은 함수의 이름입니다.

트리거 동작

다음은 엔터티 트리거에 대한 몇 가지 참고 사항입니다.

단일 스레드: 단일 디스패처 스레드를 사용하여 특정 엔터티에 대한 작업을 처리합니다. 여러 메시지를 단일 엔터티로 동시에 보내는 경우, 작업은 한 번에 하나씩 처리됩니다.
포이즌 메시지 처리 - 엔터티 트리거에는 포이즌 메시지 지원이 없습니다.
메시지 가시성 - 구성 가능한 기간 동안 엔터티 트리거 메시지가 큐에서 제거되고 보이지 않게 유지됩니다. 함수 앱이 실행되고 있고 정상으로 유지되는 동안은 이러한 메시지의 가시성이 자동으로 갱신됩니다.
반환 값 - 엔터티 함수는 반환 값을 지원하지 않습니다. 상태를 저장하거나 값을 다시 오케스트레이션에 전달하는 데 사용할 수 있는 특정 API가 있습니다.

실행 중에 엔터티 상태를 변경하면 실행이 완료된 후 자동으로 유지 됩니다.

엔터티 트리거를 정의하고 상호 작용하는 방법과 예제는 지속성 엔터티 설명서를 참조하세요.

엔터티 클라이언트

엔터티 클라이언트 바인딩을 사용하면 엔터티 함수를 비동기적으로 트리거할 수 있습니다. 해당 함수를 클라이언트 함수라고도 합니다.

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

참고 항목

[DurableClientAttribute]를 사용하여 오케스트레이션 클라이언트에 바인딩할 수도 있습니다.

엔터티 클라이언트는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

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

taskHub - 여러 함수 앱에서 동일한 스토리지 계정을 공유하지만 서로 격리되어야 하는 시나리오에 사용됩니다. 지정하지 않으면 host.json의 기본값이 사용됩니다. 이 값은 대상 엔터티 함수에서 사용하는 값과 일치해야 합니다.
connectionName - 스토리지 계정 연결 문자열을 포함하는 앱 설정의 이름입니다. 이 연결 문자열에서 나타내는 스토리지 계정은 대상 엔터티 함수에서 사용하는 계정과 동일해야 합니다. 지정하지 않으면 함수 앱에 대한 기본 스토리지 계정 연결 문자열이 사용됩니다.

참고 항목

대부분의 경우 선택적 속성을 생략하고 기본 동작을 사용하는 것이 좋습니다.

엔터티 클라이언트를 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python 함수 코드에서 직접 durable_client_input 데코레이터를 사용합니다.

엔터티 클라이언트는 function.json의 bindings 배열에 있는 다음과 같은 JSON 개체로 정의됩니다.

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

taskHub - 여러 함수 앱에서 동일한 스토리지 계정을 공유하지만 서로 격리되어야 하는 시나리오에 사용됩니다. 지정하지 않으면 host.json의 기본값이 사용됩니다. 이 값은 대상 엔터티 함수에서 사용하는 값과 일치해야 합니다.
connectionName - 스토리지 계정 연결 문자열을 포함하는 앱 설정의 이름입니다. 이 연결 문자열에서 나타내는 스토리지 계정은 대상 엔터티 함수에서 사용하는 계정과 동일해야 합니다. 지정하지 않으면 함수 앱에 대한 기본 스토리지 계정 연결 문자열이 사용됩니다.

참고 항목

대부분의 경우 선택적 속성을 생략하고 기본 동작을 사용하는 것이 좋습니다.

참고 항목

엔터티 클라이언트는 Java에서 아직 지원되지 않습니다.

클라이언트로 엔터티와 상호 작용하는 방법과 예제는 지속성 엔터티 설명서를 참조하세요.

host.json 설정

지속형 함수에 대한 구성 설정입니다.

참고 항목

Durable Functions의 모든 주요 버전은 모든 버전의 Azure Functions 런타임에서 지원됩니다. 그러나 host.json 구성의 스키마는 사용 중인 Azure Functions 런타임 및 Durable Functions 확장 버전에 따라 약간 다릅니다. 다음 예제는 Azure Functions 2.0 및 3.0과 함께 사용하기 위한 것입니다. 두 예제 모두에서 Azure Functions 1.0을 사용하는 경우 사용 가능한 설정은 동일하지만 host.json의 "durableTask" 섹션은 "extensions" 아래의 필드가 아닌 host.json 구성의 루트에 있어야 합니다.

Durable Functions 2.x
Durable Functions 1.x

{
 "extensions": {
  "durableTask": {
    "hubName": "MyTaskHub",
    "storageProvider": {
      "connectionStringName": "AzureWebJobsStorage",
      "controlQueueBatchSize": 32,
      "controlQueueBufferThreshold": 256,
      "controlQueueVisibilityTimeout": "00:05:00",
      "maxQueuePollingInterval": "00:00:30",
      "partitionCount": 4,
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "useLegacyPartitionManagement": true,
      "useTablePartitionManagement": false,
      "workItemQueueVisibilityTimeout": "00:05:00",
    },
    "tracing": {
      "traceInputsAndOutputs": false,
      "traceReplayEvents": false,
    },
    "notifications": {
      "eventGrid": {
        "topicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
        "keySettingName": "EventGridKey",
        "publishRetryCount": 3,
        "publishRetryInterval": "00:00:30",
        "publishEventTypes": [
          "Started",
          "Completed",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50,
    "storeInputsInOrchestrationHistory": false
  }
 }
}

{
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub",
      "controlQueueBatchSize": 32,
      "partitionCount": 4,
      "controlQueueVisibilityTimeout": "00:05:00",
      "workItemQueueVisibilityTimeout": "00:05:00",
      "maxConcurrentActivityFunctions": 10,
      "maxConcurrentOrchestratorFunctions": 10,
      "maxQueuePollingInterval": "00:00:30",
      "azureStorageConnectionStringName": "AzureWebJobsStorage",
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "traceInputsAndOutputs": false,
      "logReplayEvents": false,
      "eventGridTopicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
      "eventGridKeySettingName":  "EventGridKey",
      "eventGridPublishRetryCount": 3,
      "eventGridPublishRetryInterval": "00:00:30",
      "eventGridPublishEventTypes": ["Started", "Completed", "Failed", "Terminated"]
    }
  }
}

작업 허브 이름은 문자로 시작하고 문자와 숫자로만 구성되어야 합니다. 지정되지 않은 경우 함수 앱의 기본 작업 허브 이름은 TestHubName입니다. 자세한 내용은 작업 허브를 참조하세요.

속성	기본값	설명
hubName	TestHubName(Durable Functions 1.x를 사용하는 경우 DurableFunctionsHub)	여러 Durable Functions 애플리케이션이 동일한 스토리지 백 엔드를 사용하더라도 대체 작업 허브 이름을 사용하면 이러한 애플리케이션을 서로 구분할 수 있습니다.
controlQueueBatchSize	32	제어 큐에서 한 번에 끌어올 메시지의 수입니다.
controlQueueBufferThreshold	Python의 사용량 플랜: 32 JavaScript 및 C#의 사용량 플랜: 128 전용/프리미엄 계획: 256	메모리에 한 번에 버퍼링할 수 있는 컨트롤 큐 메시지의 수입니다. 이 시점에 디스패처는 추가 메시지를 큐에서 제거할 때까지 대기합니다.
partitionCount	4	제어 큐에 대한 파티션 수입니다. 1에서 16 사이의 양의 정수일 수 있습니다.
controlQueueVisibilityTimeout	5분	큐에서 제거된 제어 큐 메시지의 표시 여부 시간 제한입니다.
workItemQueueVisibilityTimeout	5분	큐에서 제거된 작업 항목 큐 메시지의 표시 여부 시간 제한입니다.
maxConcurrentActivityFunctions	사용 플랜: 10 전용/프리미엄 계획: 현재 머신의 프로세서 수의 10배	단일 호스트 인스턴스에서 동시에 처리할 수 있는 작업 함수는 최대 수입니다.
maxConcurrentOrchestratorFunctions	사용 플랜: 5 전용/프리미엄 계획: 현재 머신의 프로세서 수의 10배	단일 호스트 인스턴스에서 동시에 처리할 수 있는 오케스트레이터 함수의 최대 개수입니다.
maxQueuePollingInterval	30초	최대 제어 및 작업 항목 큐 폴링 간격(hh:mm:ss 형식)입니다. 값이 높을수록 메시지 처리 대기 시간이 길어질 수 있습니다. 값이 낮을수록 스토리지 트랜잭션이 증가하기 때문에 스토리지 비용이 높아질 수 있습니다.
connectionName(2.7.0 이상) connectionStringName(2.x) azureStorageConnectionStringName(1.x)	AzureWebJobsStorage	기본 Azure Storage 리소스에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 단일 앱 설정이 제공되는 경우 Azure Storage 연결 문자열이어야 합니다.
trackingStoreConnectionName(2.7.0 이상) trackingStoreConnectionStringName		기록 및 인스턴스 테이블에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 단일 앱 설정이 제공되는 경우 Azure Storage 연결 문자열이어야 합니다. 지정하지 않으면, `connectionStringName`(Durable 2.x) 또는 `azureStorageConnectionStringName`(Durable 1.x) 연결이 사용됩니다.
trackingStoreNamePrefix		`trackingStoreConnectionStringName`이 지정된 경우 기록 및 인스턴스 테이블에 사용할 접두사입니다. 설정하지 않는 경우 기본 접두사 값은 `DurableTask`입니다. `trackingStoreConnectionStringName`을 지정하지 않으면 기록 및 인스턴스 테이블은 `hubName` 값을 접두사로 사용하고 `trackingStoreNamePrefix`에 대한 설정은 무시됩니다.
traceInputsAndOutputs	false	함수 호출의 입출력을 추적할지 여부를 나타내는 값입니다. 함수 실행 이벤트를 추적할 때의 기본 동작은 함수 호출에 대한 직렬화된 입출력에 바이트 수를 포함하는 것입니다. 이 동작은 로그를 부풀리거나 실수로 중요한 정보를 노출하지 않으면서 입력 및 출력이 어떻게 보일지에 대한 최소한의 정보를 제공합니다. 이 속성을 true로 설정하면 기본 함수 로깅이 함수 입출력의 전체 내용을 기록하게 됩니다.
traceReplayEvents	false	Application Insights에 이벤트를 재생하는 오케스트레이션을 작성할 것인지 여부를 나타내는 값입니다.
eventGridTopicEndpoint		Azure Event Grid 사용자 지정 항목 엔드포인트의 URL입니다. 이 속성이 설정되면 오케스트레이션 수명 주기 알림 이벤트가 이 엔드포인트에 게시됩니다. 이 속성은 앱 설정 해결을 지원합니다.
eventGridKeySettingName		`EventGridTopicEndpoint`에서 Azure Event Grid 사용자 지정 항목으로 인증하는 데 사용되는 키를 포함하는 앱 설정의 이름입니다.
eventGridPublishRetryCount	0	Event Grid 항목에 게시가 실패하는 경우 다시 시도 횟수입니다.
eventGridPublishRetryInterval	5분	hh:mm:ss 형식의 Event Grid 게시 재시도 간격입니다.
eventGridPublishEventTypes		Event Grid에 게시할 이벤트 유형 목록입니다. 지정하지 않으면 모든 이벤트 유형이 게시됩니다. 허용되는 값에는 `Started`, `Completed`, `Failed`, `Terminated`가 포함됩니다.
useAppLease	true	`true`로 설정하면, 앱은 작업 허브 메시지를 처리하기 전에 앱 수준 Blob 임대를 확보해야 합니다. 자세한 내용은 재해 복구 및 지역 배포 설명서를 참조하세요. v2.3.0부터 사용할 수 있습니다.
useLegacyPartitionManagement	false	`false`로 설정하면, 확장 시 중복 함수 실행 가능성을 줄이는 파티션 관리 알고리즘을 사용합니다. v2.3.0부터 사용할 수 있습니다.
useTablePartitionManagement	false	`true`로 설정하면 Azure Storage V2 계정 비용을 절감하도록 설계된 파티션 관리 알고리즘을 사용합니다. v2.10.0부터 사용할 수 있습니다. 이 기능은 현재 미리 보기로 제공되며 사용량 플랜과 아직 호환되지 않습니다.
useGracefulShutdown	false	(미리 보기) 정상적인 종료를 사용하도록 설정하여 호스트 종료가 in-process 함수 실행에 실패할 가능성을 줄입니다.
maxEntityOperationBatchSize(2.6.1)	소비 계획: 50 전용/프리미엄 플랜: 5000	일괄 처리로 처리되는 항목 작업의 최대 수입니다. 1로 설정하면 일괄 처리가 사용하지 않도록 설정되고 각 작업 메시지는 별도의 함수 호출로 처리됩니다.
storeInputsInOrchestrationHistory	false	`true`로 설정하면 기록 테이블에 작업 입력을 저장하도록 지속성 작업 프레임워크에 지시합니다. 이렇게 하면 오케스트레이션 기록을 쿼리할 때 작업 함수 입력을 표시할 수 있습니다.

이러한 설정의 대부분은 성능 최적화를 위한 것입니다. 자세한 내용은 성능 및 크기 조정을 참조하세요.

다음 단계

인스턴스 관리에 대한 기본 제공 HTTP API 참조

다음을 통해 공유

지속성 함수의 바인딩(Azure Functions)

Python v2 프로그래밍 모델

오케스트레이션 트리거

트리거 동작

트리거 사용

트리거 샘플

작업 트리거

트리거 동작

트리거 사용

트리거 샘플

입력 및 출력 바인딩 사용

오케스트레이션 클라이언트

클라이언트 사용

엔터티 트리거

트리거 동작

엔터티 클라이언트

host.json 설정

다음 단계

피드백

추가 리소스