State management API reference

Detailed documentation on the state management API

Component file

A Dapr State Store component yaml file has the following structure:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: <NAME>
  5. namespace: <NAMESPACE>
  6. spec:
  7. type: state.<TYPE>
  8. version: v1
  9. metadata:
  10. - name:<KEY>
  11. value:<VALUE>
  12. - name: <KEY>
  13. value: <VALUE>

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:

  1. <App ID>||<state key>

For Actor states, the key format is:

  1. <App ID>||<Actor type>||<Actor id>||<state key>

Save state

This endpoint lets you save an array of state objects.

HTTP 请求

  1. POST http://localhost:<daprPort>/v1.0/state/<storename>

URL 参数

参数描述
daprPortdapr 端口。
storenamemetadata.name field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.

注意:所有的 URL 参数都是大小写敏感的。

Request Body

A JSON array of state objects. Each state object is comprised with the following fields:

字段描述
keystate key
state value, which can be any byte array
etag(optional) state ETag
metadata(optional) additional key-value pairs to be passed to the state store
options(optional) state operation options, see state operation options

ETag format Dapr runtime treats ETags as opaque strings. The exact ETag format is defined by the corresponding data store.

HTTP Response

Response Codes

代码描述
204State saved
400State store is missing or misconfigured or malformed request
500Failed to save state

Response Body

None.

示例

  1. curl -X POST http://localhost:3500/v1.0/state/starwars \
  2. -H "Content-Type: application/json" \
  3. -d '[
  4. {
  5. "key": "weapon",
  6. "value": "DeathStar"
  7. },
  8. {
  9. "key": "planet",
  10. "value": {
  11. "name": "Tatooine"
  12. }
  13. }
  14. ]'

Get state

This endpoint lets you get the state for a specific key.

HTTP 请求

  1. GET http://localhost:<daprPort>/v1.0/state/<storename>/<key>

URL 参数

参数描述
daprPortdapr 端口。
storenamemetadata.name field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
keythe key of the desired state
consistency(optional) read consistency mode, see state operation options
metadata(optional) metadata as query parameters to the state store

注意:所有的 URL 参数都是大小写敏感的。

HTTP Response

Response Codes

代码描述
200Get state successful
204Key is not found
400State store is missing or misconfigured
500Get state failed

Response Headers

Header描述
ETagETag of returned value

Response Body

JSON-encoded value

示例

  1. curl http://localhost:3500/v1.0/state/starwars/planet \
  2. -H "Content-Type: application/json"

以上命令将返回状态:

  1. {
  2. "name": "Tatooine"
  3. }

To pass metadata as query parammeter:

  1. GET http://localhost:3500/v1.0/state/starwars/planet?metadata.partitionKey=mypartitionKey

Get bulk state

This endpoint lets you get a list of values for a given list of keys.

HTTP 请求

  1. POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/bulk

URL 参数

参数描述
daprPortdapr 端口。
storenamemetadata.name field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
metadata(optional) metadata as query parameters to the state store

注意:所有的 URL 参数都是大小写敏感的。

HTTP Response

Response Codes

代码描述
200Get state successful
400State store is missing or misconfigured
500Get bulk state failed

Response Body

An array of JSON-encoded values

示例

  1. curl http://localhost:3500/v1.0/state/myRedisStore/bulk \
  2. -H "Content-Type: application/json" \
  3. -d '{
  4. "keys": [ "key1", "key2" ],
  5. "parallelism": 10
  6. }'

The above command returns an array of key/value objects:

  1. [
  2. {
  3. "key": "key1",
  4. "data": "value1",
  5. "etag": "1"
  6. },
  7. {
  8. "key": "key2",
  9. "data": "value2",
  10. "etag": "1"
  11. }
  12. ]

To pass metadata as query parammeter:

  1. POST http://localhost:3500/v1.0/state/myRedisStore/bulk?metadata.partitionKey=mypartitionKey

Delete state

This endpoint lets you delete the state for a specific key.

HTTP 请求

  1. DELETE http://localhost:<daprPort>/v1.0/state/<storename>/<key>

URL 参数

参数描述
daprPortdapr 端口。
storenamemetadata.name field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.
keythe key of the desired state
并发(Concurrency)(optional) either first-write or last-write, see state operation options
consistency(optional) either strong or eventual, see state operation options

注意:所有的 URL 参数都是大小写敏感的。

Request Headers

Header描述
If-Match(Optional) ETag associated with the key to be deleted

HTTP Response

Response Codes

代码描述
204Delete state successful
400State store is missing or misconfigured
500Delete state failed

Response Body

None.

示例

  1. curl -X "DELETE" http://localhost:3500/v1.0/state/starwars/planet -H "ETag: xxxxxxx"

State transactions

Persists the changes to the state store as a multi-item transaction.

请注意,此操作取决于支持 multi-item transactions 的状态存储组件。

List of state stores that support transactions:

  • Redis
  • MongoDB
  • PostgrSQL
  • SQL Server
  • Azure CosmSDB

HTTP 请求

  1. POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/transaction

HTTP 响应码

代码描述
204请求成功
400State store is missing or misconfigured or malformed request
500请求失败

URL 参数

参数描述
daprPortdapr 端口。
storenamemetadata.name field in the user configured state store component yaml. Please refer Dapr State Store configuration structure mentioned above.

注意:所有的 URL 参数都是大小写敏感的。

Request Body

字段描述
功能操作A JSON array of state operation
metadata(optional) the metadata for transaction that applies to all operations

Each state operation is comprised with the following fields:

字段描述
keystate key
state value, which can be any byte array
etag(optional) state ETag
metadata(optional) additional key-value pairs to be passed to the state store
options(optional) state operation options, see state operation options

示例

  1. curl -X POST http://localhost:3500/v1.0/state/starwars/transaction \
  2. -H "Content-Type: application/json" \
  3. -d '{
  4. "operations": [
  5. {
  6. "operation": "upsert",
  7. "request": {
  8. "key": "key1",
  9. "value": "myData"
  10. }
  11. },
  12. {
  13. "operation": "delete",
  14. "request": {
  15. "key": "key2"
  16. }
  17. }
  18. ],
  19. "metadata": {
  20. "partitionKey": "planet"
  21. }
  22. }'

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, Redis, PostgreSQL, SQL Server, and Azure CosmosDB 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.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: statestore
  5. namespace: default
  6. spec:
  7. type: state.redis
  8. version: v1
  9. metadata:
  10. - name: redisHost
  11. value: <redis host>
  12. - name: redisPassword
  13. value: ""
  14. - name: actorStateStore
  15. value: "true"

Optional behaviors

Key scheme

A Dapr-compatible state store shall use the following key scheme:

  • <App ID>||<state key> key format for general states
  • <App ID>||<Actor type>||<Actor id>||<state key> key format for Actor states.

Concurrency

Dapr uses Optimized Concurrency Control (OCC) with ETags. Dapr makes optional the following requirements on state stores:

  • An Dapr-compatible state store may support optimistic concurrency control using ETags. When an ETag is associated with an save or delete request, the store shall allow the update only if the attached ETag matches with the latest ETag in the database.
  • When ETag is missing in the write requests, the state store shall handle the requests in a last-write-wins fashion. This is to allow optimizations for high-throughput write scenarios in which data contingency is low or has no negative effects.
  • A store shall always return ETags when returning states to callers.

Consistency

Dapr allows clients to attach a consistency hint to get, set and delete operation. Dapr support two consistency level: strong and eventual, which are defined as the follows:

Eventual Consistency

Dapr assumes data stores are eventually consistent by default. A state should:

  • For read requests, the state store can return data from any of the replicas
  • For write request, the state store should asynchronously replicate updates to configured quorum after acknowledging the update request.

Strong Consistency

When a strong consistency hint is attached, a state store should:

  • For read requests, the state store should return the most up-to-date data consistently across replicas.
  • For write/delete requests, the state store should synchronisely replicate updated data to configured quorum before completing the write request.

Example - Complete options request example

The following is an example set request with a complete options definition:

  1. curl -X POST http://localhost:3500/v1.0/state/starwars \
  2. -H "Content-Type: application/json" \
  3. -d '[
  4. {
  5. "key": "weapon",
  6. "value": "DeathStar",
  7. "etag": "xxxxx",
  8. "options": {
  9. "concurrency": "first-write",
  10. "consistency": "strong"
  11. }
  12. }
  13. ]'

Example - Working with ETags

The following is an example which walks through the usage of an ETag when setting/deleting an object in a compatible statestore.

First, store an object in a statestore (this sample uses Redis that has been defined as ‘statestore’):

  1. curl -X POST http://localhost:3500/v1.0/state/statestore \
  2. -H "Content-Type: application/json" \
  3. -d '[
  4. {
  5. "key": "sampleData",
  6. "value": "1"
  7. }
  8. ]'

Get the object to find the ETag that was set automatically by the statestore:

  1. curl http://localhost:3500/v1.0/state/statestore/sampleData -v
  2. * Connected to localhost (127.0.0.1) port 3500 (#0)
  3. > GET /v1.0/state/statestore/sampleData HTTP/1.1
  4. > Host: localhost:3500
  5. > User-Agent: curl/7.64.1
  6. > Accept: */*
  7. >
  8. < HTTP/1.1 200 OK
  9. < Server: fasthttp
  10. < Date: Sun, 14 Feb 2021 04:51:50 GMT
  11. < Content-Type: application/json
  12. < Content-Length: 3
  13. < Etag: 1
  14. < Traceparent: 00-3452582897d134dc9793a244025256b1-b58d8d773e4d661d-01
  15. <
  16. * Connection #0 to host localhost left intact
  17. "1"* Closing connection 0

The returned ETag here was 1. Sending a new request to update or delete the data with the wrong ETag will return an error (omitting the ETag will allow the request):

  1. # Update
  2. curl -X POST http://localhost:3500/v1.0/state/statestore \
  3. -H "Content-Type: application/json" \
  4. -d '[
  5. {
  6. "key": "sampleData",
  7. "value": "2",
  8. "etag": "2"
  9. }
  10. ]'
  11. {"errorCode":"ERR_STATE_SAVE","message":"failed saving state in state store statestore: possible etag mismatch. error from state store: ERR Error running script (call to f_83e03ec05d6a3b6fb48483accf5e594597b6058f): @user_script:1: user_script:1: failed to set key nodeapp||sampleData"}
  12. # Delete
  13. curl -X DELETE -H 'If-Match: 5' http://localhost:3500/v1.0/state/statestore/sampleData
  14. {"errorCode":"ERR_STATE_DELETE","message":"failed deleting state with key sampleData: possible etag mismatch. error from state store: ERR Error running script (call to f_9b5da7354cb61e2ca9faff50f6c43b81c73c0b94): @user_script:1: user_script:1: failed to delete node
  15. app||sampleData"}

In order to update or delete the object, simply match the ETag in either the request body (update) or the If-Match header (delete). Note, when the state is updated, it receives a new ETag so further updates or deletes will need to use the new ETag.

  1. # Update
  2. curl -X POST http://localhost:3500/v1.0/state/statestore \
  3. -H "Content-Type: application/json" \
  4. -d '[
  5. {
  6. "key": "sampleData",
  7. "value": "2",
  8. "etag": "1"
  9. }
  10. ]'
  11. # Delete
  12. curl -X DELETE -H 'If-Match: 1' http://localhost:3500/v1.0/state/statestore/sampleData

Next Steps