From e113f06cbcc97ddbbae3f5a1e40362c7c93a7696 Mon Sep 17 00:00:00 2001 From: Greg Ingram Date: Mon, 25 Nov 2019 12:41:35 -0500 Subject: [PATCH] Clean up actors doc (#259) --- reference/api/actors.md | 220 ++++++++++++++++++++-------------------- 1 file changed, 110 insertions(+), 110 deletions(-) diff --git a/reference/api/actors.md b/reference/api/actors.md index bdf06d6f8..9f29c22e1 100644 --- a/reference/api/actors.md +++ b/reference/api/actors.md @@ -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:/v1.0/actors///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:/v1.0/actors///state/` -#### 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:/v1.0/actors///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:/v1.0/actors///state/` -#### 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:/v1.0/actors///state/` -#### 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:/v1.0/actors///reminders/` -#### 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:/v1.0/actors///reminders/` -#### 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:/v1.0/actors///reminders/` -#### 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:/v1.0/actors///timers/` -#### 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:/v1.0/actors///timers/` -#### 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:/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:/actors//` -#### 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:/actors//` -#### 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:/actors///method/remind/` -#### 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:/actors///method/timer/` -#### 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: