Skip to content

Latest commit

 

History

History
533 lines (375 loc) · 11.3 KB

actors.md

File metadata and controls

533 lines (375 loc) · 11.3 KB

Actors

Dapr has a 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

This endpoint lets you invoke a method on a remote Actor.

HTTP Request

POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
method the name of the method to invoke on the remote actor

Example of invoking a method on a remote actor:

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:

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
	-H "Content-Type: application/json"
  -d '{
        "destination": "Hoth"
      }'

The response from the remote endpoint will be returned in the request body.

Save actor state

This endpoint lets you save state for a given actor for a given key.

HTTP Request

POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP Response codes

Code Description
201 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
key key for the state value 
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
	-H "Content-Type: application/json"
  -d '{
        "location": "Alderaan"
      }'

Save actor state - transaction

This endpoint lets you save an actor's state as a multi item transaction.

Note that this operation is dependant on a state store that supports multi item transactions.

HTTP Request

POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state

HTTP Response codes

Code Description
201 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id 
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"
	 }
       }
      ]'

Get actor state

This endpoint lets you get the state of a given actor for a given key.

HTTP Request

GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
key key for the state value 
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
	-H "Content-Type: application/json"

The above command returns the state:

{
  "location": "Alderaan"
}

Delete actor state

This endpoint lets you delete the state of a given actor for a given key.

HTTP Request

DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
key key for the state value 
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
	-X "Content-Type: application/json"

Set actor reminder

This endpoint lets you create a persistent reminder for an actor.

HTTP Request

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

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
name the name of the reminder 
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
	-H "Content-Type: application/json"
-d '{
        "data": "someData",
	"dueTime": "1m",
	"period": "20s"
    }'

Get actor reminder

This endpoint lets get a reminder for an actor

HTTP Request

GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
name the name of the reminder to get 
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",
}

Delete actor reminder

This endpoint lets delete a reminder for an actor

HTTP Request

DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
name the name of the reminder to delete 
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
	-X "Content-Type: application/json"

Set actor timer

This endpoint lets you create a timer for an actor.

HTTP Request

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

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
name the name of the timer 
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"
    }'

Delete actor timer

This endpoint lets delete a timer for an actor

HTTP Request

DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
actorType the actor type
actorId the actor id
name the name of the timer to delete 
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
	-X "Content-Type: application/json"

Specifications for Dapr calling to user service code

Get Registered Actors

This endpoint lets you get the registered actors in Dapr.

HTTP Request

GET http://localhost:<appPort>/v1.0/dapr/config

HTTP Response codes

Code Description
200 Request successful
500 Request failed

URL Parameters

Parameter Description
appPort the application port

Example of getting the registered actors:

curl -X GET http://localhost:5001/v1.0/dapr/config \
	-H "Content-Type: application/json"

Activate the Actors

This endpoint lets you activate the actor.

HTTP Request

POST http://localhost:<appPort>/v1.0/actors/<actorType>/<actorId>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
appPort the application port
actorType the actor type
actorId the actor id

Example of activating the actor:

curl -X POST http://localhost:5001/v1.0/actors/stormtrooper/50 \
	-H "Content-Type: application/json"

Deactivate the Actors

This endpoint lets you deactivate the actor.

HTTP Request

DELETE http://localhost:<appPort>/v1.0/actors/<actorType>/<actorId>

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
appPort the application port
actorType the actor type
actorId the actor id

Example of deactivating the actor:

curl -X DELETE http://localhost:5001/v1.0/actors/stormtrooper/50 \
	-H "Content-Type: application/json"

Invoke the Reminders

This endpoint lets you invokes the actor reminders.

HTTP Request

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

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
appPort the application port
actorType the actor type
actorId the actor id
reminderName the name of the reminder

Example of invoking the actor reminder:

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

Invoke the Timers

This endpoint lets you invokes the actor timers.

HTTP Request

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

HTTP Response codes

Code Description
200 Request successful
500 Request failed
404 Actor not found

URL Parameters

Parameter Description
appPort the application port
actorType the actor type
actorId the actor id
timerName the name of the timer

Example of invoking the actor timer:

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

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
  • 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: 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 Dapr ID namespace of myapp.