mirror of https://github.com/dapr/docs.git
Merge branch 'master' into master
This commit is contained in:
Aman Bhardwaj
GitHub
commit
133aaeae13
|
|
@ -1,19 +1,19 @@
|
|||
# Actors
|
||||
|
||||
Dapr has a native, cross platform and cross-language virtual actor capabilities.
|
||||
Dapr provides native, cross-platform and cross-language virtual actor capabilities.
|
||||
Besides the language specific Dapr SDKs, a developer can invoke an actor using the API endpoints below.
|
||||
|
||||
## Specifications for user service code calling to Dapr
|
||||
|
||||
### Invoke a method on an Actor
|
||||
### Invoke Actor Method
|
||||
|
||||
This endpoint lets you invoke a method on a remote Actor.
|
||||
Invokes a method on an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -25,19 +25,19 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
method | the name of the method to invoke on the remote actor
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
method | The name of the method to invoke.
|
||||
|
||||
> Example of invoking a method on a remote actor:
|
||||
> Example of invoking a method on an actor:
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
> Example of invoking a method on a remote actor with a payload:
|
||||
> Example of invoking a method on an actor with a payload:
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
|
||||
|
|
@ -49,15 +49,15 @@ curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
|
|||
|
||||
> The response from the remote endpoint will be returned in the request body.
|
||||
|
||||
### Save actor state
|
||||
### Save Actor State
|
||||
|
||||
This endpoint lets you save state for a given actor for a given key.
|
||||
Saves the state for an actor using a specified key.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -69,10 +69,10 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
key | key for the state value
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
key | The key for the state value.
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
|
||||
|
|
@ -82,17 +82,17 @@ curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
|
|||
}'
|
||||
```
|
||||
|
||||
### Save actor state - transaction
|
||||
### Save Actor State - Transaction
|
||||
|
||||
This endpoint lets you save an actor's state as a multi item transaction.
|
||||
Saves the state for an actor as a multi-item transaction.
|
||||
|
||||
***Note that this operation is dependant on a state store that supports multi item transactions.***
|
||||
***Note that this operation is dependant on a state store that supports multi-item transactions.***
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -104,9 +104,9 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
|
||||
|
|
@ -128,15 +128,15 @@ curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
|
|||
]'
|
||||
```
|
||||
|
||||
### Get actor state
|
||||
### Get Actor State
|
||||
|
||||
This endpoint lets you get the state of a given actor for a given key.
|
||||
Gets the state for an actor using a specified key.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -148,10 +148,10 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
key | key for the state value
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
key | The key for the state value.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
|
||||
|
|
@ -166,15 +166,15 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
|
|||
}
|
||||
```
|
||||
|
||||
### Delete actor state
|
||||
### Delete Actor State
|
||||
|
||||
This endpoint lets you delete the state of a given actor for a given key.
|
||||
Deletes the state for an actor using a specified key.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -186,25 +186,25 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
key | key for the state value
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
key | The key for the state value.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
|
||||
-X "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Set actor reminder
|
||||
### Create Actor Reminder
|
||||
|
||||
This endpoint lets you create a persistent reminder for an actor.
|
||||
Creates a persistent reminder for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -216,10 +216,10 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
name | the name of the reminder
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
name | The name of the reminder to create.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
|
||||
|
|
@ -231,15 +231,15 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
|
|||
}'
|
||||
```
|
||||
|
||||
### Get actor reminder
|
||||
### Get Actor Reminder
|
||||
|
||||
This endpoint lets get a reminder for an actor
|
||||
Gets a reminder for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -251,10 +251,10 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
name | the name of the reminder to get
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
name | The name of the reminder to get.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
|
||||
|
|
@ -271,15 +271,15 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
|
|||
}
|
||||
```
|
||||
|
||||
### Delete actor reminder
|
||||
### Delete Actor Reminder
|
||||
|
||||
This endpoint lets delete a reminder for an actor
|
||||
Deletes a reminder for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -291,25 +291,25 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
name | the name of the reminder to delete
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
name | The name of the reminder to delete.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
|
||||
-X "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Set actor timer
|
||||
### Create Actor Timer
|
||||
|
||||
This endpoint lets you create a timer for an actor.
|
||||
Creates a timer for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -321,10 +321,10 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
name | the name of the timer
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
name | The name of the timer to create.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
|
||||
|
|
@ -337,15 +337,15 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
|
|||
}'
|
||||
```
|
||||
|
||||
### Delete actor timer
|
||||
### Delete Actor Timer
|
||||
|
||||
This endpoint lets delete a timer for an actor
|
||||
Deletes a timer for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -357,10 +357,10 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
name | the name of the timer to delete
|
||||
daprPort | The Dapr port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
name | The name of the timer to delete.
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
|
||||
|
|
@ -371,13 +371,13 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
|
|||
|
||||
### Get Registered Actors
|
||||
|
||||
This endpoint lets you get the registered actors in Dapr.
|
||||
Gets the registered actors in Dapr.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`GET http://localhost:<appPort>/dapr/config`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -388,7 +388,7 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
appPort | the application port
|
||||
appPort | The application port.
|
||||
|
||||
> Example of getting the registered actors:
|
||||
|
||||
|
|
@ -409,15 +409,15 @@ curl -X GET http://localhost:3000/dapr/config \
|
|||
}
|
||||
```
|
||||
|
||||
### Activate the Actors
|
||||
### Activate Actor
|
||||
|
||||
This endpoint lets you activate the actor.
|
||||
Activates an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`POST http://localhost:<appPort>/actors/<actorType>/<actorId>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -429,26 +429,26 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
appPort | the application port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
appPort | The application port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
|
||||
> Example of activating the actor:
|
||||
> Example of activating an actor:
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3000/actors/stormtrooper/50 \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Deactivate the Actors
|
||||
### Deactivate Actor
|
||||
|
||||
This endpoint lets you deactivate the actor.
|
||||
Deactivates an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -460,26 +460,26 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
appPort | the application port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
appPort | The application port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
|
||||
> Example of deactivating the actor:
|
||||
> Example of deactivating an actor:
|
||||
|
||||
```shell
|
||||
curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Invoke the Reminders
|
||||
### Invoke Reminder
|
||||
|
||||
This endpoint lets you invokes the actor reminders.
|
||||
Invokes a reminder for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -491,27 +491,27 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
appPort | the application port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
reminderName | the name of the reminder
|
||||
appPort | The application port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
reminderName | The name of the reminder to invoke.
|
||||
|
||||
> Example of invoking the actor reminder:
|
||||
> Example of invoking a reminder for an actor:
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
### Invoke the Timers
|
||||
### Invoke Timer
|
||||
|
||||
This endpoint lets you invokes the actor timers.
|
||||
Invokes a timer for an actor.
|
||||
|
||||
#### HTTP Request
|
||||
|
||||
`PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>`
|
||||
|
||||
#### HTTP Response codes
|
||||
#### HTTP Response Codes
|
||||
|
||||
Code | Description
|
||||
---- | -----------
|
||||
|
|
@ -523,28 +523,28 @@ Code | Description
|
|||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
appPort | the application port
|
||||
actorType | the actor type
|
||||
actorId | the actor id
|
||||
timerName | the name of the timer
|
||||
appPort | The application port.
|
||||
actorType | The actor type.
|
||||
actorId | The actor ID.
|
||||
timerName | The name of the timer to invoke.
|
||||
|
||||
> Example of invoking the actor timer:
|
||||
> Example of invoking a timer for an actor:
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
## Querying actor state externally
|
||||
## Querying Actor State Externally
|
||||
|
||||
In order to promote visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external 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:
|
||||
|
||||
* Dapr ID - represents the unique ID given to the Dapr application.
|
||||
* Actor Type - represents the type of the actor
|
||||
* Actor ID - represents the unique ID of the actor instance for an actor type
|
||||
* Dapr ID - Represents the unique ID given to the Dapr application.
|
||||
* Actor Type - Represents the type of the actor.
|
||||
* Actor ID - Represents the unique ID of the actor instance for an actor type.
|
||||
* Key - A key for the specific state value. An actor ID can hold multiple state keys.
|
||||
|
||||
The following example shows how to construct a key for the state of an actor instance under the `myapp` Dapr ID namespace:
|
||||
|
|
|
|||
Loading…
Reference in New Issue