The documentation you are viewing is for Dapr v1.2 which is an older version of Dapr. For up-to-date documentation, see the latest version.
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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
XXX | 来自上游调用的状态代码 |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
method | 要调用的方法的名称。 |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
204 | 请求成功 |
400 | 未找到 Actor |
500 | 请求失败 |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
204 | 找不到键值,响应将为空 |
400 | 未找到 Actor |
500 | 请求失败 |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
key | 状态的 key |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
400 | Actor not found or malformed request |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
name | The name of the reminder to create. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
name | The name of the reminder to get. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
name | The name of the reminder to delete. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
400 | Actor not found or malformed request |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
name | The name of the timer to create. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
204 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 说明 |
---|---|
daprPort | Dapr 端口。 |
actorType | Actor 类型。 |
actorId | Actor ID |
name | The name of the timer to delete. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
URL 参数
参数 | 说明 |
---|---|
appPort | The application port. |
示例
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 | The actor types this app supports. |
actorIdleTimeout | Specifies how long to wait before deactivating an idle actor. An actor is idle if no actor method calls and no reminders have fired on it. |
actorScanInterval | A duration which specifies how often to scan for actors to deactivate idle actors. Actors that have been idle longer than the actorIdleTimeout will be deactivated. |
drainOngoingCallTimeout | A duration used when in the process of draining rebalanced actors. This specifies how long to wait for the current active actor method to finish. 如果没有当前 actor 方法调用,那么将忽略此时间。 |
drainRebalancedActors | A bool. If true, Dapr will wait for drainOngoingCallTimeout to allow a current actor call to complete before trying to deactivate an actor. If false, do not wait. |
{
"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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 Actor |
URL 参数
参数 | 说明 |
---|---|
appPort | The application port. |
actorType | Actor 类型。 |
actorId | Actor ID |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 Actor |
URL 参数
参数 | 说明 |
---|---|
appPort | The application port. |
actorType | Actor 类型。 |
actorId | Actor ID |
methodName | 要调用的方法的名称。 |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 Actor |
URL 参数
参数 | 说明 |
---|---|
appPort | The application port. |
actorType | Actor 类型。 |
actorId | Actor ID |
reminderName | The name of the reminder to invoke. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | 请求成功 |
500 | 请求失败 |
404 | 未找到 Actor |
URL 参数
参数 | 说明 |
---|---|
appPort | The application port. |
actorType | Actor 类型。 |
actorId | Actor ID |
timerName | The name of the timer to invoke. |
注意:所有的 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 响应码
代码 | 说明 |
---|---|
200 | App is healthy |
URL 参数
参数 | 说明 |
---|---|
appPort | The application port. |
示例
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
.