Durable Task のシングルトンオーケストレーター

バックグラウンドジョブでは、多くの場合、特定のオーケストレーターのインスタンスが一度に 1 つだけ実行され、重複するオーケストレーションが同時に実行されないようにする必要があります。このシングルトンパターンを Durable Functions または Durable Task SDK で実装するには、オーケストレーターの作成時に特定のインスタンス ID を割り当て、その ID を持つインスタンスが既に実行されているかどうかを確認してから、新しいインスタンスを開始します。

この記事では、サポートされている各言語のコード例を使用してシングルトンオーケストレーターを実装する方法について説明します。

[前提条件]

Durable Task オーケストレーションとタスクハブに関する知識
既存のDurable Functionsまたは Durable Task SDK プロジェクト

注

シングルトンパターンには潜在的な競合状態があります。 2 つのクライアントがチェックアンドスタートロジックを同時に実行すると、両方の呼び出しで成功が報告される可能性がありますが、実際に開始されるのはオーケストレーションインスタンスが 1 つだけです。要件によっては、望ましくない副作用が発生する可能性があります。厳密な単一インスタンスの保証が必要な場合は、ロックメカニズムを追加することを検討してください。

Important

現在、PowerShell Durable Task SDK は使用できません。

シングルトンオーケストレーターの例

次の例は、シングルトンバックグラウンドジョブオーケストレーションを作成する HTTP トリガー関数を示しています。このコードは、指定されたインスタンス ID に対してアクティブなインスタンスが 1 つだけ存在することを確認しようとします。

[Function("HttpStartSingle")]
public static async Task<HttpResponseData> RunSingle(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = "orchestrators/{functionName}/{instanceId}")] HttpRequestData req,
    [DurableClient] DurableTaskClient starter,
    string functionName,
    string instanceId,
    FunctionContext executionContext)
{
    ILogger logger = executionContext.GetLogger("HttpStartSingle");

    // Check if an instance with the specified ID already exists or an existing one stopped running(completed/failed/terminated).
    OrchestrationMetadata? existingInstance = await starter.GetInstanceAsync(instanceId, getInputsAndOutputs: false);
    if (existingInstance == null 
    || existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Completed 
    || existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Failed 
    || existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Terminated)
    {
        // An instance with the specified ID doesn't exist or an existing one stopped running, create one.
        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        await starter.ScheduleNewOrchestrationInstanceAsync(functionName, requestBody, new StartOrchestrationOptions { InstanceId = instanceId });
        logger.LogInformation($"Started orchestration with ID = '{instanceId}'.");
        return await starter.CreateCheckStatusResponseAsync(req, instanceId);
    }
    else
    {
        // An instance with the specified ID exists or an existing one still running, don't create one.
        var response = req.CreateResponse(HttpStatusCode.Conflict);
        await response.WriteStringAsync($"An instance with ID '{instanceId}' already exists.");
        return response;
    }
}

注

前の C# コードは、分離されたワーカーモデル用です。これは、.NET アプリに推奨されるモデルです。インプロセスワーカーモデルと分離ワーカーモデルの違いの詳細については、Durable Functions バージョンに関する記事を参照してください。

Important

この JavaScript の例では、function.jsonを使用する Node.js プログラミングモデル v3 を使用します 。 Node.js プログラミングモデル v4 (現在の既定値) を使用している場合は、代わりに v4 コード優先パターンを使用します。

function.json

{
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{functionName}/{instanceId}",
      "methods": ["post"]
    },
    {
      "name": "starter",
      "type": "orchestrationClient",
      "direction": "in"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    }
  ]
}

index.js

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

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

    const instanceId = req.params.instanceId;
    const functionName = req.params.functionName;

    // Check if an instance with the specified ID already exists or an existing one stopped running(completed/failed/terminated).
    const existingInstance = await client.getStatus(instanceId);
    if (!existingInstance 
        || existingInstance.runtimeStatus == "Completed" 
        || existingInstance.runtimeStatus == "Failed" 
        || existingInstance.runtimeStatus == "Terminated") {
        // An instance with the specified ID doesn't exist or an existing one stopped running, create one.
        const eventData = req.body;
        await client.startNew(functionName, instanceId, eventData);
        context.log(`Started orchestration with ID = '${instanceId}'.`);
        return client.createCheckStatusResponse(req, instanceId);
    } else {
        // An instance with the specified ID exists or an existing one still running, don't create one.
        return {
            status: 409,
            body: `An instance with ID '${instanceId}' already exists.`,
        };
    }
};

function_app.py

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

app = df.DFApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.route(route="orchestrators/{functionName}/{instanceId}", methods=["POST"])
@app.durable_client_input(client_name="client")
async def http_start_single(req: func.HttpRequest, client):
    instance_id = req.route_params["instanceId"]
    function_name = req.route_params["functionName"]

    existing_instance = await client.get_status(instance_id)

    if not existing_instance or existing_instance.runtime_status in [
        df.OrchestrationRuntimeStatus.Completed,
        df.OrchestrationRuntimeStatus.Failed,
        df.OrchestrationRuntimeStatus.Terminated,
    ]:
        event_data = req.get_body()
        instance_id = await client.start_new(function_name, instance_id, event_data)
        logging.info(f"Started orchestration with ID = '{instance_id}'.")
        return client.create_check_status_response(req, instance_id)

    return func.HttpResponse(
        body=f"An instance with ID '{instance_id}' already exists.",
        status_code=409,
    )

using namespace System.Net

param($Request, $TriggerMetadata)

$FunctionName = $Request.Params.FunctionName
$InstanceId = $Request.Params.InstanceId

# Check if an instance with the specified ID already exists
$existingInstance = Get-DurableStatus -InstanceId $InstanceId

if (-not $existingInstance -or 
    $existingInstance.RuntimeStatus -eq "Completed" -or 
    $existingInstance.RuntimeStatus -eq "Failed" -or 
    $existingInstance.RuntimeStatus -eq "Terminated") {

    # An instance with the specified ID doesn't exist or stopped running, create one
    $InstanceId = Start-DurableOrchestration -FunctionName $FunctionName -InstanceId $InstanceId -Input $Request.Body
    Write-Host "Started orchestration with ID = '$InstanceId'."

    $Response = New-DurableOrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
    Push-OutputBinding -Name Response -Value $Response
}
else {
    # An instance with the specified ID exists or still running
    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
        StatusCode = [HttpStatusCode]::Conflict
        Body = "An instance with ID '$InstanceId' already exists."
    })
}

@FunctionName("HttpStartSingle")
public HttpResponseMessage runSingle(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}/{instanceId}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {

    String instanceId = req.getHeaders().getOrDefault("instanceId", "singleton-job");
    DurableTaskClient client = durableContext.getClient();

    // Check to see if an instance with this ID is already running
    OrchestrationMetadata metadata = client.getInstanceMetadata(instanceId, false);
    if (metadata == null || !metadata.isRunning()) {
        // No such instance exists or it finished - create a new one.
        // De-dupe is handled automatically in the storage layer if another
        // function tries to also use this instance ID.
        client.scheduleNewOrchestrationInstance("MyOrchestration", null, instanceId);
        return durableContext.createCheckStatusResponse(req, instanceId);
    }

    return req.createResponseBuilder(HttpStatus.CONFLICT)
            .body("An instance with ID '" + instanceId + "' already exists.")
            .build();
}

次の例は、Durable Task SDK を使用してシングルトンオーケストレーションを作成する方法を示しています。このコードは、指定されたインスタンス ID に対してアクティブなインスタンスが 1 つだけ存在することを確認しようとします。

using Microsoft.DurableTask.Client;

// Check if an instance with the specified ID already exists
string instanceId = "singleton-job";
OrchestrationMetadata? existingInstance = await client.GetInstanceAsync(instanceId, getInputsAndOutputs: false);

if (existingInstance == null ||
    existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Completed ||
    existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Failed ||
    existingInstance.RuntimeStatus == OrchestrationRuntimeStatus.Terminated)
{
    // An instance with the specified ID doesn't exist or an existing one stopped running, create one.
    await client.ScheduleNewOrchestrationInstanceAsync("MyOrchestration", input, new StartOrchestrationOptions(instanceId));
    Console.WriteLine($"Started orchestration with ID = '{instanceId}'.");
}
else
{
    // An instance with the specified ID exists or an existing one still running.
    Console.WriteLine($"An instance with ID '{instanceId}' already exists.");
}

from durabletask.azuremanaged.client import DurableTaskSchedulerClient

instance_id = "singleton-job"

# Check if an instance with the specified ID already exists
existing_instance = client.get_orchestration_state(instance_id)

if (existing_instance is None or
    existing_instance.runtime_status in ['COMPLETED', 'FAILED', 'TERMINATED']):
    # An instance with the specified ID doesn't exist or an existing one stopped running, create one.
    client.schedule_new_orchestration(my_orchestration, input=input_data, instance_id=instance_id)
    print(f"Started orchestration with ID = '{instance_id}'.")
else:
    # An instance with the specified ID exists or an existing one still running.
    print(f"An instance with ID '{instance_id}' already exists.")

import com.microsoft.durabletask.DurableTaskClient;
import com.microsoft.durabletask.OrchestrationMetadata;

String instanceId = "singleton-job";

// Check to see if an instance with this ID is already running
OrchestrationMetadata existingInstance = client.getInstanceMetadata(instanceId, false);

if (existingInstance == null || !existingInstance.isRunning()) {
    // An instance doesn't exist or finished - create one
    client.scheduleNewOrchestrationInstance("MyOrchestration", input, instanceId);
    System.out.println("Started orchestration with ID = '" + instanceId + "'.");
} else {
    // An instance with the specified ID exists and is still running
    System.out.println("An instance with ID '" + instanceId + "' already exists.");
}

import { createAzureManagedClient } from "@microsoft/durabletask-js-azuremanaged";
import { OrchestrationStatus } from "@microsoft/durabletask-js";

const client = createAzureManagedClient(connectionString);

const instanceId = "singleton-job";

// Check if an instance with the specified ID already exists
const existingInstance = await client.getOrchestrationState(instanceId, false);

if (!existingInstance ||
    existingInstance.runtimeStatus === OrchestrationStatus.COMPLETED ||
    existingInstance.runtimeStatus === OrchestrationStatus.FAILED ||
    existingInstance.runtimeStatus === OrchestrationStatus.TERMINATED) {
    // An instance with the specified ID doesn't exist or an existing one stopped running, create one.
    await client.scheduleNewOrchestration("MyOrchestration", input, instanceId);
    console.log(`Started orchestration with ID = '${instanceId}'.`);
} else {
    // An instance with the specified ID exists or an existing one still running.
    console.log(`An instance with ID '${instanceId}' already exists.`);
}

シングルトンパターンのしくみ

インスタンス ID はタスクハブ内で一意であるため、既知の固定 ID を使用してオーケストレーションをスケジュールし、その状態を確認すると、最初に重複する同時実行が防止されます。既定では、インスタンス ID はランダムに生成される GUID です。ただし、前の例では、特定のインスタンス ID が渡されます。その後、コードはオーケストレーションインスタンスのメタデータをフェッチして、その ID を持つインスタンスが既に実行されているかどうかを確認します。そのようなインスタンスが実行されていない場合は、その ID で新しいインスタンスが作成されます。

オーケストレーター関数自体は、任意のパターン (開始および完了する標準関数、または継続的に実行される永続的オーケストレーション ) を使用できます。シングルトンパターンは、同時に実行されるインスタンスの数のみを制御します。

次のステップ

オーケストレーションのネイティブ HTTP 機能について説明します

Durable Task SDK で始める

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-28

Durable Task のシングルトン オーケストレーター

[前提条件]

シングルトン オーケストレーターの例

シングルトン パターンのしくみ

次のステップ

フィードバック

その他のリソース

Durable Task のシングルトンオーケストレーター

シングルトンオーケストレーターの例

シングルトンパターンのしくみ