HTTP API 參考

文章
04/18/2024

Durable Functions 延伸模組會公開一組內建 HTTP API，可用於在協調流程、實體和工作中樞上執行管理工作。這些 HTTP API 是擴充性 Webhook，是由 Azure Functions 主機授權，但由 Durable Functions 延伸模組直接處理。

本文所提及 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 主機自動產生的授權金鑰。它特別授與「長期工作」延伸模組 API 的存取權，並且可以用與其他 Azure Functions 存取金鑰相同的方式來管理。您可以使用協調流程用戶端繫結 API (例如使用 .NET 的 CreateCheckStatusResponse 和 CreateHttpManagementPayload API、使用 JavaScript 的 createCheckStatusResponse 和 createHttpManagementPayload 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	選擇性的參數。協調流程執行個體的識別碼。如果未指定，協調器函式會以隨機執行個體識別碼開始。
`{content}`	要求內容	選擇性。 JSON 格式的協調器函式輸入。

回應

可以傳回幾個可能的狀態字碼值。

HTTP 202 (已接受)：指定的協調器函式已排程開始執行。 Location 回應標頭包含輪詢協調流程狀態的 URL。
HTTP 400 (不正確的要求)：指定的協調器函式不存在、指定的執行個體識別碼無效，或要求內容不是有效的 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`	協調流程執行個體的識別碼。
`statusQueryGetUri`	協調流程執行個體的狀態 URL。
`sendEventPostUri`	協調流程執行個體的「引發事件」URL。
`terminatePostUri`	協調流程執行個體的「終止」URL。
`purgeHistoryDeleteUri`	協調流程執行個體的「清除歷程記錄」URL。
`rewindPostUri`	(預覽版) 協調流程執行個體的「倒轉」URL。
`suspendPostUri`	協調流程執行個體的「暫止」URL。
`resumePostUri`	協調流程執行個體的「繼續」URL。

所有欄位的資料類型是 string。

以下是協調流程執行個體的範例回應承載，具有 abc123 做為其識別碼 (為了方便閱讀，已格式化)：

{
    "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 回應的設計目的是與「輪詢取用者模式」相容。它也包含下列值得注意的回應標頭：

位置：狀態端點的 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	協調流程執行個體的識別碼。
`showInput`	查詢字串	選擇性的參數。如果設定為 `false`，則函式輸入將不會包含在回應承載中。
`showHistory`	查詢字串	選擇性的參數。如果設定為 `true`，則協調流程執行歷程記錄將會包含在回應承載中。
`showHistoryOutput`	查詢字串	選擇性的參數。如果設定為 `true`，則函式輸出將會包含在協調流程執行歷程記錄中。
`createdTimeFrom`	查詢字串	選擇性的參數。指定時，會篩選所傳回執行個體的清單，這些執行個體是在指定 ISO8601 時間戳記當時或之後建立的。
`createdTimeTo`	查詢字串	選擇性的參數。指定時，會篩選傳回執行個體的清單，這些執行個體是在指定 ISO8601 時間戳記當時或之前建立的。
`runtimeStatus`	查詢字串	選擇性的參數。指定時，會根據所傳回執行個體的執行階段狀態來篩選所傳回執行個體的清單。若要查看可能的執行階段狀態值清單，請參閱查詢執行個體文章。
`returnInternalServerErrorOnFailure`	查詢字串	選擇性的參數。如果設定為 `true`，如果執行個體處於失敗狀態，則此 API 會傳回 HTTP 500 回應，而非傳回 200。此參數適用於自動化狀態輪詢情節。

回應

可以傳回幾個可能的狀態字碼值。

HTTP 200 (OK)：指定的執行個體處於已完成或失敗狀態。
HTTP 202 (已接受)：指定的執行個體正在進行中。
HTTP 400 (不正確的要求)：指定的執行個體失敗或終止。
HTTP 404 (找不到)：指定的執行個體不存在或尚未開始執行。
HTTP 500 (內部伺服器錯誤)：只有在 returnInternalServerErrorOnFailure 設為 true，且指定的執行個體失敗並帶有未處理的例外狀況時才會傳回。

HTTP 200 和 HTTP 202 案例的回應承載是 JSON 物件，具有下列欄位：

欄位	資料類型	描述
`runtimeStatus`	string	執行個體的執行階段狀態。值包括 [執行中]、[擱置]、[失敗]、[已取消]、[終止]、[已完成]、[暫止]。
`input`	JSON	JSON 資料，用來初始化執行個體。這個欄位為 `null`，如果 `showInput` 查詢字串參數設定為 `false`。
`customStatus`	JSON	用於自訂協調流程狀態的 JSON 資料。如果未設定，欄位會是 `null`。
`output`	JSON	執行個體的 JSON 輸出。如果執行個體不是已完成狀態，則這個欄位是 `null`。
`createdTime`	string	執行個體建立的時間。使用 ISO 8601 延伸標記法。
`lastUpdatedTime`	string	執行個體保存的時間。使用 ISO 8601 延伸標記法。
`historyEvents`	JSON	包含協調流程執行歷程記錄的 JSON 陣列。這個欄位為 `null`，除非 `showHistory` 查詢字串參數設定為 `true`。

以下是範例回應承載，其中包含協調流程執行歷程記錄和活動輸出 (針對可讀性格式化)：

{
  "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。

取得所有執行個體狀態

您可以藉由將 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`	查詢字串	選擇性的參數。指定時，會篩選傳回的執行個體清單，只包含其執行個體識別碼開頭為指定前置字串的執行個體。從 2.7.2 版的延伸模組開始提供。
`top`	查詢字串	選擇性的參數。指定時，會限制查詢所傳回的執行個體數目。

回應

以下是回應承載範例，包括協調流程狀態 (針對可讀性格式化)：

[
    {
        "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 儲存體提供者，而且如果執行個體資料表中有大量資料列，則此作業可能會耗用非常大量 Azure 儲存體 I/O。如需更多執行個體資料表的詳細資訊，請參閱 Azure 儲存體提供者文件。

如果有更多結果，則在回應標頭中傳回接續權杖。標頭的名稱為 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	協調流程執行個體的識別碼。

回應

可以傳回下列 HTTP 狀態字碼值。

HTTP 200 (OK)：已成功清除執行個體歷程記錄。
HTTP 404 (找不到)：指定的執行個體不存在。

HTTP 200 案例的回應承載是 JSON 物件，具有下列欄位：

欄位	資料類型	描述
`instancesDeleted`	整數	已刪除的執行個體數目。針對單一執行個體案例，此值應一律為 `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`	查詢字串	選擇性的參數。指定時，會根據其執行階段狀態，來篩選已清除執行個體的清單。若要查看可能的執行階段狀態值清單，請參閱查詢執行個體文章。

注意

如果您使用預設的 Azure 儲存體提供者，而且如果執行個體及/或歷程記錄資料表中有大量資料列，則此作業可能會耗用非常大量 Azure 儲存體 I/O。在 Durable Functions (Azure Functions) 中的效能和級別文件中，可以找到這些資料表的更多詳細資料。

回應

可以傳回下列 HTTP 狀態字碼值。

HTTP 200 (OK)：已成功清除執行個體歷程記錄。
HTTP 404 (找不到)：找不到符合篩選條件運算式的執行個體。

HTTP 200 案例的回應承載是 JSON 物件，具有下列欄位：

欄位	資料類型	描述
`instancesDeleted`	整數	已刪除的執行個體數目。

以下是範例回應裝載 (針對可讀性格式化)：

{
    "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	協調流程執行個體的識別碼。
`eventName`	URL	目標協調流程執行個體等候之事件的名稱。
`{content}`	要求內容	JSON 格式的事件裝載。

回應

可以傳回幾個可能的狀態字碼值。

HTTP 202 (已接受)：已接受引發的事件以進行處理。
HTTP400 (不正確的要求)：要求內容不是類型 application/json 或不是有效的 JSON。
HTTP 404 (找不到)：找不到指定的執行個體。
HTTP 410 (不存在)：指定的執行個體已完成或失敗，且無法再處理任何引發的事件。

以下是範例要求，它會將 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	協調流程執行個體的識別碼。
`reason`	查詢字串	選擇性。終止協調流程執行個體的原因。

回應

可以傳回幾個可能的狀態字碼值。

HTTP 202 (已接受)：已接受終止要求以進行處理。
HTTP 404 (找不到)：找不到指定的執行個體。
HTTP 410 (不存在)：指定的執行個體已完成或失敗。

以下是範例要求，它會終止執行中執行個體並且指定錯誤的原因：

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

此 API 的回應不包含任何內容。

暫止執行個體

暫止執行中的協調流程執行個體。

要求

在 Functions 執行階段 2.x 版本中，要求的格式如下 (為了清楚起見，會顯示多行)：

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

欄位	參數類型	描述
`instanceId`	URL	協調流程執行個體的識別碼。
`reason`	查詢字串	選擇性。暫止協調流程執行個體的原因。

可以傳回幾個可能的狀態字碼值。

HTTP 202 (已接受)：已接受暫止要求以進行處理。
HTTP 404 (找不到)：找不到指定的執行個體。
HTTP 410 (不存在)：指定的執行個體已完成、失敗或終止。

此 API 的回應不包含任何內容。

繼續執行個體

繼續暫止的協調流程執行個體。

要求

在 Functions 執行階段 2.x 版本中，要求的格式如下 (為了清楚起見，會顯示多行)：

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

欄位	參數類型	描述
`instanceId`	URL	協調流程執行個體的識別碼。
`reason`	查詢字串	選擇性。繼續協調流程執行個體的原因。

可以傳回幾個可能的狀態字碼值。

HTTP 202 (已接受)：已接受繼續要求以進行處理。
HTTP 404 (找不到)：找不到指定的執行個體。
HTTP 410 (不存在)：指定的執行個體已完成、失敗或終止。

此 API 的回應不包含任何內容。

倒轉執行個體 (預覽)

藉由重新執行最近失敗的作業，將失敗的協調流程執行個體還原為執行中狀態。

要求

針對 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	協調流程執行個體的識別碼。
`reason`	查詢字串	選擇性。倒轉協調流程執行個體的原因。

回應

可以傳回幾個可能的狀態字碼值。

HTTP 202 (已接受)：已接受倒轉要求以進行處理。
HTTP 404 (找不到)：找不到指定的執行個體。
HTTP 410 (不存在)：指定的執行個體已完成或終止。

以下是範例要求，它會倒轉失敗的執行個體並且指定修正的原因：

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

此 API 的回應不包含任何內容。

訊號實體

將單向作業訊息傳送至長期實體。如果實體不存在，則會自動建立實體。

注意

從 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	實體的金鑰 (唯一識別碼)。
`op`	查詢字串	選擇性。要叫用的使用者定義作業名稱。
`{content}`	要求內容	JSON 格式的事件裝載。

以下是將使用者定義「新增」訊息傳送至名為 steps 的 Counter 實體的範例要求。訊息內容是值 5。如果實體尚未存在，將會由此要求建立：

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

5

注意

根據預設，透過 .NET 使用以類別為基礎的實體，指定 delete 的 op 值將會刪除實體的狀態。不過，如果實體定義名為 delete 的作業，則會改為叫用該使用者定義的作業。

回應

此作業有數個可能的回應：

HTTP 202 (已接受)：已接受訊號作業以進行非同步處理。
HTTP 400 (不正確的要求)：要求內容不是 application/json 型別、不是有效 JSON，或具有不正確的 entityKey 值。
HTTP 404 (找不到)：找不到指定的 entityName。

成功的 HTTP 要求不包含回應中的任何內容。失敗的 HTTP 要求可能包含回應內容中的 JSON 格式錯誤資訊。

取得實體

取得特定實體的狀態。

要求

HTTP 要求的格式如下 (為了清楚起見，會顯示多行)：

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

回應

此作業有兩個可能的回應：

HTTP 200 (OK)：指定的實體存在。
HTTP 404 (找不到)：找不到指定的實體。

成功的回應包含實體的 JSON 序列化狀態做為其內容。

範例

下列範例 HTTP 要求會取得名為 steps 的現有 Counter 實體狀態：

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

如果 Counter 實體只包含一些儲存在 currentValue 欄位中的步驟，回應內容會看起來如下所示 (為了方便閱讀，已格式化):

{
    "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`	查詢字串	選擇性的參數。指定時，會限制查詢所傳回的實體數目。

回應

成功的 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 型別的前兩個實體，也會擷取其狀態：

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 參考

啟動協調流程

要求

回應

取得執行個體狀態

要求

回應

取得所有執行個體狀態

要求

回應

清除單一執行個體歷程記錄

要求

回應

清除多個執行個體歷程記錄

要求

回應

引發事件

要求

回應

終止執行個體

要求

回應

暫止執行個體

要求

繼續執行個體

要求

倒轉執行個體 (預覽)

要求

回應

訊號實體

要求

回應

取得實體

要求

回應

範例

清單實體

要求

回應

範例 - 列出所有實體

範例 - 篩選實體清單

下一步

意見反映

更多資源