mirror of https://github.com/dapr/docs.git
Updating the state API spec documentation for new multi state stores APIs (#295)
* Updating the state API spec documentation to add the details of multi state stores scenario. * Resolving code review comments. * Updating the api spec for multiple state store. Co-authored-by: Young Bu Park <youngp@microsoft.com> Co-authored-by: Aman Bhardwaj <amanbha@users.noreply.github.com>
This commit is contained in:
parent
cd7049f9cb
commit
f6c4a919f8
|
@ -25,6 +25,11 @@ The ```metadata.name``` is the name of the state store.
|
|||
|
||||
the ```spec/metadata``` section is an open key value pair metadata that allows a binding to define connection properties.
|
||||
|
||||
Starting with 0.4.0 release, support for multiple state stores was added. This is a breaking change from previous releases as the state APIs were changed to support this new scenario.
|
||||
|
||||
Please refer https://github.com/dapr/dapr/blob/master/docs/decision_records/api/API-008-multi-state-store-api-design.md for more details.
|
||||
|
||||
|
||||
## Key scheme
|
||||
Dapr state stores are key/value stores. To ensure data compatibility, Dapr requires these data stores follow a fixed key scheme. For general states, the key format is:
|
||||
```bash
|
||||
|
@ -42,13 +47,14 @@ This endpoint lets you save an array of state objects.
|
|||
|
||||
### HTTP Request
|
||||
|
||||
`POST http://localhost:<daprPort>/v1.0/state`
|
||||
`POST http://localhost:<daprPort>/v1.0/state/<storename>`
|
||||
|
||||
#### URL Parameters
|
||||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
storename | ```metadata.name``` field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
|
||||
|
||||
#### Request Body
|
||||
A JSON array of state objects. Each state object is comprised with the following fields:
|
||||
|
@ -77,7 +83,7 @@ None.
|
|||
|
||||
### Example
|
||||
```shell
|
||||
curl -X POST http://localhost:3500/v1.0/state \
|
||||
curl -X POST http://localhost:3500/v1.0/state/starwars \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[
|
||||
{
|
||||
|
@ -99,13 +105,14 @@ This endpoint lets you get the state for a specific key.
|
|||
|
||||
### HTTP Request
|
||||
|
||||
`GET http://localhost:<daprPor>/v1.0/state/<key>`
|
||||
`GET http://localhost:<daprPor>/v1.0/state/<storename>/<key>`
|
||||
|
||||
#### URL Parameters
|
||||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
storename | ```metadata.name``` field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
|
||||
key | the key of the desired state
|
||||
consistency | (optional) read consistency mode, see [state operation options](#optional-behaviors)
|
||||
|
||||
|
@ -132,7 +139,7 @@ JSON-encoded value
|
|||
### Example
|
||||
|
||||
```shell
|
||||
curl http://localhost:3500/v1.0/state/planet \
|
||||
curl http://localhost:3500/v1.0/state/starwars/planet \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
|
@ -149,13 +156,14 @@ This endpoint lets you delete the state for a specific key.
|
|||
|
||||
### HTTP Request
|
||||
|
||||
`DELETE http://localhost:<daprPort>/v1.0/state/<key>`
|
||||
`DELETE http://localhost:<daprPort>/v1.0/state/<storename>/<key>`
|
||||
|
||||
#### URL Parameters
|
||||
|
||||
Parameter | Description
|
||||
--------- | -----------
|
||||
daprPort | the Dapr port
|
||||
storename | ```metadata.name``` field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
|
||||
key | the key of the desired state
|
||||
concurrency | (optional) either *first-write* or *last-write*, see [state operation options](#optional-behaviors)
|
||||
consistency | (optional) either *strong* or *eventual*, see [state operation options](#optional-behaviors)
|
||||
|
@ -185,7 +193,28 @@ None.
|
|||
### Example
|
||||
|
||||
```shell
|
||||
curl -X "DELETE" http://localhost:3500/v1.0/state/planet -H "ETag: xxxxxxx"
|
||||
curl -X "DELETE" http://localhost:3500/v1.0/state/starwars/planet -H "ETag: xxxxxxx"
|
||||
```
|
||||
|
||||
## Configuring State Store for Actors
|
||||
Actors don't support multiple state stores and require a transactional state store to be used with Dapr. Currently mongodb and redis implement the transactional state store interface.
|
||||
To specify which state store to be used for actors, specify value of property `actorStateStore` as true in the metadata section of the state store component yaml file.
|
||||
Example: Following components yaml will configure redis to be used as the state store for Actors.
|
||||
```
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: statestore
|
||||
spec:
|
||||
type: state.redis
|
||||
metadata:
|
||||
- name: redisHost
|
||||
value: <redis host>
|
||||
- name: redisPassword
|
||||
value: ""
|
||||
- name: actorStateStore
|
||||
value: "true"
|
||||
|
||||
```
|
||||
|
||||
## Optional behaviors
|
||||
|
@ -233,7 +262,7 @@ retryThreshold | Maximum number of retries.
|
|||
The following is a sample *set* request with a complete operation option definition:
|
||||
|
||||
```shell
|
||||
curl -X POST http://localhost:3500/v1.0/state \
|
||||
curl -X POST http://localhost:3500/v1.0/state/starwars \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[
|
||||
{
|
||||
|
|
Loading…
Reference in New Issue