dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into yamlname

This commit is contained in:
Leon Mai 2019-11-25 11:07:16 -08:00 committed by GitHub
parent 3eaf9b946c e113f06cbc
commit 9c797c9954
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 110 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
reference/api/actors.md
View File

@ -1,19 +1,19 @@
# Actors # 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. 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 ## 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 #### HTTP Request
`POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>` `POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -25,19 +25,19 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
method | the name of the method to invoke on the remote actor 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 ```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \ curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
-H "Content-Type: application/json" -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 ```shell
curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \ 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. > 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 #### HTTP Request
`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>` `POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -69,10 +69,10 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
key | key for the state value key | The key for the state value.
```shell ```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \ 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 #### HTTP Request
`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state` `POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -104,9 +104,9 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
```shell ```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \ 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 #### HTTP Request
`GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>` `GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -148,10 +148,10 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
key | key for the state value key | The key for the state value.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \ 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 #### HTTP Request
`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>` `DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -186,25 +186,25 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
key | key for the state value key | The key for the state value.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \ curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
-X "Content-Type: application/json" -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 #### HTTP Request
`POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>` `POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -216,10 +216,10 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
name | the name of the reminder name | The name of the reminder to create.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ 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 #### HTTP Request
`GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>` `GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -251,10 +251,10 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
name | the name of the reminder to get name | The name of the reminder to get.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ 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 #### HTTP Request
`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>` `DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -291,25 +291,25 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
name | the name of the reminder to delete name | The name of the reminder to delete.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-X "Content-Type: application/json" -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 #### HTTP Request
`POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>` `POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -321,10 +321,10 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
name | the name of the timer name | The name of the timer to create.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \ 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 #### HTTP Request
`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>` `DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -357,10 +357,10 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
daprPort | the Dapr port daprPort | The Dapr port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
name | the name of the timer to delete name | The name of the timer to delete.
```shell ```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \ 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 ### Get Registered Actors
This endpoint lets you get the registered actors in Dapr. Gets the registered actors in Dapr.
#### HTTP Request #### HTTP Request
`GET http://localhost:<appPort>/dapr/config` `GET http://localhost:<appPort>/dapr/config`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -388,7 +388,7 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
appPort | the application port appPort | The application port.
> Example of getting the registered actors: > 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 #### HTTP Request
`POST http://localhost:<appPort>/actors/<actorType>/<actorId>` `POST http://localhost:<appPort>/actors/<actorType>/<actorId>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -429,26 +429,26 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
appPort | the application port appPort | The application port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
> Example of activating the actor: > Example of activating an actor:
```shell ```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50 \ curl -X POST http://localhost:3000/actors/stormtrooper/50 \
-H "Content-Type: application/json" -H "Content-Type: application/json"
``` ```
### Deactivate the Actors ### Deactivate Actor
This endpoint lets you deactivate the actor. Deactivates an actor.
#### HTTP Request #### HTTP Request
`DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>` `DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -460,26 +460,26 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
appPort | the application port appPort | The application port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
> Example of deactivating the actor: > Example of deactivating an actor:
```shell ```shell
curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \ curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
-H "Content-Type: application/json" -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 #### HTTP Request
`PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>` `PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -491,27 +491,27 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
appPort | the application port appPort | The application port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
reminderName | the name of the reminder reminderName | The name of the reminder to invoke.
> Example of invoking the actor reminder: > Example of invoking a reminder for an actor:
```shell ```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \ curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
-H "Content-Type: application/json" -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 #### HTTP Request
`PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>` `PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>`
#### HTTP Response codes #### HTTP Response Codes
Code | Description Code | Description
---- | ----------- ---- | -----------
@ -523,28 +523,28 @@ Code | Description
Parameter | Description Parameter | Description
--------- | ----------- --------- | -----------
appPort | the application port appPort | The application port.
actorType | the actor type actorType | The actor type.
actorId | the actor id actorId | The actor ID.
timerName | the name of the timer timerName | The name of the timer to invoke.
> Example of invoking the actor timer: > Example of invoking a timer for an actor:
```shell ```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \ curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
-H "Content-Type: application/json" -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. 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. 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: 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. * Dapr ID - Represents the unique ID given to the Dapr application.
* Actor Type - represents the type of the actor * Actor Type - Represents the type of the actor.
* Actor ID - represents the unique ID of the actor instance for an actor type * 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. * 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: The following example shows how to construct a key for the state of an actor instance under the `myapp` Dapr ID namespace: