Actors API 参考

Dapr 提供原生、跨平台和跨语言 virtual actors 功能。 Besides the language specific SDKs, a developer can invoke an actor using the API endpoints below.

调用 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 状态的变成以 multi-item transaction 的方式持久化

请注意，此操作取决于支持 multi-item transactions 的状态存储组件。

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 reminders

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

HTTP 请求

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

Body:

The following specifies a dueTime of 3 seconds and a period of 7 seconds.

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

A dueTime of 0 means to fire immediately. The following body means to fire immediately, then every 9 seconds.

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

To configure the reminder to fire once only, the period should be set to empty string. The following specifies a dueTime of 3 seconds with a period of empty string, which means the reminder will fire in 3 seconds and then never fire again.

{
  "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 reminders

Gets a reminder for an 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"

The above command returns the reminder:

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

删除 actor reminders

Deletes a reminder for an 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 timers

Creates a timer for an actor.

HTTP 请求

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

Body:

The following specifies a dueTime of 3 seconds and a period of 7 seconds.

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

A dueTime of 0 means to fire immediately. The following body means to fire immediately, then every 9 seconds.

{
  "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 timers

Deletes a timer for an 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 调用用户服务

获取注册的 Actors

Gets the registered actors types for this app and the Dapr actor configuration settings.

HTTP 请求

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

HTTP 响应码

URL 参数

示例

Example of getting the registered actors:

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

The above command returns the config (all fields are optional):

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

停用 actor

Deactivates an actor by persisting the instance of the actor to the state store with the specified actorId

HTTP 请求

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

HTTP 响应码

URL 参数

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

示例

Example of deactivating an actor: The example deactives the actor type stormtrooper that has actorId of 50

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

调用 actor 方法

Invokes a method for an actor with the specified methodName where parameters to the method are passed in the body of the request message and return values are provided in the body of the response message. If the actor is not already running, the app side should activate it.

HTTP 请求

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

HTTP 响应码

URL 参数

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

示例

Example of invoking a method for an actor: The example calls the performAction method on the actor type stormtrooper that has actorId of 50

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

调用 reminders

Invokes a reminder for an actor with the specified reminderName. If the actor is not already running, the app side should activate it.

HTTP 请求

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

HTTP 响应码

URL 参数

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

示例

Example of invoking a reminder for an actor: The example calls the checkRebels reminder method on the actor type stormtrooper that has actorId of 50

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

调用 timer

Invokes a timer for an actor rwith the specified timerName. If the actor is not already running, the app side should activate it.

HTTP 请求

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

HTTP 响应码

URL 参数

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

示例

Example of invoking a timer for an actor: The example calls the checkRebels timer method on the actor type stormtrooper that has actorId of 50

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

健康检查

Probes the application for a response to signal to Dapr that the app is healthy and running. Any other response status code other than 200 will be considered as an unhealthy response.

A response body is not required.

HTTP 请求

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

HTTP 响应码

URL 参数

示例

Example of getting a health check response from the app:

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

激活 Actor

Conceptually, activating an actor means creating the actor’s object and adding the actor to a tracking table. Here is an example from the .NET SDK.

外部查询 actor 状态

In order to enable visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external state stores such as databases. As such, it is possible to query for an actor state externally by composing the correct key or query.

The state namespace created by Dapr for actors is composed of the following items:

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

The following example shows how to construct a key for the state of an actor instance under the myapp App ID namespace: myapp||cat||hobbit||food

In the example above, we are getting the value for the state key food, for the actor ID hobbit with an actor type of cat, under the App ID namespace of myapp.