Azure에서 Durable Functions의 인스턴스 관리

Durable Functions의 오케스트레이션은 기본 제공 관리 API를 사용하여 시작, 쿼리, 일시 중단, 다시 시작 및 종료할 수 있는 장기 실행 상태 저장 함수입니다. 외부 이벤트를 인스턴스로 전송, 인스턴스 기록 제거 등과 같은 Durable Functions 오케스트레이션 클라이언트 바인딩에 의해 다른 여러 인스턴스 관리 API도 노출됩니다. 이 문서에서는 지원되는 모든 인스턴스 관리 작업에 대해 자세히 설명합니다.

인스턴스 시작

오케스트레이션 클라이언트 바인딩의 start-new(또는 schedule-new) 메서드는 새 오케스트레이션 인스턴스를 시작합니다. 내부적으로 이 메서드는 Durable Functions 스토리지 공급자 를 통해 메시지를 작성한 다음 반환합니다. 이 메시지는 지정된 이름을 사용하여 오케스트레이션 함수 의 시작을 비동기적으로 트리거합니다.

새 오케스트레이션 인스턴스를 시작하기 위한 매개 변수는 다음과 같습니다.

• 이름: 예약할 오케스트레이터 함수의 이름입니다.
• 입력: 오케스트레이터 함수에 대한 입력으로 전달되어야 하는 JSON 직렬화 가능 데이터입니다.
• InstanceId: (선택 사항) 인스턴스의 고유 ID입니다. 이 매개 변수를 지정하지 않으면 메서드는 임의 ID를 사용합니다.

팁 (조언)

가능하면 인스턴스 ID에 대해 임의 식별자를 사용합니다. 임의 인스턴스 ID는 여러 VM에서 오케스트레이터 함수의 크기를 조정할 때 동일한 부하 분산을 보장하는 데 도움이 됩니다. 임의가 아닌 인스턴스 ID를 사용해야 하는 적절한 시기는 ID가 외부 소스에서 제공될 때나 싱글톤 오케스트레이터 패턴을 구현할 때입니다.

다음 코드는 새 오케스트레이션 인스턴스를 시작하는 예제 함수입니다.

C#

[FunctionName("HelloWorldQueueTrigger")]
public static async Task Run(
    [QueueTrigger("start-queue")] string input,
    [DurableClient] IDurableOrchestrationClient starter,
    ILogger log)
{
    string instanceId = await starter.StartNewAsync("HelloWorld", input);
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
}

비고

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

JavaScript

달리 지정하지 않는 한 이 페이지의 예제에서는 다음 function.jsonHTTP 트리거를 사용합니다.

function.json

{
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

비고

이 예제에서는 Durable Functions 버전 2.x를 대상으로 합니다. 버전 1.x에서는 durableClient 대신 orchestrationClient을 사용합니다.

index.js

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

module.exports = async function(context, input) {
    const client = df.getClient(context);

    const instanceId = await client.startNew("HelloWorld", undefined, input);
    context.log(`Started orchestration with ID = ${instanceId}.`);
};

파이썬

달리 지정하지 않는 한 이 페이지의 예제에서는 다음 function.jsonHTTP 트리거를 사용합니다.

function.json

{
  "scriptFile": "__init__.py",
  "bindings": [    
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

비고

이 예제에서는 Durable Functions 버전 2.x를 대상으로 합니다. 버전 1.x에서는 durableClient 대신 orchestrationClient를 사용합니다.

__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('HelloWorld', None, None)
    logging.log(f"Started orchestration with ID = ${instance_id}.")

PowerShell

달리 지정하지 않는 한 이 페이지의 예제에서는 다음 function.jsonHTTP 트리거를 사용합니다.

function.json

{
  "bindings": [    
    {
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "Response",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

비고

이 예제에서는 Durable Functions 버전 2.x를 대상으로 합니다. 버전 1.x에서는 durableClient 대신 orchestrationClient를 사용합니다.

run.ps1

param($Request, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld'
Write-Host "Started orchestration with ID = '$InstanceId'"

java

@FunctionName("HelloWorldQueueTrigger")
public void helloWorldQueueTrigger(
        @QueueTrigger(name = "input", queueName = "start-queue", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    String instanceID = client.scheduleNewOrchestrationInstance("HelloWorld");
    context.getLogger().info("Scheduled orchestration with ID = " + instanceID);
}

오케스트레이터가 시작될 때까지 기다린 후 함수에서 반환하는 방식을 원하신다면, waitForInstanceStart() 메서드를 사용할 수도 있습니다.

// wait up to 30 seconds for the scheduled orchestration to enter the "Running" state
client.waitForInstanceStart(instanceID, Duration.ofSeconds(30));

Azure Functions 핵심 도구

다음 매개 변수를 사용하는 Core Tools의 func durable start-new 명령을 사용하여 인스턴스를 직접 시작할 수도 있습니다.

• function-name (필수): 시작할 함수의 이름입니다.
• input (선택 사항): 인라인 또는 JSON 파일을 통해 함수에 입력합니다. 파일의 경우, @를 사용하여 파일 경로에 접두사를 추가하십시오. 예를 들어, @path/to/file.json와 같이 합니다.
• id (선택 사항): 오케스트레이션 인스턴스의 ID입니다. 이 매개 변수를 지정하지 않으면 명령은 임의의 GUID를 사용합니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. durableTask:HubName을 사용하여 host.json 설정할 수도 있습니다.

비고

핵심 도구 명령은 함수 앱의 루트 디렉터리에서 실행 중이라고 가정합니다. connection-string-setting 및 task-hub-name 매개 변수를 명시적으로 제공하는 경우, 모든 디렉터리에서 명령을 실행할 수 있습니다. 함수 앱 호스트를 실행하지 않고 이러한 명령을 실행할 수 있지만 호스트가 실행되지 않는 한 일부 효과를 관찰할 수 없습니다. 예를 들어 start-new 명령은 시작 메시지를 대상 작업 허브에 큐에 넣지만 메시지를 처리할 수 있는 함수 앱 호스트 프로세스가 실행되지 않는 한 오케스트레이션은 실제로 실행되지 않습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

다음 명령은 HelloWorld라는 함수를 시작하고 파일 counter-data.json 의 내용을 전달합니다.

func durable start-new --function-name HelloWorld --input @counter-data.json --task-hub-name TestTaskHub

쿼리 인스턴스

새 오케스트레이션 인스턴스를 시작한 후에는 런타임 상태를 쿼리하여 실행 중인지, 완료되었는지 또는 실패했는지를 확인해야 합니다.

오케스트레이션 클라이언트 바인딩의 get-status 메서드는 오케스트레이션 인스턴스의 상태를 쿼리합니다.

instanceId (필수), showHistory (선택 사항), showHistoryOutput (선택 사항), showInput (선택 사항)을 매개 변수로 사용합니다.

• showHistory: 로 true설정하면 응답에 실행 기록이 포함됩니다.
• showHistoryOutput: 로 true설정하면 실행 기록에 활동 출력이 포함됩니다.
• showInput: 로 false설정하면 응답에 함수의 입력이 포함되지 않습니다. 기본값은 true입니다.

메서드는 다음 속성을 가진 개체를 반환합니다.

• 이름: 오케스트레이터 함수의 이름입니다.
• InstanceId: 오케스트레이션의 인스턴스 ID입니다(입력과 instanceId 동일해야 합니다).
• CreatedTime: 오케스트레이터 함수가 실행되기 시작한 시간입니다.
• LastUpdatedTime: 오케스트레이션에서 마지막으로 검사점을 설정한 시간입니다.
• 입력: JSON 값으로 함수의 입력입니다. false이면 showInput 이 필드가 채워지지 않습니다.
• CustomStatus: JSON 형식의 사용자 지정 오케스트레이션 상태입니다.
• 출력: 함수를 JSON 값으로 출력합니다(함수가 완료된 경우). 오케스트레이터 함수가 실패한 경우 이 속성에는 오류 세부 정보가 포함됩니다. 오케스트레이터 함수가 일시 중단되거나 종료된 경우 이 속성에는 일시 중단 또는 종료 이유(있는 경우)가 포함됩니다.
• RuntimeStatus: 다음 값 중 하나입니다.
  • 보류 중: 인스턴스가 예약되었지만 아직 실행이 시작되지 않았습니다.
  • 실행 중: 인스턴스가 실행되기 시작했습니다.
  • 완료됨: 인스턴스가 정상적으로 완료되었습니다.
  • ContinuedAsNew: 인스턴스가 새로운 이력으로 다시 시작되었습니다. 이 상태는 일시적인 상태입니다.
  • 실패: 인스턴스가 오류로 실패했습니다.
  • 종료됨: 인스턴스가 갑자기 중지되었습니다.
  • 일시 중단됨: 인스턴스가 일시 중단되었으며 나중에 다시 시작될 수 있습니다.
• 기록: 오케스트레이션의 실행 기록입니다. 이 필드는 showHistory가 true로 설정된 경우에만 채워집니다.

비고

오케스트레이터는 예약된 모든 작업이 완료되고 오케스트레이터가 반환될 때까지 표시되지 Completed 않습니다. 즉, 오케스트레이터가 자신의 return 문에 도달하는 것만으로는 그것이 Completed로 표시되기에 충분하지 않습니다. 이는 특히 WhenAny가 사용되는 경우에 관련이 있습니다. 예약된 모든 작업이 실행되기 전에 이러한 오케스트레이터가 자주 return를 수행합니다.

이 메서드는 인스턴스가 없으면 (.NET 및 Java), undefined (JavaScript) 또는 None (Python)을 반환 null 합니다.

C#

[FunctionName("GetStatus")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("check-status-queue")] string instanceId)
{
    DurableOrchestrationStatus status = await client.GetStatusAsync(instanceId);
    // do something based on the current status.
}

비고

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

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const status = await client.getStatus(instanceId);
    // do something based on the current status.
    // example: if status.runtimeStatus === df.OrchestrationRuntimeStatus.Running: ...
}

인스턴스 시작에 대한 function.json 구성 을 참조하세요.

파이썬

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    status = await client.get_status(instance_id)
    # do something based on the current status
    # example: if (existing_instance.runtime_status is df.OrchestrationRuntimeStatus.Running) { ...

PowerShell

param($Request, $TriggerMetadata)

# Get instanceid from body
$InstanceId = $Request.Body.InstanceId

$Status = Get-DurableStatus -InstanceId $InstanceId -ShowHistory -ShowHistoryOutput -ShowInput
Write-Host "Status: $($Status | ConvertTo-Json)"

# Do something based on status
# example: if ($Status.runtimeStatus -eq 'Running') { ... }

java

@FunctionName("GetStatus")
public void getStatus(
        @QueueTrigger(name = "instanceID", queueName = "check-status-queue", connection = "Storage") String instanceID,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    OrchestrationMetadata metadata = client.getInstanceMetadata(instanceID, false);
    if (metadata != null) {
        OrchestrationRuntimeStatus status = metadata.getRuntimeStatus();
        switch (status) {
            // do something based on the current status
        }
    }
}

Azure Functions 핵심 도구

Core Tools의 명령을 사용하여 func durable get-runtime-status 오케스트레이션 인스턴스의 상태를 직접 가져올 수도 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

durable get-runtime-status 명령은 다음 매개 변수를 사용합니다.

• id (필수): 오케스트레이션 인스턴스의 ID입니다.
• show-input (선택 사항): 설정 true하면 응답에 함수의 입력이 포함됩니다. 기본값은 false입니다.
• show-output (선택 사항): 설정 true하면 응답에 함수의 출력이 포함됩니다. 기본값은 false입니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. durableTask:HubName을 사용하여 host.json설정할 수도 있습니다.

다음 명령은 오케스트레이션 인스턴스 ID가 0ab8c55a66644d68a3a8b220b12d209c인 인스턴스의 상태(입력 및 출력 포함)를 검색합니다. 함수 앱의 func 루트 디렉터리에서 명령을 실행한다고 가정합니다.

func durable get-runtime-status --id 0ab8c55a66644d68a3a8b220b12d209c --show-input true --show-output true

명령을 durable get-history 사용하여 오케스트레이션 인스턴스의 기록을 검색할 수 있습니다. 사용되는 매개 변수는 다음과 같습니다.

• id (필수): 오케스트레이션 인스턴스의 ID입니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. ** durableTask:HubName을 사용하여 host.json에서 설정할 수도 있습니다.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

모든 인스턴스 쿼리

언어 SDK의 API를 사용하여 작업 허브에 있는 모든 오케스트레이션 인스턴스의 상태를 쿼리할 수 있습니다. 이 "list-instances" 또는 "get-status" API는 쿼리 매개 변수와 일치하는 오케스트레이션 인스턴스를 나타내는 개체 목록을 반환합니다.

C#

[FunctionName("GetAllStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    var noFilter = new OrchestrationStatusQueryCondition();
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        noFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
    
    // Note: ListInstancesAsync only returns the first page of results.
    // To request additional pages provide the result.ContinuationToken
    // to the OrchestrationStatusQueryCondition's ContinuationToken property.
}

비고

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

JavaScript

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

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const instances = await client.getStatusAll();
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

function.json 구성의 시작 인스턴스를 참조하세요.

파이썬

import logging
import json
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)

    instances = await client.get_status_all()

    for instance in instances:
        logging.log(json.dumps(instance))

시작 인스턴스를 function.json 구성에서 참조하세요.

PowerShell

비고

이 기능은 현재 PowerShell에서 지원되지 않지만 Durable Functions HTTP API를 사용하여 수행할 수 있습니다.

java

@FunctionName("GetAllStatus")
public String getAllStatus(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery noFilter = new OrchestrationStatusQuery();
    OrchestrationStatusQueryResult result = client.queryInstances(noFilter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

Azure Functions 핵심 도구

Core Tools의 명령을 사용하여 인스턴스를 직접 쿼리할 func durable get-instances 수도 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

durable get-instances 명령은 다음 매개 변수를 사용합니다.

• top (선택 사항): 이 명령은 페이징을 지원합니다. 이 매개 변수는 요청당 검색된 인스턴스 수에 해당합니다. 기본값은 10입니다.
• continuation-token (선택 사항): 검색할 인스턴스의 페이지 또는 섹션을 나타내는 토큰입니다. 각 get-instances 실행은 다음 인스턴스 집합에 토큰을 반환합니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. durableTask:HubName을 사용하여 host.json설정할 수도 있습니다.

func durable get-instances

필터를 사용하여 인스턴스 쿼리

표준 인스턴스 쿼리에서 제공할 수 있는 모든 정보가 실제로 필요하지 않은 경우 어떻게 해야 할까요? 예를 들어 오케스트레이션 생성 시간 또는 오케스트레이션 런타임 상태를 찾고 있다면 어떻게 해야 할까요? 필터를 적용하여 쿼리 범위를 좁힐 수 있습니다.

C#

[FunctionName("QueryStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    // Get the first 100 running or pending instances that were created between 7 and 1 day(s) ago
    var queryFilter = new OrchestrationStatusQueryCondition
    {
        RuntimeStatus = new[]
        {
            OrchestrationRuntimeStatus.Pending,
            OrchestrationRuntimeStatus.Running,
        },
        CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
        CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
        PageSize = 100,
    };
    
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        queryFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
}

비고

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

JavaScript

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

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const runtimeStatus = [
        df.OrchestrationRuntimeStatus.Completed,
        df.OrchestrationRuntimeStatus.Running,
    ];
    const instances = await client.getStatusBy(
        new Date(2021, 3, 10, 10, 1, 0),
        new Date(2021, 3, 10, 10, 23, 59),
        runtimeStatus
    );
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

시작 인스턴스를 function.json 구성에 대해 참조하세요.

파이썬

import logging
from datetime import datetime
import json
import azure.functions as func
import azure.durable_functions as df
from azure.durable_functions.models.OrchestrationRuntimeStatus import OrchestrationRuntimeStatus

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

    instances = await client.get_status_by(
        datetime(2021, 3, 10, 10, 1, 0),
        datetime(2021, 3, 10, 10, 23, 59),
        runtime_status
    )

    for instance in instances:
        logging.log(json.dumps(instance))

PowerShell

비고

이 기능은 현재 PowerShell에서 지원되지 않지만 Durable Functions HTTP API를 사용하여 수행할 수 있습니다.

java

@FunctionName("GetRunningInstances")
public String getRunningInstances(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery filter = new OrchestrationStatusQuery()
        .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.PENDING, OrchestrationRuntimeStatus.RUNNING))
        .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(7)))
        .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(1)));
    OrchestrationStatusQueryResult result = client.queryInstances(filter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

Azure Functions 핵심 도구

Azure Functions 핵심 도구에서 필터와 durable get-instances 함께 명령을 사용할 수도 있습니다. 앞에서 언급한 top, , continuation-tokenconnection-string-setting및 task-hub-name 매개 변수 외에도 세 개의 필터 매개 변수(created-after및created-beforeruntime-status)를 사용할 수 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

다음은 명령에 대한 매개 변수입니다 durable get-instances .

• created-after (선택 사항): 이 날짜/시간(UTC) 이후에 만든 인스턴스를 검색합니다. ISO 8601 형식의 날짜/시간이 허용되었습니다.
• created-before (선택 사항): 이 날짜/시간(UTC) 이전에 만든 인스턴스를 검색합니다. ISO 8601 형식의 날짜/시간이 허용되었습니다.
• runtime-status (선택 사항): 특정 상태의 인스턴스를 검색합니다(예: 실행 중 또는 완료됨). 여러(공백으로 구분된) 상태를 제공할 수 있습니다.
• top (선택 사항): 요청당 검색된 인스턴스 수입니다. 기본값은 10입니다.
• continuation-token (선택 사항): 검색할 인스턴스의 페이지 또는 섹션을 나타내는 토큰입니다. 각 get-instances 실행은 다음 인스턴스 집합에 토큰을 반환합니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. durableTask:HubName을 사용하여 host.json설정할 수도 있습니다.

필터(created-after, created-before, 또는 runtime-status)를 제공하지 않으면 명령은 런타임 상태나 생성 시간과 관계없이 top 인스턴스를 단순히 검색합니다.

func durable get-instances --created-after 2021-03-10T13:57:31Z --created-before  2021-03-10T23:59Z --top 15

인스턴스 종료

실행하는 데 너무 오래 걸리는 오케스트레이션 인스턴스가 있거나 어떤 이유로든 완료하기 전에 중지해야 하는 경우 종료할 수 있습니다.

종료 API에 대한 두 매개 변수는 로그 및 인스턴스 상태에 기록되는 인스턴스 ID 및 이유 문자열입니다.

C#

[FunctionName("TerminateInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("terminate-queue")] string instanceId)
{
    string reason = "Found a bug";
    return client.TerminateAsync(instanceId, reason);
}

비고

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

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Found a bug";
    return client.terminate(instanceId, reason);
};

인스턴스 시작에 대해 function.json 구성을 참조하세요.

파이썬

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    reason = "Found a bug"
    return await client.terminate(instance_id, reason)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$Reason = 'Found a bug'

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

java

@FunctionName("TerminateInstance")
public void terminateInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String reason = "Found a bug";
    durableContext.getClient().terminate(instanceID, reason);
}

종료된 인스턴스는 결국 상태로 전환 Terminated 됩니다. 그러나 이 전환은 즉시 발생하지 않습니다. 대신 종료 작업은 해당 인스턴스에 대한 다른 작업과 함께 작업 허브에 큐에 대기됩니다. 인스턴스 쿼리 API를 사용하여 종료된 인스턴스가 실제로 상태에 도달한 Terminated 시기를 알 수 있습니다.

비고

인스턴스 종료는 현재 전파되지 않습니다. 작업 함수 및 하위 오케스트레이션은 호출한 오케스트레이션 인스턴스를 종료했는지 여부에 관계없이 완료될 때 실행됩니다.

인스턴스 일시 중단 및 다시 시작

오케스트레이션을 일시 중단하면 실행 중인 오케스트레이션을 중지할 수 있습니다. 종료와 달리 일시 중단된 오케스트레이터는 나중에 다시 시작할 수 있습니다.

일시 중단 API에 대한 두 매개 변수는 로그 및 인스턴스 상태에 기록되는 인스턴스 ID 및 이유 문자열입니다.

C#

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // To resume an orchestration
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    // To suspend an orchestration
    const suspendReason = "Need to pause workflow";
    await client.suspend(instanceId, suspendReason);

    // To resume an orchestration
    const resumeReason = "Continue workflow";
    await client.resume(instanceId, resumeReason);
};

파이썬

import azure.functions as func
import azure.durable_functions as df
from datetime import timedelta

async def main(req: func.HttpRequest, starter: str, instance_id: str):
    client = df.DurableOrchestrationClient(starter)

    # To suspend an orchestration
    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # To resume an orchestration
    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

PowerShell

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

# To suspend an orchestration
$SuspendReason = 'Need to pause workflow'
Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# To resume an orchestration
$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

비고

이 기능은 독립 실행형 Durable Functions PowerShell SDK 에서만 사용할 수 있습니다. 마이그레이션 가이드와 함께 독립 실행형 SDK와 레거시 기본 제공 SDK 간의 차이점을 확인합니다.

java

@FunctionName("SuspendResumeInstance")
public void suspendResumeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    DurableTaskClient client = durableContext.getClient();  

    // To suspend an orchestration
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // To resume an orchestration
    String resumeReason = "Continue workflow";
    client.resumeInstance(instanceID, resumeReason);
}

일시 중단된 인스턴스는 결국 Suspended 상태로 전환됩니다. 그러나 이 전환은 즉시 발생하지 않습니다. 대신 일시 중단 작업은 해당 인스턴스에 대한 다른 작업과 함께 작업 허브에 큐에 대기됩니다. 인스턴스 쿼리 API를 사용하여 실행 중인 인스턴스가 실제로 일시 중단된 상태에 도달한 시기를 알 수 있습니다.

일시 중단된 오케스트레이터가 다시 시작되면 해당 상태가 다시 .로 Running변경됩니다.

Azure Functions 핵심 도구

Core Tools의 명령을 사용하여 오케스트레이션 인스턴스를 직접 종료할 func durable terminate 수도 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

durable terminate 명령은 다음 매개 변수를 사용합니다.

• id (필수): 종료할 오케스트레이션 인스턴스의 ID입니다.
• reason (선택 사항): 종료 이유입니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. durableTask:HubName을 사용하여 host.json설정할 수도 있습니다.

다음 명령은 ID가 0ab8c55a66644d68a3a8b220b12d209c인 오케스트레이션 인스턴스를 종료합니다.

func durable terminate --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Found a bug"

인스턴스에 이벤트 보내기

일부 시나리오에서는 오케스트레이터 함수가 외부 이벤트를 수신 대기해야 합니다. 이 시나리오가 유용한 예제 시나리오에는 모니터링 및 사용자 상호 작용 시나리오가 포함됩니다.

오케스트레이션 클라이언트의 이벤트 발생 API를 사용하여 실행 중인 인스턴스에 이벤트 알림을 보낼 수 있습니다. 오케스트레이션은 외부 이벤트 오케스트레이터 API 에 대한 대기 를 사용하여 이러한 이벤트를 수신 대기하고 응답할 수 있습니다.

raise 이벤트에 대한 매개 변수는 다음과 같습니다.

• 인스턴스 ID: 인스턴스의 고유 ID입니다.
• 이벤트 이름: 보낼 이벤트의 이름입니다.
• 이벤트 데이터: 인스턴스로 보낼 JSON 직렬화 가능 페이로드입니다.

C#

[FunctionName("RaiseEvent")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("event-queue")] string instanceId)
{
    int[] eventData = new int[] { 1, 2, 3 };
    return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}

비고

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

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const eventData = [ 1, 2, 3 ];
    return client.raiseEvent(instanceId, "MyEvent", eventData);
};

시작 인스턴스에 대해 function.json 구성을 참조하세요.

파이썬

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    event_data = [1, 2 ,3]
    return await client.raise_event(instance_id, 'MyEvent', event_data)

PowerShell

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$EventName = 'MyEvent'
$EventData = @(1,2,3)

Send-DurableExternalEvent -InstanceId $InstanceId -EventName $EventName -EventData $EventData

java

@FunctionName("RaiseEvent")
public void raiseEvent(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String eventName = "MyEvent";
    int[] eventData = { 1, 2, 3 };
    durableContext.getClient().raiseEvent(instanceID, eventName, eventData);
}

비고

지정된 인스턴스 ID를 가진 오케스트레이션 인스턴스가 없으면 이벤트 메시지가 삭제됩니다. 인스턴스가 있지만 이벤트를 아직 기다리지 않는 경우 이벤트를 수신하고 처리할 준비가 될 때까지 인스턴스 상태에 저장됩니다.

Azure Functions 핵심 도구

Core Tools의 func durable raise-event 명령을 사용하여 오케스트레이션 인스턴스에 직접 이벤트를 발생시킬 수도 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

durable raise-event 명령은 다음 매개 변수를 사용합니다.

• id (필수): 오케스트레이션 인스턴스의 ID입니다.
• event-name: 발생할 이벤트의 이름입니다.
• event-data (선택 사항): 오케스트레이션 인스턴스로 보낼 데이터입니다. JSON 파일의 경로이거나 명령줄에서 직접 데이터를 제공할 수 있습니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본값은 DurableFunctionsHub입니다. durableTask:HubName을 사용하여 host.json설정할 수도 있습니다.

func durable raise-event --id 0ab8c55a66644d68a3a8b220b12d209c --event-name MyEvent --event-data @eventdata.json

func durable raise-event --id 1234567 --event-name MyOtherEvent --event-data 3

오케스트레이션 완료 대기

장기 실행되는 오케스트레이션에서는 오케스트레이션 결과를 기다려야 할 수 있습니다. 이러한 경우 오케스트레이션에서 시간 제한 기간을 정의할 수도 있습니다. 시간 제한을 초과하면 오케스트레이션 상태가 결과 대신 반환되어야 합니다.

"완료 대기 또는 확인 상태 응답 만들기" API를 사용하여 오케스트레이션 인스턴스의 실제 출력을 동기적으로 가져올 수 있습니다. 기본적으로 이 메서드의 기본 시간 제한은 10초이고 폴링 간격은 1초입니다.

다음은 이 API를 사용하는 방법을 보여 주는 예제 HTTP 트리거 함수입니다.

C#

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See LICENSE in the project root for license information.

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace VSSample
{
    public static class HttpSyncStart
    {
        private const string Timeout = "timeout";
        private const string RetryInterval = "retryInterval";

        [FunctionName("HttpSyncStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}/wait")]
            HttpRequestMessage req,
            [DurableClient] IDurableOrchestrationClient 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}'.");

            TimeSpan timeout = GetTimeSpan(req, Timeout) ?? TimeSpan.FromSeconds(30);
            TimeSpan retryInterval = GetTimeSpan(req, RetryInterval) ?? TimeSpan.FromSeconds(1);
            
            return await starter.WaitForCompletionOrCreateCheckStatusResponseAsync(
                req,
                instanceId,
                timeout,
                retryInterval);
        }

        private static TimeSpan? GetTimeSpan(HttpRequestMessage request, string queryParameterName)
        {
            string queryParameterStringValue = request.RequestUri.ParseQueryString()[queryParameterName];
            if (string.IsNullOrEmpty(queryParameterStringValue))
            {
                return null;
            }

            return TimeSpan.FromSeconds(double.Parse(queryParameterStringValue));
        }
    }
}

JavaScript

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

const timeout = "timeout";
const retryInterval = "retryInterval";

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

    const timeoutInMilliseconds = getTimeInSeconds(req, timeout) || 30000;
    const retryIntervalInMilliseconds = getTimeInSeconds(req, retryInterval) || 1000;

    const response = client.waitForCompletionOrCreateCheckStatusResponse(
        context.bindingData.req,
        instanceId,
        timeoutInMilliseconds,
        retryIntervalInMilliseconds
    );
    return response;
};

function getTimeInSeconds(req, queryParameterName) {
    const queryValue = req.query[queryParameterName];
    return queryValue
        ? queryValue * 1000 // expected to be in seconds
        : undefined;
}

function.json 구성에 대한 시작 인스턴스를 참조하세요.

파이썬

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

timeout = "timeout"
retry_interval = "retryInterval"

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, req.get_body())
    logging.log(f"Started orchestration with ID = '${instance_id}'.")

    timeout_in_milliseconds = get_time_in_seconds(req, timeout)
    timeout_in_milliseconds = timeout_in_milliseconds if timeout_in_milliseconds != None else 30000
    retry_interval_in_milliseconds = get_time_in_seconds(req, retry_interval)
    retry_interval_in_milliseconds = retry_interval_in_milliseconds if retry_interval_in_milliseconds != None else 1000

    return await client.wait_for_completion_or_create_check_status_response(
        req,
        instance_id,
        timeout_in_milliseconds,
        retry_interval_in_milliseconds
    )

def get_time_in_seconds(req: func.HttpRequest, query_parameter_name: str):
    query_value = req.params.get(query_parameter_name)
    return query_value if query_value != None else 1000

PowerShell

비고

PowerShell에는 현재 이 시나리오에 대한 기본 제공 명령이 없습니다.

java

Java에는 현재 이 시나리오에 대한 단일 메서드가 없습니다. 그러나 몇 가지 추가 코드 줄을 사용하여 구현할 수 있습니다.

@FunctionName("HttpStartAndWait")
public HttpResponseMessage httpStartAndWait(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}/wait", methods = {HttpMethod.POST}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("functionName") String functionName,
        final ExecutionContext context) {

    DurableTaskClient client = durableContext.getClient();
    String instanceId = client.scheduleNewOrchestrationInstance(functionName);
    context.getLogger().info("Created new Java orchestration with instance ID = " + instanceId);
    try {
        String timeoutString = req.getQueryParameters().get("timeout");
        Integer timeoutInSeconds = Integer.parseInt(timeoutString);
        OrchestrationMetadata orchestration = client.waitForInstanceCompletion(
                instanceId,
                Duration.ofSeconds(timeoutInSeconds),
                true /* getInputsAndOutputs */);
        return req.createResponseBuilder(HttpStatus.OK)
                .body(orchestration.getSerializedOutput())
                .header("Content-Type", "application/json")
                .build();
    } catch (TimeoutException timeoutEx) {
        // timeout expired - return a 202 response
        return durableContext.createCheckStatusResponse(req, instanceId);
    }
}

다음 줄을 사용하여 함수를 호출합니다. 제한 시간에는 2초, 재시도 간격에는 0.5초를 사용합니다.

curl -X POST "http://localhost:7071/orchestrators/E1_HelloSequence/wait?timeout=2&retryInterval=0.5"

비고

위의 cURL 명령은 프로젝트에 이름이 지정된 E1_HelloSequence 오케스트레이터 함수가 있다고 가정합니다. HTTP 트리거 함수를 작성하는 방법 때문에 프로젝트의 오케스트레이터 함수 이름으로 바꿀 수 있습니다.

오케스트레이션 인스턴스에서 응답을 가져오는 데 필요한 시간에 따라 다음 두 가지 경우가 있습니다.

• 오케스트레이션 인스턴스는 정의된 시간 제한(이 경우 2초) 내에 완료되고 응답은 동기적으로 전달되는 실제 오케스트레이션 인스턴스 출력입니다.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:14:29 GMT
Transfer-Encoding: chunked

[
    "Hello Tokyo!",
    "Hello Seattle!",
    "Hello London!"
]

• 오케스트레이션 인스턴스는 정의된 시간 제한 내에서 완료할 수 없으며 응답은 HTTP API URL 검색에 설명된 기본값입니다.

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:13:51 GMT
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
Retry-After: 10
Transfer-Encoding: chunked

{
    "id": "d3b72dddefce4e758d92f4d411567177",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/suspend?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/resume?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
}

비고

실행 중인 Azure Functions 호스트의 버전에 따라 웹후크 URL의 형식이 다를 수 있습니다. 앞의 예제는 Azure Functions 3.0 호스트에 대한 것입니다.

HTTP 관리 웹후크 URL 검색

외부 시스템을 사용하여 오케스트레이션에 대한 이벤트를 모니터링하거나 발생시킬 수 있습니다. 외부 시스템은 HTTP API URL 검색에 설명된 기본 응답의 일부인 웹후크 URL을 통해 Durable Functions와 통신할 수 있습니다. 또는 오케스트레이션 클라이언트 바인딩을 사용하여 프로그래밍 방식으로 웹후크 URL에 액세스할 수 있습니다. 특히 HTTP 관리 페이로드 만들기 API를 사용하여 이러한 웹후크 URL을 포함하는 직렬화 가능한 개체를 가져올 수 있습니다.

HTTP 관리 페이로드 만들기 API에는 하나의 매개 변수가 있습니다.

• 인스턴스 ID: 인스턴스의 고유 ID입니다.

메서드는 다음 문자열 속성을 사용하여 개체를 반환합니다.

• ID: 오케스트레이션의 인스턴스 ID입니다(입력과 InstanceId 동일해야 합니다).
• StatusQueryGetUri: 오케스트레이션 인스턴스의 상태 URL입니다.
• SendEventPostUri: 오케스트레이션 인스턴스의 "이벤트 발생" URL입니다.
• TerminatePostUri: 오케스트레이션 인스턴스의 "종료" URL입니다.
• PurgeHistoryDeleteUri: 오케스트레이션 인스턴스의 "제거 기록" URL입니다.
• suspendPostUri: 오케스트레이션 인스턴스의 "일시 중단" URL입니다.
• resumePostUri: 오케스트레이션 인스턴스의 "resume" URL입니다.

함수는 다음 예제에서 보여준 것처럼 이러한 개체의 인스턴스를 외부 시스템으로 보내 해당 오케스트레이션에서 이벤트를 모니터링하거나 이벤트를 발생시킬 수 있습니다.

C#

[FunctionName("SendInstanceInfo")]
public static void SendInstanceInfo(
    [ActivityTrigger] IDurableActivityContext ctx,
    [DurableClient] IDurableOrchestrationClient client,
    [CosmosDB(
        databaseName: "MonitorDB",
        containerName: "HttpManagementPayloads",
        Connection = "CosmosDBConnectionSetting")]out dynamic document)
{
    HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);

    // send the payload to Azure Cosmos DB
    document = new { Payload = payload, id = ctx.InstanceId };
}

비고

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

JavaScript

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

modules.exports = async function(context, ctx) {
    const client = df.getClient(context);

    const payload = client.createHttpManagementPayload(ctx.instanceId);

    // send the payload to Azure Cosmos DB
    context.bindings.document = JSON.stringify({
        id: ctx.instanceId,
        payload,
    });
};

function.json 구성에 대해 시작 인스턴스를 참조하세요.

파이썬

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.cosmosdb.cdb.Document:
    client = df.DurableOrchestrationClient(starter)

    payload = client.create_check_status_response(req, instance_id).get_body().decode()

    return func.cosmosdb.CosmosDBConverter.encode({
        id: instance_id,
        payload: payload
    })

PowerShell

using namespace System.Net

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId
$Response = New-DurableOrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
Push-OutputBinding -Name Response -Value $Response

java

비고

이 기능은 현재 Java에서 지원되지 않습니다.

인스턴스 되감기(미리 보기)

예기치 않은 이유로 오케스트레이션 오류가 발생하는 경우 해당 용도로 빌드된 API를 사용하여 인스턴스를 이전에 정상 상태로 되감 을 수 있습니다.

비고

이 API는 적절한 오류 처리 및 재시도 정책을 대체하기 위한 것이 아닙니다. 대신 예기치 않은 이유로 오케스트레이션 인스턴스가 실패하는 경우에만 사용됩니다. Failed 이외의 상태(예: Running, Pending, Terminated, Completed)의 오케스트레이션은 "되감기"할 수 없습니다. 오류 처리 및 다시 시도 정책에 대한 자세한 내용은 오류 처리 문서를 참조하세요.

RewindAsync오케스트레이션 클라이언트 바인딩의 (.NET) 또는 rewind (JavaScript) 메서드를 사용하여 오케스트레이션을 다시 실행 상태로 전환합니다. 또한 이 메서드는 오케스트레이션 실패를 발생시킨 작업 또는 하위 오케스트레이션 실행 오류를 다시 실행합니다.

예를 들어 일련의 사용자 승인과 관련된 워크플로가 있다고 가정해 보겠습니다. 승인이 필요하다고 누군가에게 알리고 실시간 응답을 기다리는 일련의 활동 함수가 있다고 가정해 보겠습니다. 모든 승인 활동이 응답을 받거나 시간이 초과되면 잘못된 데이터베이스 연결 문자열과 같은 애플리케이션의 구성이 잘못되어 다른 작업이 실패한다고 가정합니다. 그 결과 워크플로 깊은 부분에서 오케스트레이션 실패가 발생합니다. RewindAsync (.NET) 또는 rewind (JavaScript) API를 사용하면 애플리케이션 관리자가 구성 오류를 수정하고 실패한 오케스트레이션을 실패 바로 전에 상태로 되감을 수 있습니다. 사용자 상호 작용 단계를 다시 승인할 필요가 없으며 이제 오케스트레이션이 성공적으로 완료될 수 있습니다.

비고

되감기 기능은 지속성 타이머를 사용하는 오케스트레이션 인스턴스 되감기를 지원하지 않습니다.

C#

[FunctionName("RewindInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("rewind-queue")] string instanceId)
{
    string reason = "Orchestrator failed and needs to be revived.";
    return client.RewindAsync(instanceId, reason);
}

비고

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

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Orchestrator failed and needs to be revived.";
    return client.rewind(instanceId, reason);
};

인스턴스 시작에 대한 function.json 구성 을 참조하세요.

파이썬

비고

이 기능은 현재 Python에서 지원되지 않습니다.

PowerShell

비고

이 기능은 현재 PowerShell에서 지원되지 않습니다.

java

비고

이 기능은 현재 Java에서 지원되지 않습니다.

Azure Functions 핵심 도구

Core Tools의 명령을 사용하여 오케스트레이션 인스턴스를 직접 되돌릴 수도 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

durable rewind 명령은 다음 매개 변수를 사용합니다.

• id (필수): 오케스트레이션 인스턴스의 ID입니다.
• reason (선택 사항): 오케스트레이션 인스턴스를 되감는 이유입니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본적으로 host.json 파일의 작업 허브 이름이 사용됩니다.

func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."

인스턴스 기록 제거

오케스트레이션과 연결된 모든 데이터를 제거하려면 인스턴스 기록을 제거할 수 있습니다. 예를 들어 완료된 인스턴스와 연결된 스토리지 리소스를 삭제할 수 있습니다. 이렇게 하려면 오케스트레이션 클라이언트에서 정의한 제거 인스턴스 API를 사용합니다.

이 첫 번째 예제에서는 단일 오케스트레이션 인스턴스를 제거하는 방법을 보여 줍니다.

C#

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("purge-queue")] string instanceId)
{
    return client.PurgeInstanceHistoryAsync(instanceId);
}

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);
    return client.purgeInstanceHistory(instanceId);
};

인스턴스 시작에 대한 function.json 구성 을 참조하세요.

파이썬

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    return await client.purge_instance_history(instance_id)

PowerShell

비고

이 기능은 현재 PowerShell에서 지원되지 않지만 Durable Functions HTTP API를 사용하여 수행할 수 있습니다.

java

@FunctionName("PurgeInstance")
public HttpResponseMessage purgeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}, route = "purge/{instanceID}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("instanceID") String instanceID) {
    PurgeResult result = durableContext.getClient().purgeInstance(instanceID);
    if (result.getDeletedInstanceCount() == 0) {
        return req.createResponseBuilder(HttpStatus.NOT_FOUND)
                .body("No completed instance with ID '" + instanceID + "' was found!")
                .build();
    } else {
        return req.createResponseBuilder(HttpStatus.OK)
                .body("Successfully purged data for " + instanceID)
                .build();
    }
}

다음 예제에서는 지정된 시간 간격 후에 완료된 모든 오케스트레이션 인스턴스의 기록을 제거하는 타이머 트리거 함수를 보여 줍니다. 이 경우 30일 이상 전에 완료된 모든 인스턴스에 대한 데이터가 제거됩니다. 이 예제 함수는 UTC 오후 12:00에 하루에 한 번 실행되도록 예약됩니다.

C#

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [TimerTrigger("0 0 12 * * *")] TimerInfo myTimer)
{
    return client.PurgeInstanceHistoryAsync(
        DateTime.MinValue,
        DateTime.UtcNow.AddDays(-30),  
        new List<OrchestrationStatus>
        {
            OrchestrationStatus.Completed
        });
}

비고

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

JavaScript

이 메서드를 purgeInstanceHistoryBy 사용하여 여러 인스턴스에 대한 인스턴스 기록을 조건부로 제거할 수 있습니다.

function.json

{
  "bindings": [
    {
      "schedule": "0 0 12 * * *",
      "name": "myTimer",
      "type": "timerTrigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

비고

이 예제에서는 Durable Functions 버전 2.x를 대상으로 합니다. 버전 1.x에서는 durableClient 대신 orchestrationClient를 사용합니다.

index.js

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

module.exports = async function (context, myTimer) {
    const client = df.getClient(context);
    const createdTimeFrom = new Date(0);
    const createdTimeTo = new Date().setDate(today.getDate() - 30);
    const runtimeStatuses = [ df.OrchestrationRuntimeStatus.Completed ];
    return client.purgeInstanceHistoryBy(createdTimeFrom, createdTimeTo, runtimeStatuses);
};

PowerShell

비고

이 기능은 현재 PowerShell에서 지원되지 않지만 Durable Functions HTTP API를 사용하여 수행할 수 있습니다.

파이썬

import azure.functions as func
import azure.durable_functions as df
from azure.durable_functions.models.DurableOrchestrationStatus import OrchestrationRuntimeStatus
from datetime import datetime, timedelta

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    created_time_from = datetime.min
    created_time_to = datetime.today() + timedelta(days = -30)
    runtime_statuses = [OrchestrationRuntimeStatus.Completed]

    return await client.purge_instance_history_by(created_time_from, created_time_to, runtime_statuses)

java

@FunctionName("PurgeInstances")
public void purgeInstances(
        @TimerTrigger(name = "purgeTimer", schedule = "0 0 12 * * *") String timerInfo,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        ExecutionContext context) throws TimeoutException {
    PurgeInstanceCriteria criteria = new PurgeInstanceCriteria()
            .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(60)))
            .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(30)))
            .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.COMPLETED));
    PurgeResult result = durableContext.getClient().purgeInstances(criteria);
    context.getLogger().info(String.format("Purged %d instance(s)", result.getDeletedInstanceCount()));
}

비고

제거 기록 작업이 성공하려면 대상 인스턴스의 런타임 상태를 완료, 종료 또는 실패해야 합니다.

Azure Functions 핵심 도구

Core Tools의 명령을 사용하여 func durable purge-history 오케스트레이션 인스턴스의 기록을 제거할 수 있습니다. 이전 섹션의 두 번째 C# 예제와 마찬가지로 지정된 시간 간격 동안 생성된 모든 오케스트레이션 인스턴스의 기록을 제거합니다. 제거된 인스턴스를 런타임 상태로 추가로 필터링할 수 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

명령에 durable purge-history 는 다음과 같은 몇 가지 매개 변수가 있습니다.

• created-after (선택 사항): 이 날짜/시간(UTC) 이후에 만든 인스턴스의 기록을 제거합니다. ISO 8601 형식의 날짜/시간이 허용되었습니다.
• created-before (선택 사항): 이 날짜/시간(UTC) 이전에 만든 인스턴스의 기록을 제거합니다. ISO 8601 형식의 날짜/시간이 허용되었습니다.
• runtime-status (선택 사항): 특정 상태(예: 실행 중 또는 완료됨)를 사용하여 인스턴스의 기록을 제거합니다. 여러(공백으로 구분된) 상태를 제공할 수 있습니다.
• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본적으로 host.json 파일의 작업 허브 이름이 사용됩니다.

다음 명령은 2021년 11월 14일 오후 7시 35분(UTC) 이전에 만든 실패한 모든 인스턴스의 기록을 삭제합니다.

func durable purge-history --created-before 2021-11-14T19:35:00.0000000Z --runtime-status failed

작업 허브 삭제

Core Tools의 func durable delete-task-hub 명령을 사용하여 Azure Storage 테이블, 큐 및 Blob을 포함하여 특정 작업 허브와 연결된 모든 스토리지 아티팩트를 삭제할 수 있습니다.

비고

Core Tools 명령은 현재 런타임 상태를 유지하기 위해 기본 Azure Storage 공급자 를 사용하는 경우에만 지원됩니다.

명령에는 durable delete-task-hub 두 개의 매개 변수가 있습니다.

• connection-string-setting (선택 사항): 사용할 스토리지 연결 문자열을 포함하는 애플리케이션 설정의 이름입니다. 기본값은 AzureWebJobsStorage입니다.
• task-hub-name (선택 사항): 사용할 Durable Functions 작업 허브의 이름입니다. 기본적으로 host.json 파일의 작업 허브 이름이 사용됩니다.

다음 명령은 작업 허브와 연결된 모든 Azure Storage 데이터를 삭제합니다 UserTest .

func durable delete-task-hub --task-hub-name UserTest

다음 단계

버전 관리 처리 방법 알아보기

인스턴스 관리를 위한 기본 제공 HTTP API 참조