HTTP API 引用HTTP API reference

Durable Functions 扩展公开一组内置的 HTTP API,这些 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 是扩展性 Webhook,它们由 Azure Functions 主机授权,但由 Durable Functions 扩展直接处理。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. 所有参数的数据类型均为 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 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. 可以使用业务流程客户端绑定 API(例如 .NET 中的 CreateCheckStatusResponseCreateHttpManagementPayload API,或者 JavaScript 中的 createCheckStatusResponsecreateHttpManagementPayload 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.

请求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/orchestrators/{functionName}/{instanceId?}
     ?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/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.

响应Response

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

  • HTTP 202 (已接受) :指定的业务流程协调程序函数已计划开始运行。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 (错误请求) :指定的业务流程协调程序函数不存在、指定的实例 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.

所有字段的数据类型均为 stringThe 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. 默认值为 10The 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.

请求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 article.

响应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 stringstring 实例的运行时状态。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 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,否则此字段为 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. 如果你在函数上有匿名身份验证,则不需要 codeIf 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 article.
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 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.

请求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 筛选在给定 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.

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.

信号实体Signal entity

持久实体发送单向操作消息。Sends a one-way operation message to a Durable Entity. 如果该实体不存在,系统会自动创建它。If the entity doesn't exist, it will be created automatically.

Note

Durable Functions 2.0 开始提供 Durable Entities。Durable Entities are available starting in Durable Functions 2.0.

请求Request

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”消息发送到名为 stepsCounter 实体。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

响应Response

此操作有多种可能的响应:This operation has several possible responses:

  • HTTP 202 (已接受) :已接受对信号操作进行异步处理。HTTP 202 (Accepted): The signal operation was accepted for asynchronous processing.
  • HTTP 400 (错误请求) :请求内容不是 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 (找不到) :找不到指定的 entityTypeHTTP 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.

请求Request

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}

响应Response

此操作有两种可能的响应:This operation has two possible responses:

  • HTTP 200 (正常) :指定的实体存在。HTTP 200 (OK): The specified entity exists.
  • HTTP 404 (找不到) :找不到指定的实体。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

如果 Counter 实体只是包含 currentValue 字段中保存的一些步骤,则响应内容可能如下所示(为方便阅读,已设置响应的格式):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
}