Actors API 参考文档

Dapr 提供了原生、跨平台且跨语言的 virtual actor 功能。 除了特定语言的 SDK外，开发者还可以使用以下 API 端点来调用 actor。

用户服务代码调用 Dapr

调用 actor 方法

通过 Dapr 调用 actor 方法。

HTTP 请求

POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

调用 actor 方法的示例：

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
  -H "Content-Type: application/json"

您可以在请求正文中提供方法参数和值，例如在 curl 中使用 -d "{\"param\":\"value\"}"。调用带参数的 actor 方法的示例：

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json" \
  -d '{
        "destination": "Hoth"
      }'

或

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json" \
  -d "{\"destination\":\"Hoth\"}"

来自远程端点的响应（方法返回值）会在请求正文中返回。

Actor 状态事务

将 actor 的状态更改作为多项事务持久化。

请注意，此操作依赖于使用支持多项事务的状态存储组件。

TTL

在启用了 ActorStateTTL 功能的情况下，actor 客户端可以在事务元数据中设置 ttlInSeconds 字段，使状态在指定的秒数后过期。如果未设置 ttlInSeconds 字段，状态将不会过期。

在构建启用此功能的 actor 应用程序时请记住； 目前，所有 actor SDK 都会在其本地缓存中保留 actor 状态，即使在状态已过期之后。这意味着，如果 TTL 已过期，actor 状态不会从本地缓存中移除，直到 actor 重新启动或停用。此行为将在未来版本中更改。

有关 actor 状态 TTL 的更多详细信息，请参阅 Dapr Community Call 80 录像。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

注意，以下示例使用了 ttlInSeconds 字段，该字段需要启用了 ActorStateTTL 功能。

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
  -H "Content-Type: application/json" \
  -d '[
       {
         "operation": "upsert",
         "request": {
           "key": "key1",
           "value": "myData",
           "metadata": {
             "ttlInSeconds": "3600"
           }
         }
       },
       {
         "operation": "delete",
         "request": {
           "key": "key2"
         }
       }
      ]'

获取 actor 状态

使用指定的键获取 actor 的状态。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
  -H "Content-Type: application/json"

上述命令返回状态：

{
  "location": "Alderaan"
}

创建 actor 提醒

为 actor 创建持久化提醒。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

提醒请求正文

包含以下字段的 JSON 对象：

period 字段支持 time.Duration 格式和 ISO 8601 格式，但有一些限制。对于 period，仅支持 ISO 8601 持续时间 Rn/PnYnMnWnDTnHnMnS 的持续时间格式。Rn/ 指定提醒将被调用 n 次。

• n 应为大于 0 的正整数。
• 如果某些值为 0，可以缩短 period；例如，10 秒可以在 ISO 8601 持续时间中指定为 PT10S。

如果未指定 Rn/，提醒将运行无限次，直到被删除。

如果仅设置了 ttl 和 dueTime，则将接受提醒。但是，只有 dueTime 生效。例如，提醒在 dueTime 触发，而 ttl 被忽略。

如果设置了 ttl、dueTime 和 period，提醒将首先在 dueTime 触发，然后根据 period 和 ttl 重复触发和过期。

以下示例指定了 3 秒的 dueTime 和 7 秒的 period。

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

dueTime 为 0 意味着立即触发。以下正文意味着立即触发，然后每 9 秒触发一次。

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

要将提醒配置为仅触发一次，period 应设置为空字符串。以下内容指定了 3 秒的 dueTime，period 为空字符串，这意味着提醒将在 3 秒后触发，然后再也不会触发。

{
  "dueTime":"0h0m3s0ms",
  "period":""
}

当您在 period 和 ttl 中都指定重复次数时，定时器/提醒会在满足任一条件时停止。以下示例的定时器具有 3 秒的 period（ISO 8601 持续时间格式）和 20 秒的 ttl。此定时器在注册后立即触发，然后在 20 秒的持续时间内每 3 秒触发一次，之后由于 ttl 已满足而不再触发

{
  "period":"PT3S",
  "ttl":"20s"
}

需要 data 的描述。

{
  "data": "someData",
  "dueTime": "1m",
  "period": "20s"
}

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json" \
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s"
    }'

获取 actor 提醒

获取 actor 的提醒。

HTTP 请求

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  "Content-Type: application/json"

上述命令返回提醒：

{
  "dueTime": "1s",
  "period": "5s",
  "data": "0",
}

删除 actor 提醒

删除 actor 的提醒。

HTTP 请求

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json"

创建 actor 定时器

为 actor 创建定时器。

HTTP 请求

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

定时器请求正文：

定时器请求正文的格式与 actor 提醒 相同。例如：

以下内容指定了 3 秒的 dueTime 和 7 秒的 period。

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

dueTime 为 0 意味着立即触发。以下正文意味着立即触发，然后每 9 秒触发一次。

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
    -H "Content-Type: application/json" \
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s",
      "callback": "myEventHandler"
    }'

删除 actor 定时器

删除 actor 的定时器。

HTTP 请求

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
  -H "Content-Type: application/json"

Dapr 调用用户服务代码

获取已注册的 actor

获取此应用程序的已注册 actor 类型和 Dapr actor 配置设置。

HTTP 请求

GET http://localhost:<appPort>/dapr/config

HTTP 响应码

URL 参数

示例

获取已注册 actor 的示例：

curl -X GET http://localhost:3000/dapr/config \
  -H "Content-Type: application/json"

上述命令返回配置（所有字段都是可选的）：

{
  "entities":["actorType1", "actorType2"],
  "actorIdleTimeout": "1h",
  "actorScanInterval": "30s",
  "drainOngoingCallTimeout": "30s",
  "drainRebalancedActors": true,
  "reentrancy": {
    "enabled": true,
    "maxStackDepth": 32
  },
  "entitiesConfig": [
      {
          "entities": ["actorType1"],
          "actorIdleTimeout": "1m",
          "drainOngoingCallTimeout": "10s",
          "reentrancy": {
              "enabled": false
          }
      }
  ]
}

停用 actor

通过将 actor 的实例持久化到具有指定 actorId 的状态存储来停用 actor。

HTTP 请求

DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

以下示例停用 actorId 为 50 的 actor 类型 stormtrooper。

curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
  -H "Content-Type: application/json"

调用 actor 方法

使用指定的 methodName 调用 actor 的方法，其中：

• 方法的参数在请求消息的正文中传递。
• 返回值在响应消息的正文中提供。

如果 actor 尚未运行，应用程序端应激活它。

HTTP 请求

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/<methodName>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

以下示例调用 actorId 为 50 的 actor 类型 stormtrooper 的 performAction 方法。

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/performAction \
  -H "Content-Type: application/json"

调用提醒

使用指定的 reminderName 为 actor 调用提醒。如果 actor 尚未运行，应用程序端应激活它。

HTTP 请求

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

以下示例调用 actorId 为 50 的 actor 类型 stormtrooper 的 checkRebels 提醒方法。

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
  -H "Content-Type: application/json"

调用定时器

使用指定的 timerName 为 actor 调用定时器。如果 actor 尚未运行，应用程序端应激活它。

HTTP 请求

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>

HTTP 响应码

URL 参数

注意，所有 URL 参数都区分大小写。

示例

以下示例调用 actorId 为 50 的 actor 类型 stormtrooper 的 checkRebels 定时器方法。

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
  -H "Content-Type: application/json"

健康检查

探测应用程序以向 Dapr 发出信号，表明应用程序运行正常。 除 200 以外的任何响应状态码都将被视为不健康的响应。

不需要响应正文。

HTTP 请求

GET http://localhost:<appPort>/healthz

HTTP 响应码

URL 参数

示例

从应用程序获取健康检查响应的示例：

curl -X GET http://localhost:3000/healthz \

激活 Actor

从概念上讲，激活 actor 意味着创建 actor 的对象并将 actor 添加到跟踪表中。查看 .NET SDK 中的示例。

外部查询 actor 状态

为了提高 actor 状态的可见性并允许复杂场景（如状态聚合），Dapr 将 actor 状态保存在外部状态存储（如数据库）中。因此，可以通过组合正确的键或查询来外部查询 actor 状态。

Dapr 为 actor 创建的状态命名空间由以下项目组成：

• 应用程序 ID：分配给 Dapr 应用程序的唯一 ID。
• Actor 类型：表示 actor 的类型。
• Actor ID：表示 actor 类型的 actor 实例的唯一 ID。
• 键：特定状态值的键。Actor ID 可以保存多个状态键。

以下示例显示如何为 myapp 应用程序 ID 命名空间下的 actor 实例的状态构造键：

myapp||cat||hobbit||food

在上面的示例中，我们获取状态键 food 的值，对于 actor ID hobbit 和 actor 类型 cat，在 myapp 应用程序 ID 命名空间下。