HTTP API リファレンス

[アーティクル]
06/01/2023

Durable Functions 拡張機能では、オーケストレーション、エンティティ、およびタスクハブで管理タスクを実行するために使用できる一連の組み込み HTTP API が公開されています。これらの HTTP API は、Azure Functions ホストによって承認されているが Durable Functions 拡張機能によって直接処理される拡張性 webhook です。

この記事で触れられている API のベース URL は、関数アプリのベース URL と同じです。 Azure Functions Core Tools を使用してローカルで開発する場合、通常、ベース URL は http://localhost:7071 です。ホストされている Azure Functions サービスでは、通常、ベース URL は https://{appName}.azurewebsites.net です。 App Service アプリで構成されている場合、カスタムホスト名もサポートされます。

拡張機能によって実装されるすべての HTTP API には、次のパラメーターが必要です。すべてのパラメーターのデータ型は string です。

パラメーター	パラメーターの型	説明
`taskHub`	クエリ文字列	タスクハブの名前。指定しない場合は、現在の関数アプリのタスクハブの名前が想定されます。
`connection`	クエリ文字列	バックエンド記憶域プロバイダー用の接続アプリ設定の名前。指定しない場合は、関数アプリの既定の接続構成が想定されます。
`systemKey`	クエリ文字列	API の呼び出しに必要な承認キー。

systemKey は、Azure Functions ホストによって自動生成される承認キーです。これにより、Durable Task 拡張機能 API へのアクセスが特別に許可されます。また、他の Azure Functions アクセスキーと同じ方法で管理できます。 .NET の CreateCheckStatusResponse や CreateHttpManagementPayload API、または JavaScript の createCheckStatusResponse や createHttpManagementPayload API などのオーケストレーションクライアントバインディング API を使用して、正しい taskHub、connection、systemKey クエリ文字列値を含む URL を生成できます。

以降のセクションで、この拡張機能でサポートされる特定の HTTP API とその使用方法の例について説明します。

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

指定されたオーケストレーター関数の新しいインスタンスの実行を開始します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`functionName`	URL	開始するオーケストレーター関数の名前。
`instanceId`	URL	省略可能なパラメーター。オーケストレーションインスタンスの ID。指定しない場合、オーケストレーター関数はランダムなインスタンス ID で開始します。
`{content}`	要求内容	省略可能。 JSON 形式のオーケストレーター関数入力。

Response

返される可能性がある状態コード値は、いくつかあります。

HTTP 202 (Accepted) : 指定されたオーケストレーター関数は実行を開始するようにスケジュールされました。 Location 応答ヘッダーには、オーケストレーションの状態をポーリングするための URL が含まれています。
HTTP 400 (Bad request) : 指定されたオーケストレーター関数が存在しないか、指定されたインスタンス ID が無効だったか、要求コンテンツが有効な JSON ではありませんでした。

RestartVMs オーケストレーター関数を開始し、JSON オブジェクトペイロードを含む要求の例を次に示します。

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 オブジェクトです。

フィールド	説明
`id`	オーケストレーションインスタンスの ID。
`statusQueryGetUri`	オーケストレーションインスタンスの状態の URL。
`sendEventPostUri`	オーケストレーションインスタンスの "イベント発生" URL。
`terminatePostUri`	オーケストレーションインスタンスの "終了" URL。
`purgeHistoryDeleteUri`	オーケストレーションインスタンスの "消去履歴" URL。
`rewindPostUri`	(プレビュー) オーケストレーションインスタンスの "巻き戻し" URL。
`suspendPostUri`	オーケストレーションインスタンスの "中断" URL。
`resumePostUri`	オーケストレーションインスタンスの "再開" URL。

すべてのフィールドのデータ型は string です。

abc123 を ID として持つオーケストレーションインスタンスの応答ペイロードの例を次に示します (読みやすいように書式設定されています)。

{
    "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",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/suspend?reason={text}&code=XXX",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/resume?reason={text}&code=XXX"
}

HTTP 応答は、ポーリングコンシューマーパターンと互換性があるように意図されています。また、次の重要な応答ヘッダーも含まれています。

Location: 状態エンドポイントの URL。この URL には、statusQueryGetUri フィールドと同じ値が含まれます。
Retry-After: ポーリング操作の間に待機する秒数。既定値は 10 です。

非同期 HTTP ポーリングパターンの詳細については、HTTP 非同期操作の追跡に関するドキュメントをご覧ください。

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

指定されたオーケストレーションインスタンスの状態を取得します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。
`showInput`	クエリ文字列	省略可能なパラメーター。 `false` に設定した場合、関数の入力は応答ペイロードに含まれなくなります。
`showHistory`	クエリ文字列	省略可能なパラメーター。 `true` に設定した場合、オーケストレーションの実行履歴が応答ペイロードに含まれます。
`showHistoryOutput`	クエリ文字列	省略可能なパラメーター。 `true` に設定した場合、関数の出力はオーケストレーションの実行履歴に含まれます。
`createdTimeFrom`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以降に作成されたインスタンスにフィルター処理されます。
`createdTimeTo`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以前に作成されたインスタンスにフィルター処理されます。
`runtimeStatus`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるインスタンスの一覧がランタイム状態に基づいてフィルター処理されます。考えられるランタイム状態の値の一覧を確認するには、インスタンスのクエリの実行に関する記事をご覧ください。
`returnInternalServerErrorOnFailure`	クエリ文字列	省略可能なパラメーター。 `true` に設定すると、インスタンスがエラー状態の場合、この API は HTTP 200 ではなく HTTP 500 応答を返します。このパラメーターは、ステータスポーリングの自動化シナリオを対象としています。

Response

返される可能性がある状態コード値は、いくつかあります。

HTTP 200 (OK) : 指定されたインスタンスが完了状態またはエラー状態。
HTTP 202 (Accepted): 指定されたインスタンスが処理中。
HTTP 400 (Bad Request): 指定されたインスタンスが失敗したか終了した。
HTTP 404 (Not Found): 指定されたインスタンスが存在しないか実行開始されていない。
HTTP 500 (Internal Server Error) : returnInternalServerErrorOnFailure が true に設定され、指定したインスタンスがハンドルされない例外で失敗した場合にのみ返されます。

HTTP 200 と HTTP 202 の場合の応答ペイロードは、次のフィールドを持つ JSON オブジェクトです。

フィールド	データ型	Description
`runtimeStatus`	string	インスタンスの実行時状態。値には、Running、Pending、Failed、Canceled、Terminated、Completed、Suspended があります。
`input`	JSON	インスタンスを初期化するために使用される JSON データ。このフィールドは、`showInput` クエリ文字列パラメーターが `false`に設定されている場合は、`null` です。
`customStatus`	JSON	カスタムオーケストレーションの状態に使用された JSON データ。セットされていない場合、このフィールドは`null`です。
`output`	JSON	インスタンスの JSON の出力。インスタンスが完了状態でない場合、このフィールドは `null` です。
`createdTime`	string	インスタンスが作成された時刻。 ISO 8601 の拡張された表記を使用します。
`lastUpdatedTime`	string	インスタンスが最後に保持されていた時刻。 ISO 8601 の拡張された表記を使用します。
`historyEvents`	JSON	オーケストレーションの実行履歴を含む JSON 配列。このフィールドは、`showHistory` クエリ文字列パラメーターが `true`に設定されていない限り、`null` です。

オーケストレーションの実行履歴とアクティビティの出力を含む応答ペイロードの例を次に示します (読みやすい形式になっています)。

{
  "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 応答ヘッダーも含まれています。

すべてのインスタンスステータスを取得する

'インスタンスの状態を取得する' 要求から instanceId を削除して、すべてのインスタンスの状態のクエリを実行することもできます。この場合、基本のパラメーターは 'インスタンスの状態を取得する' と同じです。フィルター処理用のクエリ文字列パラメーターもサポートされています。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`showInput`	クエリ文字列	省略可能なパラメーター。 `false` に設定した場合、関数の入力は応答ペイロードに含まれなくなります。
`showHistoryOutput`	クエリ文字列	省略可能なパラメーター。 `true` に設定した場合、関数の出力はオーケストレーションの実行履歴に含まれます。
`createdTimeFrom`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以降に作成されたインスタンスにフィルター処理されます。
`createdTimeTo`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以前に作成されたインスタンスにフィルター処理されます。
`runtimeStatus`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるインスタンスの一覧がランタイム状態に基づいてフィルター処理されます。考えられるランタイム状態の値の一覧を確認するには、インスタンスのクエリの実行に関する記事をご覧ください。
`instanceIdPrefix`	クエリ文字列	省略可能なパラメーター。指定すると、返されたインスタンスの一覧がフィルター処理され、インスタンス ID が指定したプレフィックス文字列で始まるインスタンスのみが含まれます。拡張機能のバージョン 2.7.2 以降で使用できます。
`top`	クエリ文字列	省略可能なパラメーター。指定した場合、クエリによって返されるインスタンス数が制限されます。

Response

次に、オーケストレーションステータスを含む応答ペイロードの例を示します (読みやすくなるように、形式を整えています)。

[
    {
        "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"
    }
]

Note

この操作は、既定の Azure Storage プロバイダーを使用している場合、およびインスタンステーブルに多数の行がある場合、Azure Storage I/O の観点から非常にコスト効率が悪くなることがあります。インスタンステーブルの詳細については、「Azure Storage プロバイダー」のドキュメントを参照してください。

さらに結果が存在する場合、継続トークンが応答ヘッダーに返されます。ヘッダーの名前は x-ms-continuation-token です。

注意事項

クエリ結果から返される項目数が、top で指定された制限より少ない場合があります。したがって、結果を受け取るときは、常に継続トークンがあるかどうかを確認する必要があります。

次の要求ヘッダーで継続トークンの値を設定すると、結果の次のページを取得できます。この要求ヘッダーの名前も x-ms-continuation-token です。

単一インスタンス履歴を消去する

指定したオーケストレーションインスタンスの履歴および関連する成果物を削除します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。

Response

以下の HTTP 状態コード値が返される可能性があります。

HTTP 200 (OK) : インスタンス履歴は正常に消去されました。
HTTP 404 (Not Found) : 指定されたインスタンスは存在しません。

HTTP 200 の場合の応答ペイロードは、次のフィールドを持つ JSON オブジェクトです。

フィールド	データ型	説明
`instancesDeleted`	整数 (integer)	削除されたインスタンスの数。単一インスタンスの場合、この値は常に `1` です。

応答ペイロードの例を次に示します (読みやすいように書式設定されています)。

{
    "instancesDeleted": 1
}

複数インスタンス履歴を消去する

'単一インスタンス履歴を消去する' 要求から {instanceId} を削除することで、タスクハブ内の複数インスタンスの履歴および関連する成果物を削除することもできます。インスタンス履歴を選択して消去するには、'すべてのインスタンスステータスを取得する' 要求で説明したものと同じフィルターを使用します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`createdTimeFrom`	クエリ文字列	消去されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以降に作成されたインスタンスにフィルター処理されます。
`createdTimeTo`	クエリ文字列	省略可能なパラメーター。指定した場合、消去されるインスタンスの一覧が特定の ISO8601 タイムスタンプの時刻以前に作成されたインスタンスにフィルター処理されます。
`runtimeStatus`	クエリ文字列	省略可能なパラメーター。指定した場合、消去されるインスタンスの一覧がランタイム状態に基づいてフィルター処理されます。考えられるランタイム状態の値の一覧を確認するには、インスタンスのクエリの実行に関する記事をご覧ください。

Note

この操作は、既定の Azure Storage プロバイダーを使用している場合、およびインスタンスや履歴のテーブルに多数の行がある場合、Azure Storage I/O の観点から非常にコスト効率が悪くなることがあります。これらのテーブルの詳細については、「Durable Functions のパフォーマンスとスケーリング (Azure Functions)」のドキュメントを参照してください。

Response

以下の HTTP 状態コード値が返される可能性があります。

HTTP 200 (OK) : インスタンス履歴は正常に消去されました。
HTTP 404 (Not Found) : フィルター式に一致するインスタンスが見つかりませんでした。

HTTP 200 の場合の応答ペイロードは、次のフィールドを持つ JSON オブジェクトです。

フィールド	データ型	説明
`instancesDeleted`	整数 (integer)	削除されたインスタンスの数。

応答ペイロードの例を次に示します (読みやすいように書式設定されています)。

{
    "instancesDeleted": 250
}

イベントを発生させる

実行中のオーケストレーションインスタンスにイベント通知メッセージを送信します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。
`eventName`	URL	ターゲットオーケストレーションインスタンスが待機しているイベントの名前。
`{content}`	要求内容	JSON 形式のイベントペイロード。

Response

返される可能性がある状態コード値は、いくつかあります。

HTTP 202 (Accepted): 発生したイベントが受け入れられて処理された。
HTTP 400 (Bad request): 要求内容が application/json タイプまたは有効な JSON でなかった。
HTTP 404 (Not Found): 指定されたインスタンスが見つからなかった。
HTTP 410 (Gone): 指定されたインスタンスが完了または失敗し、発生したイベントを処理できない。

operation という名前のイベントを待機するインスタンスに JSON 文字列 "incr" を送信する要求の例を次に示します。

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

"incr"

この API の応答には内容は含まれません。

インスタンスを終了する

実行中のオーケストレーションインスタンスを終了します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターの型	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。
`reason`	クエリ文字列	省略可能。オーケストレーションインスタンスの終了の理由。

Response

返される可能性がある状態コード値は、いくつかあります。

HTTP 202 (Accepted): 終了要求が受け入れられて処理された。
HTTP 404 (Not Found): 指定されたインスタンスが見つからなかった。
HTTP 410 (Gone): 指定されたインスタンスが完了したか失敗した。

実行中のインスタンスを終了させ、バグの理由を示す要求の例を次に示します。

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

この API の応答には内容は含まれません。

インスタンスの中断

実行中のオーケストレーションインスタンスを中断します。

Request

Functions ランタイムバージョン 2.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

フィールド	パラメーターの型	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。
`reason`	クエリ文字列	省略可能。オーケストレーションインスタンスを中断する理由。

返される可能性がある状態コード値は、いくつかあります。

HTTP 202 (Accepted): 中断要求が受け入れられて処理された。
HTTP 404 (Not Found): 指定されたインスタンスが見つからなかった。
HTTP 410 (Gone): 指定されたインスタンスは完了、失敗、または終了した。

この API の応答には内容は含まれません。

インスタンスの再開

中断したオーケストレーションインスタンスを再開します。

Request

Functions ランタイムバージョン 2.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

フィールド	パラメーターの型	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。
`reason`	クエリ文字列	省略可能。オーケストレーションインスタンスを再開する理由。

返される可能性がある状態コード値は、いくつかあります。

HTTP 202 (Accepted): 再開要求が受け入れられて処理された。
HTTP 404 (Not Found): 指定されたインスタンスが見つからなかった。
HTTP 410 (Gone): 指定されたインスタンスは完了、失敗、または終了した。

この API の応答には内容は含まれません。

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

最後に失敗した操作を再実行することにより、失敗したオーケストレーションインスタンスを実行状態に復元します。

要求

Functions ランタイムバージョン 1.x の場合、要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Functions ランタイムバージョン 2.x の URL 形式は、パラメーターがすべて同じですが、プレフィックスが若干異なります。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターの型	説明
`instanceId`	URL	オーケストレーションインスタンスの ID。
`reason`	クエリ文字列	省略可能。オーケストレーションインスタンスを rewind する理由。

Response

返される可能性がある状態コード値は、いくつかあります。

HTTP 202 (Accepted): 巻き戻し要求が受け入れられて処理された。
HTTP 404 (Not Found): 指定されたインスタンスが見つからなかった。
HTTP 410 (Gone): 指定されたインスタンスが完了したか終了した。

失敗したインスタンスを rewind し、修正の理由を指定する要求の例を次に示します。

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

この API の応答には内容は含まれません。

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

一方向の操作メッセージを Durable Entity に送信します。エンティティが存在しない場合、自動的に作成されます。

Note

持続エンティティは、Durable Functions 2.0 以降で使用できます。

要求

HTTP 要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`entityName`	URL	エンティティの名前 (型)。
`entityKey`	URL	エンティティのキー (一意の ID)。
`op`	クエリ文字列	省略可能。呼び出すユーザー定義操作の名前。
`{content}`	要求内容	JSON 形式のイベントペイロード。

次に示すのは、ユーザー定義の "Add" メッセージを、steps という名前の Counter エンティティに送信する要求の例です。メッセージの内容は値 5 です。エンティティがまだ存在しない場合、次の要求によって作成されます。

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

5

Note

.NET のクラスベースのエンティティの既定では、delete の op 値を指定すると、エンティティの状態が削除されます。ただし、エンティティで delete という名前の操作が定義されている場合、そのユーザー定義の操作が代わりに呼び出されます。

Response

この操作には、複数の応答の可能性があります。

HTTP 202 (Accepted) : 非同期処理のためにシグナル操作が受理されました。
HTTP 400 (Bad request) : 要求内容が application/json タイプまたは有効な JSON でなかったか、entityKey の値が無効でした。
HTTP 404 (Not Found) : 指定された entityName が見つかりませんでした。

成功した HTTP 要求の応答には内容は含まれません。失敗した HTTP 要求は、応答の内容に JSON 形式のエラー情報が含まれている場合があります。

エンティティの取得

指定されたエンティティの状態を取得します。

要求

HTTP 要求は次のような形式です (わかりやすくするために複数行が示されています)。

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

Response

この操作には、2 つの応答の可能性があります。

HTTP 200 (OK) : 指定されたエンティティが存在します。
HTTP 404 (Not Found) : 指定されたエンティティが見つかりませんでした。

成功した応答は、JSON でシリアル化されたエンティティの状態がその内容に含まれます。

例

次の例の HTTP 要求では、steps という名前の既存の Counter エンティティの状態を取得します。

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

currentValue フィールドに保存したステップ数しか Counter エンティティに含まれていなかった場合、応答の内容は次のようになります (読みやすいように整形しています)。

{
    "currentValue": 5
}

エンティティの一覧表示

複数のエンティティを照会するには、エンティティ名または最後の操作日を使用します。

要求

HTTP 要求は次のような形式です (わかりやすくするために複数行が示されています)。

GET /runtime/webhooks/durabletask/entities/{entityName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &lastOperationTimeFrom={timestamp}
    &lastOperationTimeTo={timestamp}
    &fetchState=[true|false]
    &top={integer}

この API の要求パラメーターには、前述の既定のセットと、次の固有のパラメーターが含まれます。

フィールド	パラメーターのタイプ	説明
`entityName`	URL	省略可能。指定した場合、返されるエンティティの一覧をエンティティ名でフィルター処理します (大文字と小文字は区別されません)。
`fetchState`	クエリ文字列	省略可能なパラメーター。 `true` に設定すると、エンティティの状態が応答ペイロードに含まれます。
`lastOperationTimeFrom`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるエンティティの一覧が特定の ISO8601 タイムスタンプの時刻以降に操作を実行したエンティティにフィルター処理されます。
`lastOperationTimeTo`	クエリ文字列	省略可能なパラメーター。指定した場合、返されるエンティティの一覧が特定の ISO8601 タイムスタンプの時刻以前に操作を実行したエンティティにフィルター処理されます。
`top`	クエリ文字列	省略可能なパラメーター。指定した場合、クエリによって返されるエンティティ数が制限されます。

Response

成功した HTTP 200 応答には、JSON でシリアル化されたエンティティの配列と、必要に応じて各エンティティの状態が含まれます。

既定では、操作はクエリ条件に一致する最初の 100 エンティティを返します。呼び出し元は、top のクエリ文字列パラメーター値を指定して、異なる結果の最大数を返すことができます。返される結果を超える結果が存在する場合、継続トークンも応答ヘッダーに返されます。ヘッダーの名前は x-ms-continuation-token です。

次の要求ヘッダーで継続トークンの値を設定すると、結果の次のページを取得できます。この要求ヘッダーの名前も x-ms-continuation-token です。

例 - すべてのエンティティを一覧表示する

次の HTTP 要求の例では、タスクハブ内のすべてのエンティティが一覧表示されます。

GET /runtime/webhooks/durabletask/entities

応答 JSON は次のようになります (読みやすいように書式設定されています)。

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
    },
    {
        "entityId": { "key": "mice", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
    },
    {
        "entityId": { "key": "radio", "name": "device" },
        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
    },
]

例 - エンティティの一覧のフィルター処理

次の HTTP 要求の例では、counter 型の最初の 2 つのエンティティのみを一覧表示し、その状態も取得します。

GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true

応答 JSON は次のようになります (読みやすいように書式設定されています)。

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
        "state": { "value": 9 }
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
        "state": { "value": 10 }
    }
]

次のステップ

Application Insights を使用して Durable Functions を監視する方法を確認する

次の方法で共有

HTTP API リファレンス

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

要求

Response

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

要求

Response

すべてのインスタンス ステータスを取得する

要求

Response

単一インスタンス履歴を消去する

要求

Response

複数インスタンス履歴を消去する

要求

Response

イベントを発生させる

要求

Response

インスタンスを終了する

要求

Response

インスタンスの中断

Request

インスタンスの再開

Request

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

要求

Response

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

要求

Response

エンティティの取得

要求

Response

例

エンティティの一覧表示

要求

Response

例 - すべてのエンティティを一覧表示する

例 - エンティティの一覧のフィルター処理

次のステップ

フィードバック

その他のリソース

すべてのインスタンスステータスを取得する