HTTP API リファレンスHTTP API reference

Durable Functions 拡張機能では、オーケストレーションエンティティ、およびタスク ハブで管理タスクを実行するために使用できる一連の組み込み HTTP API が公開されています。The Durable Functions extension exposes a set of built-in HTTP APIs that can be used to perform management tasks on orchestrations, entities, and task hubs. これらの HTTP API は、Azure Functions ホストによって承認されているが Durable Functions 拡張機能によって直接処理される拡張性 webhook です。These HTTP APIs are extensibility webhooks that are authorized by the Azure Functions host but handled directly by the Durable Functions extension.

拡張機能によって実装されるすべての HTTP API には、次のパラメーターが必要です。All HTTP APIs implemented by the extension require 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 autogenerated 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. .NET の CreateCheckStatusResponseCreateHttpManagementPayload API、または JavaScript の createCheckStatusResponsecreateHttpManagementPayload API などのオーケストレーション クライアント バインド API を使用して、正しい taskHubconnectionsystemKey クエリ文字列値を含む URL を生成できます。You can generate URLs that contain the correct taskHub, connection, and systemKey query string values using orchestration client binding APIs, such as the CreateCheckStatusResponse and CreateHttpManagementPayload APIs in .NET, or the createCheckStatusResponse and createHttpManagementPayload APIs in JavaScript.

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

オーケストレーションの開始Start orchestration

指定されたオーケストレーター関数の新しいインスタンスの実行を開始します。Starts executing a new instance of the specified orchestrator function.

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/orchestrators/{functionName}/{instanceId?}
     ?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/orchestrators/{functionName}/{instanceId?}
     ?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
functionName URLURL 開始するオーケストレーター関数の名前。The name of the orchestrator function to start.
instanceId URLURL 省略可能なパラメーター。Optional parameter. オーケストレーション インスタンスの ID。The ID of the orchestration instance. 指定しない場合、オーケストレーター関数はランダムなインスタンス ID で開始します。If not specified, the orchestrator function will start with a random instance ID.
{content} 要求内容Request content 省略可能。Optional. JSON 形式のオーケストレーター関数入力。The JSON-formatted orchestrator function input.

ResponseResponse

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

  • HTTP 202 (Accepted) :指定されたオーケストレーター関数は実行を開始するようにスケジュールされました。HTTP 202 (Accepted): The specified orchestrator function was scheduled to start running. Location 応答ヘッダーには、オーケストレーションの状態をポーリングするための URL が含まれています。The Location response header contains a URL for polling the orchestration status.
  • HTTP 400 (Bad request) :指定されたオーケストレーター関数が存在しないか、指定されたインスタンス ID が無効だったか、要求コンテンツが有効な JSON ではありませんでした。HTTP 400 (Bad request): The specified orchestrator function doesn't exist, the specified instance ID was not valid, or request content was not valid JSON.

RestartVMs オーケストレーター関数を開始し、JSON オブジェクトペイロードを含む要求の例を次に示します。The following is an example request that starts a RestartVMs orchestrator function and includes JSON object payload:

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

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

フィールド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.
purgeHistoryDeleteUri オーケストレーション インスタンスの "消去履歴" URL。The "purge history" URL of the orchestration instance.
rewindPostUri (プレビュー) オーケストレーション インスタンスの "巻き戻し" URL。(preview) The "rewind" URL of the orchestration instance.

すべてのフィールドのデータ型は string です。The data type of all fields is string.

abc123 を ID として持つオーケストレーション インスタンスの応答ペイロードの例を次に示します (読みやすいように書式設定されています)。Here is an example response payload for an orchestration instance with abc123 as its ID (formatted for readability):

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX"
}

http 応答は、"ポーリング コンシューマー パターン" と互換性があるように意図されています。The http response is intended to be compatible with the Polling Consumer Pattern. また、次の重要な応答ヘッダーも含まれています。It also includes the following notable response headers:

  • [場所] :状態エンドポイントの URL。Location: The URL of the status endpoint. この URL には、statusQueryGetUri フィールドと同じ値が含まれます。This URL contains the same value as the statusQueryGetUri field.
  • Retry-After:ポーリング操作の間に待機する秒数。Retry-After: The number of seconds to wait between polling operations. 既定値は 10 です。The default value is 10.

非同期 HTTP ポーリング パターンの詳細については、HTTP 非同期操作の追跡に関するドキュメントをご覧ください。For more information on the asynchronous HTTP polling pattern, see the HTTP async operation tracking documentation.

インスタンスの状態を取得する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 article.

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. 関数に対する匿名認証がある場合、code は必要ありません。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 article.
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 histories

'単一インスタンス履歴を消去する' 要求から {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 article.

注意

この操作は、インスタンスや履歴のテーブルに多数の行がある場合、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.

エンティティへのシグナル通知Signal entity

一方向の操作メッセージを Durable Entity に送信します。Sends a one-way operation message to a Durable Entity. エンティティが存在しない場合、自動的に作成されます。If the entity doesn't exist, it will be created automatically.

注意

Durable Entity は Durable Functions 2.0 以降で使用できます。Durable Entities are available starting in Durable Functions 2.0.

RequestRequest

HTTP 要求は次のような形式です (わかりやすくするために複数行が示されています)。The HTTP request is formatted as follows (multiple lines are shown for clarity):

POST /runtime/webhooks/durabletask/entities/{entityType}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

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

フィールドField パラメーターのタイプParameter type 説明Description
entityType URLURL エンティティの種類。The type of the entity.
entityKey URLURL エンティティの一意の名前。The unique name of the entity.
op クエリ文字列Query string 省略可能。Optional. 呼び出すユーザー定義操作の名前。The name of the user-defined operation to invoke.
{content} 要求内容Request content JSON 形式のイベント ペイロード。The JSON-formatted event payload.

次に示すのは、ユーザー定義の "Add" メッセージを、steps という名前の Counter エンティティに送信する要求の例です。Here is an example request that sends a user-defined "Add" message to a Counter entity named steps. メッセージの内容は値 5 です。The content of the message is the value 5. エンティティがまだ存在しない場合、次の要求によって作成されます。If the entity does not already exist, it will be created by this request:

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

ResponseResponse

この操作には、複数の応答の可能性があります。This operation has several possible responses:

  • HTTP 202 (Accepted) :非同期処理のためにシグナル操作が受理された。HTTP 202 (Accepted): The signal operation was accepted for asynchronous processing.
  • HTTP 400 (Bad request) :要求内容が application/json タイプまたは有効な JSON でなかったか、entityKey の値が無効だった。HTTP 400 (Bad request): The request content was not of type application/json, was not valid JSON, or had an invalid entityKey value.
  • HTTP 404 (Not Found) :指定された entityType が見つからなかった。HTTP 404 (Not Found): The specified entityType was not found.

成功した HTTP 要求の応答には内容は含まれません。A successful HTTP request does not contain any content in the response. 失敗した HTTP 要求は、応答の内容に JSON 形式のエラー情報が含まれている場合があります。A failed HTTP request may contain JSON-formatted error information in the response content.

エンティティのクエリの実行Query entity

指定されたエンティティの状態を取得します。Gets the state of the specified entity.

RequestRequest

HTTP 要求は次のような形式です (わかりやすくするために複数行が示されています)。The HTTP request is formatted as follows (multiple lines are shown for clarity):

GET /runtime/webhooks/durabletask/entities/{entityType}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

ResponseResponse

この操作には、2 つの応答の可能性があります。This operation has two possible responses:

  • HTTP 200 (OK) :指定されたエンティティが存在する。HTTP 200 (OK): The specified entity exists.
  • HTTP 404 (Not Found) :指定されたエンティティが見つからなかった。HTTP 404 (Not Found): The specified entity was not found.

成功した応答は、JSON でシリアル化されたエンティティの状態がその内容に含まれます。A successful response contains the JSON-serialized state of the entity as its content.

Example

次の例の HTTP 要求では、steps という名前の既存の Counter エンティティの状態を取得します。The following example HTTP request gets the state of an existing Counter entity named steps:

GET /runtime/webhooks/durabletask/entities/Counter/steps

currentValue フィールドに保存したステップ数しか Counter エンティティに含まれていなかった場合、応答の内容は次のようになります (読みやすいように整形しています)。If the Counter entity simply contained a number of steps saved in a currentValue field, the response content might look like the following (formatted for readability):

{
    "currentValue": 5
}

次の手順Next steps