Durable Functions 中的 HTTP API (Azure Functions)HTTP 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 都是 Webhook 操作,可由 Durable Task 扩展直接处理。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.

Note

此外,也可使用 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. 下面的 HTTP 触发型函数示例演示了如何使用此 API: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. 所有字段的数据类型均为 stringThe 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 业务流程实例的“后退”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"
}

Note

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 触发器返回 HTTP 202 响应,其中包含带有 statusQueryGetUri 值的 Location 标头。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.

Note

默认情况下,Azure 逻辑应用提供的所有基于 HTTP 的操作都支持标准异步操作模式。By default, all HTTP-based actions provided by Azure Logic Apps support the standard asynchronous operation pattern. 使用此功能,可在逻辑应用工作流中嵌入长时间运行的持久函数。This capability makes it possible to embed a long-running durable function as part of a Logic Apps workflow. 有关异步 HTTP 模式的逻辑应用支持的更多详细信息,请参阅 Azure 逻辑应用工作流操作和触发器文档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. 所有参数的数据类型均为 stringThe 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. 发现 systemKey 值的最简单的方法是使用上文提及的 CreateCheckStatusResponse API。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.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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]

在 2.x 版 Functions 运行时中,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.

响应Response

可返回若干可能的状态代码值。Several possible status code values can be returned.

  • HTTP 200 (正常):指定的实例处于已完成状态。HTTP 200 (OK): The specified instance is in a completed state.
  • HTTP 202 (已接受):指定实例正在进行中。HTTP 202 (Accepted): The specified instance is in progress.
  • HTTP 400 (错误请求):指定的实例已失败或被终止。HTTP 400 (Bad Request): The specified instance failed or was terminated.
  • HTTP 404 (找不到):指定的实例不存在或未开始运行。HTTP 404 (Not Found): The specified instance doesn't exist or has not started running.
  • HTTP 500 (内部服务器错误):指定的实例因未处理的异常而失败。HTTP 500 (Internal Server Error): The specified instance failed with an unhandled exception.

值为 HTTP 200 和 HTTP 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 字符串string 实例的运行时状态。The runtime status of the instance. 相关的值为:正在运行、挂起、失败、已取消、已终止和已完成。Values include Running, Pending, Failed, Canceled, Terminated, Completed.
input JSONJSON 用于初始化实例的 JSON 数据。The JSON data used to initialize the instance. 如果 showInput 查询字符串参数设置为 false,则此字段为 nullThis field is null if the showInput query string parameter is set to false.
customStatus JSONJSON 用于自定义业务流程状态的 JSON 数据。The JSON data used for custom orchestration status. 如果未设置,此字段为 nullThis field is null if not set.
output JSONJSON 实例的 JSON 输出。The JSON output of the instance. 如果实例不是已完成状态,则该字段为 nullThis field is null if the instance is not in a completed state.
createdTime 字符串string 创建实例的时间。The time at which the instance was created. 使用 ISO 8601 扩展表示法。Uses ISO 8601 extended notation.
lastUpdatedTime 字符串string 实例持续的时间。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,否则此字段为 nullThis 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 响应还包括 Location 响应标头,该标头引用了与上文提及的 statusQueryGetUri 字段相同的 URL。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.

要记住的一件事是 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.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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}

在 2.x 版 Functions 运行时中,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.

响应Response

以下是包含业务流程状态的响应有效负载的示例(为可读性而设置了格式):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"
    }
]

Note

如果实例表中有很多行,则此操作在 Azure存储 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-tokenThe 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-tokenThis 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.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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}

在 2.x 版 Functions 运行时中,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.

响应Response

可以返回以下 HTTP 状态代码值。The following HTTP status code values can be returned.

  • HTTP 200 (正常):已成功清除实例历史记录。HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (找不到):指定的实例不存在。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. 对于单个实例,此值应始终为 1For 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.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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,...}

在 2.x 版 Functions 运行时中,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 可选参数。Optional parameter. 指定后,将筛选在给定 ISO8601 时间戳当时或之后创建的已清除实例列表。When specified, 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.

如果未指定参数,则会清除任务中心内的所有实例。If no parameters are specified, all instances in the task hub will be purged.

Note

如果“实例”和/或“历史记录”表中包含许多的行,则此操作可能会导致很高的 Azure 存储 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.

响应Response

可以返回以下 HTTP 状态代码值。The following HTTP status code values can be returned.

  • HTTP 200 (正常):已成功清除实例历史记录。HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (找不到):找不到与筛选表达式匹配的实例。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.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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}

在 2.x 版 Functions 运行时中,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.

响应Response

可返回若干可能的状态代码值。Several possible status code values can be returned.

  • HTTP 202 (已接受):已接受引发的事件,正在处理。HTTP 202 (Accepted): The raised event was accepted for processing.
  • HTTP 400 (错误请求):请求内容不属于 application/json 类型或不是有效的 JSON。HTTP 400 (Bad request): The request content was not of type application/json or was not valid JSON.
  • HTTP 404 (找不到):找不到指定的实例。HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (消失):指定的实例已完成或失败,且无法处理任何引发的事件。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.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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}

在 2.x 版 Functions 运行时中,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.

响应Response

可返回若干可能的状态代码值。Several possible status code values can be returned.

  • HTTP 202 (已接受):已接受终止请求,正在处理。HTTP 202 (Accepted): The terminate request was accepted for processing.
  • HTTP 404 (找不到):找不到指定的实例。HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (消失):指定的实例已完成或失败。HTTP 410 (Gone): The specified instance has completed or failed.

下面的示例请求终止正在运行的实例,并将原因指定为 buggy: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 instance (preview)

通过重播最近的失败操作,将失败的业务流程实例还原到运行状态。Restores a failed orchestration instance into a running state by replaying the most recent failed operations.

请求Request

对于 1.x 版 Functions 运行时,请求格式如下(为简洁起见,已分多行显示):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}

在 2.x 版 Functions 运行时中,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. 后退业务流程实例的原因。The reason for rewinding the orchestration instance.

响应Response

可返回若干可能的状态代码值。Several possible status code values can be returned.

  • HTTP 202 (已接受):已接受回退请求,正在处理。HTTP 202 (Accepted): The rewind request was accepted for processing.
  • HTTP 404 (找不到):找不到指定的实例。HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (消失):指定的实例已完成或被终止。HTTP 410 (Gone): The specified instance has completed or was terminated.

以下是一个示例请求,它会后退失败的实例并指定修复的原因: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