次の方法で共有


Azure の Durable Functions でインスタンスを管理する

Durable Functions のオーケストレーションは、実行時間の長いステートフル関数であり、組み込みの管理 API を使用して開始、照会、中断、再開、および終了できます。 インスタンスへの外部イベントの送信、インスタンス履歴の消去など、Durable Functions オーケストレーション クライアント バインドによって、他のいくつかのインスタンス管理 API も公開されます。この記事では、サポートされているすべてのインスタンス管理操作の詳細について説明します。

インスタンスを開始する

オーケストレーション クライアント バインドの start-new (または schedule-new) メソッドは、新しいオーケストレーション インスタンスを開始します。 内部的には、このメソッドは Durable Functions ストレージ プロバイダー を介してメッセージを書き込み、返します。 このメッセージは、指定した名前で オーケストレーション関数 の開始を非同期的にトリガーします。

新しいオーケストレーション インスタンスを開始するためのパラメーターは次のとおりです。

  • 名前: スケジュールするオーケストレーター関数の名前。
  • 入力: オーケストレーター関数への入力として渡す必要がある JSON シリアル化可能なデータ。
  • InstanceId: (省略可能) インスタンスの一意の ID。 このパラメーターを指定しない場合、メソッドはランダム ID を使用します。

ヒント

可能な限り、インスタンス ID にランダムな識別子を使用します。 ランダム インスタンス ID は、複数の VM 間でオーケストレーター関数をスケーリングするときに、均等な負荷分散を実現するのに役立ちます。 非ランダム インスタンス ID を使用する適切なタイミングは、ID が外部ソースから取得される必要がある場合、または シングルトン オーケストレーター パターンを実装する場合です。

次のコードは、新しいオーケストレーション インスタンスを開始する関数の例です。

[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 のバージョン に関する記事を参照してください。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

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 でこれを設定することもできます。

Core Tools コマンドは、関数アプリのルート ディレクトリから実行していることを前提としています。 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 値としての関数の入力。 showInputが false の場合、このフィールドは設定されません。
  • CustomStatus: JSON 形式のカスタム オーケストレーションの状態。
  • 出力: JSON 値としての関数の出力 (関数が完了した場合)。 オーケストレーター関数が失敗した場合、このプロパティにはエラーの詳細が含まれます。 オーケストレーター関数が中断または終了された場合、このプロパティには中断または終了の理由が含まれます (ある場合)。
  • RuntimeStatus: 次のいずれかの値。
    • 保留中: インスタンスはスケジュールされていますが、まだ実行が開始されていません。
    • 実行中: インスタンスの実行が開始されました。
    • 完了: インスタンスは正常に完了しました。
    • ContinuedAsNew: インスタンスが新しい履歴で再起動されました。 この状態は一時的な状態です。
    • 失敗: インスタンスがエラーで失敗しました。
    • 終了: インスタンスが突然停止しました。
    • 中断: インスタンスは中断され、後の時点で再開される可能性があります。
  • 履歴: オーケストレーションの実行履歴。 このフィールドは、 showHistorytrue に設定されている場合にのみ設定されます。

スケジュールされたすべてのタスクが完了、オーケストレーターが戻るまで、オーケストレーターはCompletedとしてマークされません。 つまり、オーケストレーターがreturnステートメントに到達しても、それだけでCompletedとしてマークされることはできません。 これは、 WhenAny が使用される場合に特に関連します。これらのオーケストレーターは、多くの場合、スケジュールされたすべてのタスクが実行される前に return

このメソッドは、インスタンスが存在しない場合は、 null (.NET と Java)、 undefined (JavaScript)、または None (Python) を返します。

[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 のバージョン に関する記事を参照してください。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

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 は、クエリ パラメーターに一致するオーケストレーション インスタンスを表すオブジェクトの一覧を返します。

[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 のバージョン に関する記事を参照してください。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

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

フィルターを使用してインスタンスにクエリを実行する

標準インスタンス クエリで提供できるすべての情報が本当に必要ない場合はどうでしょうか。 たとえば、オーケストレーションの作成時刻やオーケストレーション ランタイムの状態だけを探している場合はどうなりますか。 フィルターを適用することで、クエリを絞り込むことができます。

[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 のバージョン に関する記事を参照してください。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

Azure Functions Core Tools では、フィルターで durable get-instances コマンドを使用することもできます。 前述の topcontinuation-tokenconnection-string-setting、および task-hub-name パラメーターに加えて、3 つのフィルター パラメーター (created-aftercreated-before、および runtime-status) を使用できます。

現在、Core Tools コマンドは、ランタイム状態を保持するために既定の Azure Storage プロバイダー を使用する場合にのみサポートされています。

durable get-instances コマンドのパラメーターを次に示します。

  • created-after (省略可能):この日時 (UTC) より後に作成されたインスタンスを取得します。 ISO 8601 形式の datetime が受け入れられます。
  • created-before (省略可能): この日付/時刻 (UTC) より前に作成されたインスタンスを取得します。 ISO 8601 形式の datetime が受け入れられます。
  • runtime-status (省略可能): 特定の状態 (実行中や完了など) を持つインスタンスを取得します。 複数の (スペース区切り) 状態を提供できます。
  • top (省略可能): 要求ごとに取得されたインスタンスの数。 既定値は 10 です。
  • continuation-token (省略可能):取得するインスタンスのページまたはセクションを示すトークン。 各 get-instances 実行は、次のインスタンス セットにトークンを返します。
  • connection-string-setting (省略可能): 使用するストレージ接続文字列を含むアプリケーション設定の名前。 既定値は AzureWebJobsStorageです。
  • task-hub-name (省略可能):使用する Durable Functions タスク ハブの名前。 既定値は DurableFunctionsHubです。 durableTask:HubName を使用して 、host.jsonで設定することもできます。

フィルター (created-aftercreated-before、または runtime-status) を指定しない場合、コマンドはランタイムの状態や作成時間に関係なく、単に top インスタンスを取得します。

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

インスタンスを終了する

オーケストレーション インスタンスの実行に時間がかかりすぎる場合、または何らかの理由で完了する前に停止するだけで済む場合は、終了できます。

terminate API の 2 つのパラメーターは 、インスタンス ID理由 文字列であり、ログとインスタンスの状態に書き込まれます。

[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 のバージョン に関する記事を参照してください。

終了したインスタンスは、最終的に Terminated 状態に遷移します。 ただし、この移行はすぐには行われません。 代わりに、終了操作は、そのインスタンスの他の操作と共にタスク ハブにキューに入れられます。 インスタンス クエリ API を使用して、終了したインスタンスが実際にTerminated状態に達したタイミングを把握できます。

インスタンスの終了は現在伝達されません。 アクティビティ関数とサブオーケストレーションは、呼び出したオーケストレーション インスタンスを終了したかどうかに関係なく、完了まで実行されます。

インスタンスの中断と再開

オーケストレーションを一時停止すると、実行中のオーケストレーションを止めることができます。 終了とは異なり、中断したオーケストレーターは後から再開することができます。

suspend API の 2 つのパラメーターは、インスタンス ID と理由文字列であり、ログとインスタンスの状態に書き込まれます。

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

中断されたインスタンスは、最終的に Suspended 状態に遷移します。 ただし、この移行はすぐには行われません。 代わりに、中断操作は、そのインスタンスの他の操作と共にタスク ハブにキューに入れられます。 インスタンス クエリ API を使用して、実行中のインスタンスが実際に中断状態に達したタイミングを把握できます。

中断されたオーケストレーターが再開されると、その状態は Runningに戻ります。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

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"

インスタンスにイベントを送信する

一部のシナリオでは、オーケストレーター関数が外部イベントを待ち、受信する必要があります。 これが役に立つシナリオの例としては、 監視人間の操作 のシナリオがあります。

オーケストレーション クライアントの raise イベント API を使用して、実行中のインスタンスにイベント通知を送信できます。 オーケストレーションは、外部イベントの待機オーケストレーターAPIを使用して、これらのイベントを待ち受けて応答できます。

raise イベントのパラメーターは次のとおりです。

  • インスタンス ID: インスタンスの一意の ID。
  • イベント名: 送信するイベントの名前。
  • イベント データ: インスタンスに送信する JSON シリアル化可能なペイロード。
[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 のバージョン に関する記事を参照してください。

指定したインスタンス ID を持つオーケストレーション インスタンスがない場合、イベント メッセージは破棄されます。 インスタンスが存在するが、まだイベントを待機していない場合、イベントは受信して処理する準備ができるまでインスタンス状態に格納されます。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

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 トリガー関数の例を次に示します。

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

次の行で関数を呼び出します。 タイムアウトには 2 秒、再試行間隔には 0.5 秒を使用します。

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

上記の cURL コマンドは、プロジェクトに E1_HelloSequence という名前のオーケストレーター関数があることを前提としています。 HTTP トリガー関数の記述方法により、プロジェクト内のオーケストレーター関数の名前に置き換えることができます。

オーケストレーション インスタンスから応答を取得するために必要な時間に応じて、次の 2 つのケースがあります。

  • オーケストレーション インスタンスは、定義されたタイムアウト (この場合は 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}"
}

Webhook URL の形式は、実行している Azure Functions ホストのバージョンによって異なる場合があります。 上記の例は、Azure Functions 3.0 ホスト用です。

HTTP 管理 Webhook の URL を取得する

外部システムを使用して、オーケストレーションの監視を行うまたはイベントを発生させることができます。 外部システムは、 HTTP API URL 検出で説明されている既定の応答の一部である Webhook URL を介して Durable Functions と通信できます。 Webhook URL には、 オーケストレーション クライアント バインドを使用してプログラムでアクセスすることもできます。 具体的には、 HTTP 管理ペイロードの作成 API を使用して、これらの Webhook URL を含むシリアル化可能なオブジェクトを取得できます。

HTTP 管理ペイロードの作成 API には、次の 1 つのパラメーターがあります。

  • インスタンス ID: インスタンスの一意の ID。

メソッドは、次の文字列プロパティを持つオブジェクトを返します。

  • Id: オーケストレーションのインスタンス ID ( InstanceId 入力と同じである必要があります)。
  • StatusQueryGetUri: オーケストレーション インスタンスの状態 URL。
  • SendEventPostUri: オーケストレーション インスタンスの "イベントの発生" URL。
  • TerminatePostUri: オーケストレーション インスタンスの "terminate" URL。
  • PurgeHistoryDeleteUri: オーケストレーション インスタンスの "消去履歴" URL。
  • suspendPostUri: オーケストレーション インスタンスの "中断" URL。
  • resumePostUri: オーケストレーション インスタンスの "resume" URL。

関数は、次の例に示すように、これらのオブジェクトのインスタンスを外部システムに送信して、対応するオーケストレーションのイベントを監視または発生させることができます。

[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 のバージョン に関する記事を参照してください。

インスタンスの巻き戻し (プレビュー)

予期しない理由でオーケストレーションエラーが発生した場合は、その目的のために構築された API を使用して、インスタンスを以前は正常な状態に 巻き戻 すことができます。

この API は、適切なエラー処理と再試行ポリシーに代わるものではありません。 代わりに、予期しない理由でオーケストレーション インスタンスが失敗した場合にのみ使用することを目的としています。 Failed以外の状態のオーケストレーション (たとえば、RunningPendingTerminatedCompleted) を "巻き戻す" ことはできません。 エラー処理と再試行ポリシーの詳細については、 エラー処理 に関する記事を参照してください。

オーケストレーションを実行中の状態に戻すには、オーケストレーション クライアント バインドRewindAsync (.NET) または rewind (JavaScript) メソッドを使用します。 このメソッドは、オーケストレーションエラーの原因となったアクティビティまたはサブオーケストレーションの実行エラーも再実行します。

たとえば、一連の 人間による承認を含むワークフローがあるとします。 承認が必要であることをユーザーに通知し、リアルタイムの応答を待機する一連のアクティビティ関数があるとします。 すべての承認アクティビティが応答を受信したかタイムアウトになった後、無効なデータベース接続文字列など、アプリケーションの構成ミスによって別のアクティビティが失敗したとします。 その結果、ワークフローの深部でオーケストレーションエラーが発生します。 RewindAsync (.NET) または rewind (JavaScript) API を使用すると、アプリケーション管理者は構成エラーを修正し、失敗したオーケストレーションをエラーの直前の状態に戻すことができます。 人間とのやり取りの手順を再承認する必要はありません。これでオーケストレーションを正常に完了できます。

巻き戻し機能では、永続的タイマーを使用するオーケストレーション インスタンスの巻き戻しはサポートされていません。

[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 のバージョン に関する記事を参照してください。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

また、Core Tools の func durable rewind コマンド を使用して、オーケストレーション インスタンスを直接巻き戻すこともできます。

現在、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 を使用します。

この最初の例では、1 つのオーケストレーション インスタンスを消去する方法を示します。

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

次の例は、指定した時間間隔後に完了したすべてのオーケストレーション インスタンスの履歴を消去するタイマーによってトリガーされる関数を示しています。 この場合、30 日以上前に完了したすべてのインスタンスのデータが削除されます。 この関数例は、1 日に 1 回、午後 12 時 (UTC) に実行するようにスケジュールされています。

[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 のバージョン に関する記事を参照してください。

消去履歴操作を成功させるには、ターゲット インスタンスのランタイム状態が [完了]、[ 終了]、または [失敗] である必要があります。

Azure Functions Core Tools (Azure ファンクションズ コア ツール)

Core Tools の func durable purge-history コマンド を使用して、オーケストレーション インスタンスの履歴を消去できます。 前のセクションの 2 番目の C# の例と同様に、指定した時間間隔で作成されたすべてのオーケストレーション インスタンスの履歴が消去されます。 消去されたインスタンスをさらに実行時の状態でフィルターできます。

現在、Core Tools コマンドは、ランタイム状態を保持するために既定の Azure Storage プロバイダー を使用する場合にのみサポートされています。

durable purge-history コマンドには、いくつかのパラメーターがあります。

  • created-after (省略可能):この日時 (UTC) より後に作成されたインスタンスの履歴を消去します。 ISO 8601 形式の datetime が受け入れられます。
  • created-before (省略可能):この日付/時刻 (UTC) より前に作成されたインスタンスの履歴を消去します。 ISO 8601 形式の datetime が受け入れられます。
  • 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 ストレージ テーブル、キュー、BLOB など、特定のタスク ハブに関連付けられているすべてのストレージ 成果物を削除できます。

現在、Core Tools コマンドは、ランタイム状態を保持するために既定の Azure Storage プロバイダー を使用する場合にのみサポートされています。

durable delete-task-hub コマンドには、次の 2 つのパラメーターがあります。

  • connection-string-setting (省略可能): 使用するストレージ接続文字列を含むアプリケーション設定の名前。 既定値は AzureWebJobsStorageです。
  • task-hub-name (省略可能):使用する Durable Functions タスク ハブの名前。 既定では、 host.json ファイル内のタスク ハブ名が使用されます。

次のコマンドは、 UserTest タスク ハブに関連付けられているすべての Azure ストレージ データを削除します。

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

次のステップ