HTTP API 引用

  • 项目

Durable Functions 扩展公开一组内置的 HTTP API，这些 API 可以用来在业务流程、实体和任务中心中执行管理任务。 这些 HTTP API 是扩展性 Webhook，它们由 Azure Functions 主机授权，但由 Durable Functions 扩展直接处理。

本文中提到的 API 的基 URL 与函数应用的基 URL 相同。 使用 Azure Functions Core Tools 在本地进行开发时，基 URL 通常为 http://localhost:7071。 在 Azure Functions 托管服务中，基 URL 通常为 https://{appName}.chinacloudsites.cn。 自定义主机名如果是在应用服务应用上进行配置的，则也受支持。

由扩展实现的所有 HTTP API 均需要以下参数。 所有参数的数据类型均为 string。

参数 参数类型 说明
taskHub 查询字符串 任务中心的名称。 如果未指定，则使用当前函数应用的任务中心名称。
connection 查询字符串 后端存储提供程序的连接应用程序设置的名称。 如果未指定，则使用函数应用的默认连接配置。
systemKey 查询字符串 需要授权密钥才可调用 API。

systemKey 是 Azure Functions 主机自动生成的授权密钥。 它可专门向 Durable Task 扩展 API 授予访问权限，且可通过与管理其他 Azure Functions 访问密钥相同的方式进行管理。 可以使用业务流程客户端绑定 API（例如 .NET 中的 CreateCheckStatusResponse 和 CreateHttpManagementPayload API、JavaScript 中的 createCheckStatusResponse 和 createHttpManagementPayload API 等）生成包含正确的 taskHub、connection 和 systemKey 查询字符串值的 URL。

后面几节介绍扩展支持的特殊 HTTP API，并提供有关其用法的示例。

启动业务流程

开始执行指定的业务流程协调程序函数的新实例。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，URL 格式包含的所有参数相同，但前缀略有不同：

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

此 API 的请求参数包括前面提及的默认集及以下唯一参数：

字段 参数类型 说明
functionName URL 要启动的业务流程协调程序函数的名称。
instanceId URL 可选参数。 业务流程实例的 ID。 如果未指定，业务流程协调程序函数会使用随机实例 ID 启动。
{content} 请求内容 可选。 JSON 格式的业务流程协调程序函数输入。

响应

可返回若干可能的状态代码值。

  • HTTP 202 (已接受)：指定的业务流程协调程序函数已计划开始运行。 Location 响应标头包含一个 URL，用于轮询业务流程状态。
  • HTTP 400 (错误请求)：指定的业务流程协调程序函数不存在、指定的实例 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 响应旨在与轮询使用者模式兼容。 它还包括以下值得注意的响应标头：

  • 位置：状态终结点的 URL。 此 URL 包含的值与 statusQueryGetUri 字段的值相同。
  • 重试间隔：在执行下一个轮询操作之前应等待的秒数。 默认值为 10。

有关异步 HTTP 轮询模式的详细信息，请参阅 HTTP 异步操作跟踪文档。

获取实例状态

获取指定业务流程实例的状态。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，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 500 响应而不是 200。 此参数适用于自动状态轮询方案。

响应

可返回若干可能的状态代码值。

  • HTTP 200 (正常) ：指定实例的状态为已完成或失败。
  • HTTP 202 (已接受)：指定实例正在进行中。
  • HTTP 400 (错误请求)：指定实例失败或已终止。
  • HTTP 404 (找不到)：指定实例不存在或未开始运行。
  • HTTP 500 (内部服务器错误) ：仅当 returnInternalServerErrorOnFailure 设置为 true 且指定实例失败并出现未经处理的异常时才返回。

值为 HTTP 200 和 HTTP 202 时的响应负载是包含以下字段的 JSON 对象：

字段 数据类型 说明
runtimeStatus 字符串 实例的运行时状态。 相关的值为：“Running”、“Pending”、“Failed”、“Canceled”、“Terminated”、“Completed”、“Suspended”。
input JSON 用于初始化实例的 JSON 数据。 如果 showInput 查询字符串参数设置为 false，则此字段为 null。
customStatus JSON 用于自定义业务流程状态的 JSON 数据。 如果未设置，此字段为 null。
output JSON 实例的 JSON 输出。 如果实例不是已完成状态，则该字段为 null。
createdTime 字符串 创建实例的时间。 使用 ISO 8601 扩展表示法。
lastUpdatedTime 字符串 实例持续的时间。 使用 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 响应还包括 Location 响应标头，该标头引用了与上文提及的 statusQueryGetUri 字段相同的 URL。

获取所有实例状态

此外，可以通过从“获取实例状态”请求中删除 instanceId，来查询所有实例的状态。 在这种情况下，基本参数与“获取实例状态”相同。 也支持使用查询字符串参数进行筛选。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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}

在 2.x 版 Functions 运行时中，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 查询字符串 可选参数。 如果指定，则会限制查询返回的实例数。

响应

以下是包含业务流程状态的响应有效负载的示例（为可读性而设置了格式）：

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

清除单个实例的历史记录

删除指定业务流程实例的历史记录和相关项目。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，URL 格式包含的所有参数相同，但前缀略有不同：

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

此 API 的请求参数包括前面提及的默认集及以下唯一参数：

字段 参数类型 说明
instanceId URL 业务流程实例的 ID。

响应

可以返回以下 HTTP 状态代码值。

  • HTTP 200 (正常)：已成功清除实例历史记录。
  • HTTP 404 (找不到)：指定的实例不存在。

值为 HTTP 200 时的响应有效负载是包含以下字段的 JSON 对象：

字段 数据类型 说明
instancesDeleted integer 删除的实例数。 对于单个实例，此值应始终为 1。

以下是响应负载的示例（为提高可读性设置了格式）：

{
    "instancesDeleted": 1
}

清除多个实例的历史记录

也可以通过删除“清除单个实例的历史记录”请求中的 {instanceId}，来删除任务中心内多个实例的历史记录和相关项目。 若要有选择地清除实例历史记录，请使用“获取所有实例状态”请求中所述的相同筛选器。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，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 (正常)：已成功清除实例历史记录。
  • HTTP 404 (找不到)：未找到与筛选器表达式匹配的实例。

值为 HTTP 200 时的响应有效负载是包含以下字段的 JSON 对象：

字段 数据类型 说明
instancesDeleted integer 删除的实例数。

以下是响应负载的示例（为提高可读性设置了格式）：

{
    "instancesDeleted": 250
}

引发事件

向正在运行的业务流程实例发送事件通知消息。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，URL 格式包含的所有参数相同，但前缀略有不同：

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

此 API 的请求参数包括前面提及的默认集及以下唯一参数：

字段 参数类型 说明
instanceId URL 业务流程实例的 ID。
eventName URL 目标业务流程正在等待的事件的名称。
{content} 请求内容 JSON 格式的事件负载。

响应

可返回若干可能的状态代码值。

  • HTTP 202 (已接受)：已接受引发的事件，正在处理。
  • HTTP 400 (错误请求)：请求内容不属于 application/json 类型或不是有效的 JSON。
  • HTTP 404 (找不到)：找不到指定的实例。
  • HTTP 410 (消失)：指定的实例已完成或失败，且无法处理任何引发的事件。

下面的请求示例向等待名为 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 的响应不包含任何内容。

终止实例

终止正在运行的业务流程实例。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，URL 格式包含的所有参数相同，但前缀略有不同：

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

此 API 的请求参数包括前面提及的默认集及以下唯一参数。

字段 参数类型 说明
instanceId URL 业务流程实例的 ID。
reason 查询字符串 可选。 终止业务流程实例的原因。

响应

可返回若干可能的状态代码值。

  • HTTP 202 (已接受)：已接受终止请求，正在处理。
  • HTTP 404 (找不到)：找不到指定的实例。
  • HTTP 410 (消失)：指定的实例已完成或失败。

下面的示例请求终止正在运行的实例，并将原因指定为 buggy：

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

此 API 的响应不包含任何内容。

暂停实例

暂停正在运行的业务流程实例。

请求

在 2.x 版 Functions 运行时中，请求格式如下（为简洁起见，已分多行显示）：

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
字段 参数类型 说明
instanceId URL 业务流程实例的 ID。
reason 查询字符串 可选。 暂停业务流程实例的原因。

可返回若干可能的状态代码值。

  • HTTP 202 (已接受)：已接受暂停请求以进行处理。
  • HTTP 404 (找不到)：找不到指定的实例。
  • HTTP 410 (消失)：指定的实例已完成、已失败或已终止。

此 API 的响应不包含任何内容。

继续实例

继续暂停的业务流程实例。

请求

在 2.x 版 Functions 运行时中，请求格式如下（为简洁起见，已分多行显示）：

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
字段 参数类型 说明
instanceId URL 业务流程实例的 ID。
reason 查询字符串 可选。 继续业务流程实例的原因。

可返回若干可能的状态代码值。

  • HTTP 202 (已接受)：已接受继续请求以进行处理。
  • HTTP 404 (找不到)：找不到指定的实例。
  • HTTP 410 (消失)：指定的实例已完成、已失败或已终止。

此 API 的响应不包含任何内容。

回退实例（预览版）

通过重播最近的失败操作，将失败的业务流程实例还原为运行状态。

请求

对于 1.x 版 Functions 运行时，请求格式如下（为简洁起见，已分多行显示）：

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

在 2.x 版 Functions 运行时中，URL 格式包含的所有参数相同，但前缀略有不同：

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

此 API 的请求参数包括前面提及的默认集及以下唯一参数。

字段 参数类型 说明
instanceId URL 业务流程实例的 ID。
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 开始提供 Durable Entities。

请求

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

注意

默认情况下，使用 .NET 中基于类的实体时，将 op 值指定为 delete 会删除实体的状态。 但是，如果实体定义名为 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 (正常)：指定的实体存在。
  • 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 监视持久函数