Actors API 参考

Dapr 提供原生、跨平台和跨语言的 virtual actors 功能。 除了 特定语言的 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"

若 Actor 方法具备参数：您可以在请求正文中提供方法参数和值，例如使用 -d “{"param":"value"}”

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

or

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

被调用方法的返回值将会从响应正文中返回。

Actor 状态事务

以多项事务的方式将 actor 变更的状态持久化。

请注意，该具体操作取决于支持多项事务的状态存储组件。

HTTP 请求

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

HTTP 响应码

URL 参数

注意：所有的 URL 参数都是大小写敏感的。

示例

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"
         }
       },
       {
         "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 reminder

为 actor 创建一个持久化的 reminder。

HTTP 请求

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

Request Body

JSON 对象将具有以下字段：

period 字段支持 time.Duration 格式和 ISO 8601 格式(有一些限制)。 period 仅支持 ISO 8601 持续时间格式， Rn/PnYnMnWnDTnHnMnS 。 此处 Rn/ 指定将调用提醒 n 次。 这里的 n 应该为正整数。 如果某些值为 0，则 period 可以缩短， 例如10秒持续时间可以在ISO 8601 中被指定为 PT10S。 如果未指定 Rn/ ，则提醒将运行无限次，直到删除。

以下指定 dueTime 的 3 秒和 7 秒的句点。

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

dueTime 为0表示立即执行。 以下正文是指立即执行，然后每 9 秒钟再执行一次。

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

要将 reminders 配置为仅触发一次，应将 period 设置为空字符串。 以下 dueTime 为 3 秒，period 为空字符串，这意味着 reminder 将在 3 秒后立即执行，然后永远不会再次触发。

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

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 reminder

获取一个 actor 的 reminder。

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"

以上命令将返回 reminders:

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

删除 actor reminders

删除一个 actor 的 reminders。

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 timer

创建一个 actor 的 reminder。

HTTP 请求

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

Body:

以下明确了 dueTime 的 3 秒和 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 timer

删除一个 actor 的 timer。

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 调用业务的应用服务

获取注册的 Actors

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

HTTP 请求

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

HTTP 响应码

URL 参数

示例

获取注册的 actors 的示例:

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

以上命令返回配置 ( 所有字段都是可选的):

{
  "entities":["actorType1", "actorType2"],
  "actorIdleTimeout": "1h",
  "actorScanInterval": "30s",
  "drainOngoingCallTimeout": "30s",
  "drainRebalancedActors": true
}

停用 actor

通过将 指定 actor Id 的 actor 保留到状态存储与来停用 actor

HTTP 请求

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

HTTP 响应码

URL 参数

注意：所有的 URL 参数都是大小写敏感的。

示例

取消激活 actor 的示例: 该示例取消激活 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 参数都是大小写敏感的。

示例

对 actor 调用方法的示例: 该示例调用 actorId 为 50 的 actor 类型 stormtrooper上的 performAction 方法

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

调用 reminders

调用具有指定的 reminderName 的 actor 的 reminders。 如果 actor 尚未运行，那么应用程序方应先激活它。

HTTP 请求

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

HTTP 响应码

URL 参数

注意：所有的 URL 参数都是大小写敏感的。

示例

对 actor 调用 reminders 的示例: 该示例调用 actorId 为 50 的参与者类型 stormtrooper 上的 checkRebels reminders 方法

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

调用 timer

为具有指定 timerName 的 actor 调用 timer。 如果 actor 尚未运行，那么应用程序方应先激活它。

HTTP 请求

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

HTTP 响应码

URL 参数

注意：所有的 URL 参数都是大小写敏感的。

示例

为 actor 调用 timer 的示例: 该示例调用 actorId 为 50 的 actor 类型 stormtrooper 上的 checkRebels timer 方法

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 为 Actors 创建的状态名称空间由以下项组成:

• App ID - 表示给 Dapr 应用程序的唯一 ID。
• Actor 类型 - 表示 actor 的类型。
• Actor ID - 代表 actor 类型的 actor 实例的唯一ID。
• Key - 特定状态值的键。 Actor ID 标识可以保存多个状态键。

下面的示例演示如何在 myapp 应用程序 ID 命名空间下为 actor 实例的状态构造状态名称空间： myapp||cat||hobbit||food

在以上示例中，我们在 myapp 的应用标识名称空间下，为 actor ID 为 hobbit ( actor 类型为 cat) 获取状态键 food的值。