Durable Functions (Azure Functions) での HTTP APIHTTP APIs in Durable Functions (Azure Functions)

Durable Task 拡張機能は、次のタスクの実行で使用できる一連の HTTP API を公開します。The Durable Task extension exposes a set of HTTP APIs that can be used to perform the following tasks:

  • オーケストレーション インスタンスの状態を取得します。Fetch the status of an orchestration instance.
  • 待機中のオーケストレーション インスタンスにイベントを送信します。Send an event to a waiting orchestration instance.
  • 実行中のオーケストレーション インスタンスを終了します。Terminate a running orchestration instance.

これらの各 HTTP API は、Durable Task 拡張機能によって直接処理される webhook 操作です。Each of these HTTP APIs is a webhook operation that is handled directly by the Durable Task extension. 関数アプリの関数に固有のものではありません。They are not specific to any function in the function app.

注意

これらの操作は、DurableOrchestrationClient クラスのインスタンス管理 API を使用して直接呼び出すこともできます。These operations can also be invoked directly using the instance management APIs on the DurableOrchestrationClient class. 詳しくは、インスタンス管理に関する記事をご覧ください。For more information, see Instance Management.

HTTP API URL の検出HTTP API URL discovery

DurableOrchestrationClient クラスでは、CreateCheckStatusResponse API を公開します。これは、サポートされるすべての操作へのリンクを含む HTTP 応答ペイロードを生成するのに使用できます。The DurableOrchestrationClient class exposes a CreateCheckStatusResponse API that can be used to generate an HTTP response payload containing links to all the supported operations. この API の使用方法を示す HTTP トリガー関数の例を次に示します。Here is an example HTTP-trigger function that demonstrates how to use this API:

C#C#

#r "Microsoft.Azure.WebJobs.Extensions.DurableTask"
#r "Microsoft.Extensions.Logging"
#r "Newtonsoft.Json"

using System.Net;
using System.Net.Http.Headers;

public static async Task<HttpResponseMessage> Run(
    HttpRequestMessage req,
    DurableOrchestrationClient starter,
    string functionName,
    ILogger log)
{
    // Function input comes from the request content.
    dynamic eventData = await req.Content.ReadAsAsync<object>();
    string instanceId = await starter.StartNewAsync(functionName, eventData);
    
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
    
    return starter.CreateCheckStatusResponse(req, instanceId);
}

JavaScript (Functions 2.x のみ)JavaScript (Functions 2.x only)

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

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

    return client.createCheckStatusResponse(context.bindingData.req, instanceId);
};

これらの関数例では、次の JSON 応答データが生成されます。These example functions produce the following JSON response data. すべてのフィールドのデータ型は string です。The data type of all fields is string.

フィールドField 説明Description
id オーケストレーション インスタンスの ID。The ID of the orchestration instance.
statusQueryGetUri オーケストレーション インスタンスの状態の URL。The status URL of the orchestration instance.
sendEventPostUri オーケストレーション インスタンスの "イベント発生" URL。The "raise event" URL of the orchestration instance.
terminatePostUri オーケストレーション インスタンスの "終了" URL。The "terminate" URL of the orchestration instance.
rewindPostUri オーケストレーション インスタンスの "rewind" URL。The "rewind" URL of the orchestration instance.

次は応答の例です。Here is an example response:

HTTP/1.1 202 Accepted
Content-Length: 923
Content-Type: application/json; charset=utf-8
Location: https://{host}/runtime/webhooks/durabletask/instances/34ce9a28a6834d8492ce6a295f1a80e2?taskHub=DurableFunctionsHub&connection=Storage&code=XXX

{
    "id":"34ce9a28a6834d8492ce6a295f1a80e2",
    "statusQueryGetUri":"https://{host}/runtime/webhooks/durabletask/instances/34ce9a28a6834d8492ce6a295f1a80e2?taskHub=DurableFunctionsHub&connection=Storage&code=XXX",
    "sendEventPostUri":"https://{host}/runtime/webhooks/durabletask/instances/34ce9a28a6834d8492ce6a295f1a80e2/raiseEvent/{eventName}?taskHub=DurableFunctionsHub&connection=Storage&code=XXX",
    "terminatePostUri":"https://{host}/runtime/webhooks/durabletask/instances/34ce9a28a6834d8492ce6a295f1a80e2/terminate?reason={text}&taskHub=DurableFunctionsHub&connection=Storage&code=XXX",
    "rewindPostUri":"https://{host}/runtime/webhooks/durabletask/instances/34ce9a28a6834d8492ce6a295f1a80e2/rewind?reason={text}&taskHub=DurableFunctionsHub&connection=Storage&code=XXX"
}

注意

webhook URL の形式は、実行している Azure Functions ホストのバージョンによって異なる場合があります。The format of the webhook URLs may differ depending on which version of the Azure Functions host you are running. 上記の例は、Azure Functions 2.x ホスト用の形式です。The above example is for the Azure Functions 2.x host.

非同期操作の追跡Async operation tracking

上記の HTTP 応答は、Durable Functions で実行時間の長い HTTP 非同期 API を実装するのに役立つように設計されています。The HTTP response mentioned previously is designed to help implement long-running HTTP async APIs with Durable Functions. これは、ポーリング コンシューマー パターンと呼ばれる場合もあります。This is sometimes referred to as the Polling Consumer Pattern. クライアント/サーバー フローは次のように動作します。The client/server flow works as follows:

  1. クライアントが、オーケストレーター関数など、実行時間の長いプロセスを開始する HTTP 要求を発行します。The client issues an HTTP request to start a long running process, such as an orchestrator function.
  2. 対象の HTTP トリガーが、statusQueryGetUri 値の Location ヘッダーを含む HTTP 202 応答を返します。The target HTTP trigger returns an HTTP 202 response with a Location header with the statusQueryGetUri value.
  3. クライアントが Location ヘッダー内の URL をポーリングします。The client polls the URL in the Location header. クライアントは引き続き、Location ヘッダーを含む HTTP 202 応答を参照します。It continues to see HTTP 202 responses with a Location header.
  4. インスタンスが完了 (または失敗) すると、Location ヘッダー内のエンドポイントから HTTP 200 が返されます。When the instance completes (or fails), the endpoint in the Location header returns HTTP 200.

このプロトコルでは、HTTP エンドポイントのポーリングと Location ヘッダーのフォローをサポートする、外部のクライアントまたはサービスでの実行時間の長いプロセスを調整できます。This protocol allows coordinating long-running processes with external clients or services that support polling an HTTP endpoint and following the Location header. 基本の部分は、Durable Functions HTTP API に既に組み込まれています。The fundamental pieces are already built into the Durable Functions HTTP APIs.

注意

既定では、Azure Logic Apps によって提供される HTTP ベースのすべてのアクションで、標準的な非同期操作パターンがサポートされています。By default, all HTTP-based actions provided by Azure Logic Apps support the standard asynchronous operation pattern. この機能により、実行時間の長い Durable Functions を Logic Apps ワークフローの一部として組み込むことができます。This capability makes it possible to embed a long-running durable function as part of a Logic Apps workflow. Logic Apps での非同期 HTTP パターンのサポートについて詳しくは、Azure Logic Apps ワークフロー アクションおよびトリガーに関するドキュメントをご覧ください。More details on Logic Apps support for asynchronous HTTP patterns can be found in the Azure Logic Apps workflow actions and triggers documentation.

HTTP API リファレンスHTTP API reference

拡張機能によって実装されるすべての HTTP API では、次のパラメーターを指定します。All HTTP APIs implemented by the extension take the following parameters. すべてのパラメーターのデータ型は string です。The data type of all parameters is string.

パラメーターParameter パラメーターのタイプParameter Type 説明Description
taskHub クエリ文字列Query string タスク ハブの名前。The name of the task hub. 指定しない場合は、現在の関数アプリのタスク ハブの名前が想定されます。If not specified, the current function app's task hub name is assumed.
connection クエリ文字列Query string ストレージ アカウントの接続文字列の名前The name of the connection string for the storage account. 指定しない場合は、関数アプリの既定の接続文字列が想定されます。If not specified, the default connection string for the function app is assumed.
systemKey クエリ文字列Query string API の呼び出しに必要な承認キー。The authorization key required to invoke the API.

systemKey は、Azure Functions ホストによって自動生成される承認キーです。systemKey is an authorization key auto-generated by the Azure Functions host. このキーにより、Durable Task 拡張機能 API へのアクセスが特別に許可されます。また、このキーは他の承認キーと同じ方法で管理できます。It specifically grants access to the Durable Task extension APIs and can be managed the same way as other authorization keys. 前述の CreateCheckStatusResponse API を使用すると、systemKey 値を最も簡単に検出できます。The simplest way to discover the systemKey value is by using the CreateCheckStatusResponse API mentioned previously.

以降のセクションで、この拡張機能でサポートされる特定の HTTP API とその使用方法の例について説明します。The next few sections cover the specific HTTP APIs supported by the extension and provide examples of how they can be used.

インスタンスの状態を取得するGet instance status

指定されたオーケストレーション インスタンスの状態を取得します。Gets the status of a specified orchestration instance.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

フィールドField パラメーターのタイプParameter type 説明Description
instanceId URLURL オーケストレーション インスタンスの ID。The ID of the orchestration instance.
showInput クエリ文字列Query string 省略可能なパラメーター。Optional parameter. false に設定した場合、関数の入力は応答ペイロードに含まれなくなります。If set to false, the function input will not be included in the response payload.
showHistory クエリ文字列Query string 省略可能なパラメーター。Optional parameter. true に設定した場合、オーケストレーションの実行履歴が応答ペイロードに含まれます。If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput クエリ文字列Query string 省略可能なパラメーター。Optional parameter. true に設定した場合、関数の出力はオーケストレーションの実行履歴に含まれます。If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以降に作成されたインスタンスにフィルター処理されます。When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以前に作成されたインスタンスにフィルター処理されます。When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、返されるインスタンスの一覧がランタイム状態に基づいてフィルター処理されます。When specified, filters the list of returned instances based on their runtime status. 考えられるランタイム状態の値の一覧を参照するには、インスタンスのクエリの実行に関するトピックをご覧ください。To see the list of possible runtime status values, see the Querying instances topic.

ResponseResponse

返される可能性がある状態コード値は、いくつかあります。Several possible status code values can be returned.

  • HTTP 200 (OK) :指定されたインスタンスが完了状態。HTTP 200 (OK): The specified instance is in a completed state.
  • HTTP 202 (Accepted) :指定されたインスタンスが処理中。HTTP 202 (Accepted): The specified instance is in progress.
  • HTTP 400 (Bad Request) :指定されたインスタンスが失敗したか終了した。HTTP 400 (Bad Request): The specified instance failed or was terminated.
  • HTTP 404 (Not Found) :指定されたインスタンスが存在しないか実行開始されていない。HTTP 404 (Not Found): The specified instance doesn't exist or has not started running.
  • HTTP 500 (Internal Server Error) :指定されたインスタンスがハンドルされない例外で失敗した。HTTP 500 (Internal Server Error): The specified instance failed with an unhandled exception.

HTTP 200HTTP 202 の場合の応答ペイロードは、次のフィールドを持つ JSON オブジェクトです。The response payload for the HTTP 200 and HTTP 202 cases is a JSON object with the following fields:

フィールドField データ型Data type 説明Description
runtimeStatus stringstring インスタンスの実行時状態。The runtime status of the instance. 値には、RunningPendingFailedCanceledTerminatedCompleted があります。Values include Running, Pending, Failed, Canceled, Terminated, Completed.
input JSONJSON インスタンスを初期化するために使用される JSON データ。The JSON data used to initialize the instance. このフィールドは、showInput クエリ文字列パラメーターが falseに設定されている場合は、null です。This field is null if the showInput query string parameter is set to false.
customStatus JSONJSON カスタム オーケストレーションの状態に使用された JSON データ。The JSON data used for custom orchestration status. セットされていない場合、このフィールドはnullです。This field is null if not set.
output JSONJSON インスタンスの JSON の出力。The JSON output of the instance. インスタンスが完了状態でない場合、このフィールドは null です。This field is null if the instance is not in a completed state.
createdTime stringstring インスタンスが作成された時刻。The time at which the instance was created. ISO 8601 の拡張された表記を使用します。Uses ISO 8601 extended notation.
lastUpdatedTime stringstring インスタンスが最後に保持されていた時刻。The time at which the instance last persisted. ISO 8601 の拡張された表記を使用します。Uses ISO 8601 extended notation.
historyEvents JSONJSON オーケストレーションの実行履歴を含む JSON 配列。A JSON array containing the orchestration execution history. このフィールドは、showHistory クエリ文字列パラメーターが trueに設定されていない限り、null です。This field is null unless the showHistory query string parameter is set to true.

オーケストレーションの実行履歴とアクティビティの出力を含む応答ペイロードの例を次に示します (読みやすい形式になっています)。Here is an example response payload including the orchestration execution history and activity outputs (formatted for readability):

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

HTTP 202 の応答には、前述の statusQueryGetUri フィールドと同じ URL を参照する Location 応答ヘッダーも含まれています。The HTTP 202 response also includes a Location response header that references the same URL as the statusQueryGetUri field mentioned previously.

すべてのインスタンス ステータスを取得するGet all instances status

'インスタンスの状態を取得する' 要求から instanceId を削除して、すべてのインスタンスの状態のクエリを実行することもできます。You can also query the status of all instances by removing the instanceId from the 'Get instance status' request. この場合、基本のパラメーターは 'インスタンスの状態を取得する' と同じです。In this case, the basic parameters are the same as the 'Get instance status'. フィルター処理用のクエリ文字列パラメーターもサポートされています。Query string parameters for filtering are also supported.

覚えておくべきことの 1 つは、connectioncode が省略可能であることです。One thing to remember is that connection and code are optional. 関数に対する匿名認証がある場合、コードは必要ありません。If you have anonymous auth on the function then code isn't required. AzureWebJobsStorage アプリ設定で定義されているのとは異なるストレージの接続文字列を使用しない場合は、接続クエリ文字列パラメーターを無視してかまいません。If you don't want to use a different storage connection string other than defined in the AzureWebJobsStorage app setting, then you can safely ignore the connection query string parameter.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &showInput=[true|false]
    &top={integer}

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

GET /runtime/webhooks/durableTask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &showInput=[true|false]
    &top={integer}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

フィールドField パラメーターのタイプParameter type 説明Description
instanceId URLURL オーケストレーション インスタンスの ID。The ID of the orchestration instance.
showInput クエリ文字列Query string 省略可能なパラメーター。Optional parameter. false に設定した場合、関数の入力は応答ペイロードに含まれなくなります。If set to false, the function input will not be included in the response payload.
showHistory クエリ文字列Query string 省略可能なパラメーター。Optional parameter. true に設定した場合、オーケストレーションの実行履歴が応答ペイロードに含まれます。If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput クエリ文字列Query string 省略可能なパラメーター。Optional parameter. true に設定した場合、関数の出力はオーケストレーションの実行履歴に含まれます。If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以降に作成されたインスタンスにフィルター処理されます。When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以前に作成されたインスタンスにフィルター処理されます。When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、返されるインスタンスの一覧がランタイム状態に基づいてフィルター処理されます。When specified, filters the list of returned instances based on their runtime status. 考えられるランタイム状態の値の一覧を参照するには、インスタンスのクエリの実行に関するトピックをご覧ください。To see the list of possible runtime status values, see the Querying instances topic.
top クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、クエリによって返されるインスタンス数が制限されます。When specified, limits the number of instances returned by the query.

ResponseResponse

次に、オーケストレーション ステータスを含む応答ペイロードの例を示します (読みやすくなるように、形式を整えています)。Here is an example of response payloads including the orchestration status (formatted for readability):

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

注意

この操作は、インスタンスのテーブルに多数の行がある場合、Azure Storage の I/O の観点から非常にコスト効率が悪くなることがあります。This operation can be very expensive in terms of Azure Storage I/O if there are a lot of rows in the Instances table. インスタンス テーブルの詳細については、「Durable Functions のパフォーマンスとスケーリング (Azure Functions)」のドキュメントを参照してください。More details on Instance table can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

さらに結果が存在する場合、継続トークンが応答ヘッダーに返されます。If more results exist, a continuation token is returned in the response header. ヘッダーの名前は x-ms-continuation-token です。The name of the header is x-ms-continuation-token.

次の要求ヘッダーで継続トークンの値を設定すると、結果の次のページを取得できます。If you set continuation token value in the next request header, you can get the next page of results. この要求ヘッダーの名前も x-ms-continuation-token です。This name of the request header is also x-ms-continuation-token.

単一インスタンス履歴を消去するPurge single instance history

指定したオーケストレーション インスタンスの履歴および関連する成果物を削除します。Deletes the history and related artifacts for a specified orchestration instance.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

フィールドField パラメーターのタイプParameter type 説明Description
instanceId URLURL オーケストレーション インスタンスの ID。The ID of the orchestration instance.

ResponseResponse

以下の HTTP 状態コード値が返される可能性があります。The following HTTP status code values can be returned.

  • HTTP 200 (OK) :インスタンス履歴は正常に消去されました。HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (Not Found) :指定されたインスタンスは存在しません。HTTP 404 (Not Found): The specified instance doesn't exist.

HTTP 200 の場合の応答ペイロードは、次のフィールドを持つ JSON オブジェクトです。The response payload for the HTTP 200 case is a JSON object with the following field:

フィールドField データ型Data type 説明Description
instancesDeleted integerinteger 削除されたインスタンスの数。The number of instances deleted. 単一インスタンスの場合、この値は常に 1 です。For the single instance case, this value should always be 1.

応答ペイロードの例を次に示します (読みやすいように書式設定されています)。Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 1
}

複数インスタンス履歴を消去するPurge multiple instance history

'単一インスタンス履歴を消去する' 要求から {instanceId} を削除することで、タスク ハブ内の複数インスタンスの履歴および関連する成果物を削除することもできます。You can also delete the history and related artifacts for multiple instances within a task hub by removing the {instanceId} from the 'Purge single instance history' request. インスタンス履歴を選択して消去するには、'すべてのインスタンス ステータスを取得する' 要求で説明したものと同じフィルターを使用します。To selectively purge instance history, use the same filters described in the 'Get all instances status' request.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

フィールドField パラメーターのタイプParameter type 説明Description
createdTimeFrom クエリ文字列Query string 消去されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以降に作成されたインスタンスにフィルター処理されます。Filters the list of purged instances that were created at or after the given ISO8601 timestamp.
createdTimeTo クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、消去されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以前に作成されたインスタンスにフィルター処理されます。When specified, filters the list of purged instances that were created at or before the given ISO8601 timestamp.
runtimeStatus クエリ文字列Query string 省略可能なパラメーター。Optional parameter. 指定した場合、消去されるインスタンスの一覧がランタイム状態に基づいてフィルター処理されます。When specified, filters the list of purged instances based on their runtime status. 考えられるランタイム状態の値の一覧を参照するには、インスタンスのクエリの実行に関するトピックをご覧ください。To see the list of possible runtime status values, see the Querying instances topic.

注意

この操作は、インスタンスや履歴のテーブルに多数の行がある場合、Azure Storage の I/O の観点から非常にコスト効率が悪くなることがあります。This operation can be very expensive in terms of Azure Storage I/O if there are a lot of rows in the Instances and/or History tables. これらのテーブルの詳細については、「Durable Functions のパフォーマンスとスケーリング (Azure Functions)」のドキュメントを参照してください。More details on these tables can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

ResponseResponse

以下の HTTP 状態コード値が返される可能性があります。The following HTTP status code values can be returned.

  • HTTP 200 (OK) :インスタンス履歴は正常に消去されました。HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (Not Found) :フィルター式に一致するインスタンスが見つかりませんでした。HTTP 404 (Not Found): No instances were found that match the filter expression.

HTTP 200 の場合の応答ペイロードは、次のフィールドを持つ JSON オブジェクトです。The response payload for the HTTP 200 case is a JSON object with the following field:

フィールドField データ型Data type 説明Description
instancesDeleted integerinteger 削除されたインスタンスの数。The number of instances deleted.

応答ペイロードの例を次に示します (読みやすいように書式設定されています)。Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 250
}

イベントを発生させるRaise event

実行中のオーケストレーション インスタンスにイベント通知メッセージを送信します。Sends an event notification message to a running orchestration instance.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

フィールドField パラメーターのタイプParameter type 説明Description
instanceId URLURL オーケストレーション インスタンスの ID。The ID of the orchestration instance.
eventName URLURL ターゲット オーケストレーション インスタンスが待機しているイベントの名前。The name of the event that the target orchestration instance is waiting on.
{content} 要求内容Request content JSON 形式のイベント ペイロード。The JSON-formatted event payload.

ResponseResponse

返される可能性がある状態コード値は、いくつかあります。Several possible status code values can be returned.

  • HTTP 202 (Accepted) :発生したイベントが受け入れられて処理された。HTTP 202 (Accepted): The raised event was accepted for processing.
  • HTTP 400 (Bad request) :要求内容が application/json タイプまたは有効な JSON でなかった。HTTP 400 (Bad request): The request content was not of type application/json or was not valid JSON.
  • HTTP 404 (Not Found) :指定されたインスタンスが見つからなかった。HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone) :指定されたインスタンスが完了または失敗し、発生したイベントを処理できない。HTTP 410 (Gone): The specified instance has completed or failed and cannot process any raised events.

operation という名前のイベントを待機するインスタンスに JSON 文字列 "incr" を送信する要求の例を次に示します。Here is an example request that sends the JSON string "incr" to an instance waiting for an event named operation:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

この API の応答には内容は含まれません。The responses for this API do not contain any content.

インスタンスを終了するTerminate instance

実行中のオーケストレーション インスタンスを終了します。Terminates a running orchestration instance.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

フィールドField パラメーターのタイプParameter Type 説明Description
instanceId URLURL オーケストレーション インスタンスの ID。The ID of the orchestration instance.
reason クエリ文字列Query string 省略可能。Optional. オーケストレーション インスタンスの終了の理由。The reason for terminating the orchestration instance.

ResponseResponse

返される可能性がある状態コード値は、いくつかあります。Several possible status code values can be returned.

  • HTTP 202 (Accepted) :終了要求が受け入れられて処理された。HTTP 202 (Accepted): The terminate request was accepted for processing.
  • HTTP 404 (Not Found) :指定されたインスタンスが見つからなかった。HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone) :指定されたインスタンスが完了したか失敗した。HTTP 410 (Gone): The specified instance has completed or failed.

実行中のインスタンスを終了させ、バグの理由を示す要求の例を次に示します。Here is an example request that terminates a running instance and specifies a reason of buggy:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

この API の応答には内容は含まれません。The responses for this API do not contain any content.

rewind インスタンス (プレビュー)Rewind instance (preview)

最後に失敗した操作を再実行することにより、失敗したオーケストレーション インスタンスを実行状態に復元します。Restores a failed orchestration instance into a running state by replaying the most recent failed operations.

RequestRequest

Functions ランタイム バージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Functions ランタイム バージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

フィールドField パラメーターのタイプParameter Type 説明Description
instanceId URLURL オーケストレーション インスタンスの ID。The ID of the orchestration instance.
reason クエリ文字列Query string 省略可能。Optional. オーケストレーション インスタンスを rewind する理由。The reason for rewinding the orchestration instance.

ResponseResponse

返される可能性がある状態コード値は、いくつかあります。Several possible status code values can be returned.

  • HTTP 202 (Accepted) :巻き戻し要求が受け入れられて処理された。HTTP 202 (Accepted): The rewind request was accepted for processing.
  • HTTP 404 (Not Found) :指定されたインスタンスが見つからなかった。HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone) :指定されたインスタンスが完了したか終了した。HTTP 410 (Gone): The specified instance has completed or was terminated.

失敗したインスタンスを rewind し、修正の理由を指定する要求の例を次に示します。Here is an example request that rewinds a failed instance and specifies a reason of fixed:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

この API の応答には内容は含まれません。The responses for this API do not contain any content.

次の手順Next steps