Updated state docs

This commit is contained in:
Aaron Crawfis 2020-10-15 09:48:16 -07:00
parent 4dc5ffac2a
commit 02efbf71b9
4 changed files with 142 additions and 68 deletions

View File

@ -12,59 +12,140 @@ Dealing with different databases libraries, testing them, handling retries and f
Dapr provides state management capabilities that include consistency and concurrency options.
In this guide we'll start of with the basics: Using the key/value state API to allow an application to save, get and delete state.
## 1. Setup a state store
## Step 1: Setup a state store
A state store component represents a resource that Dapr uses to communicate with a database.
For the purpose of this how to, we'll use a Redis state store.
For the purpose of this how to we'll use a Redis state store, but any state store from the [supported list]({{< ref supported-state-stores.md >}}) will work.
See a list of supported state stores [here](../setup-state-store/supported-state-stores.md)
### Using the Dapr CLI
{{< tabs "Self-Hosted (CLI)" Kubernetes>}}
{{% codetab %}}
When using `Dapr init` in Standalone mode, the Dapr CLI automatically provisions a state store (Redis) and creates the relevant YAML when running your app with `dapr run`.
To change the state store being used, replace the YAML under `/components` with the file of your choice.
{{% /codetab %}}
### Kubernetes
{{% codetab %}}
See the instructions [here]({{< ref "setup-state-store" >}}) on how to setup different state stores on Kubernetes.
{{% /codetab %}}
See the instructions [here](../setup-state-store) on how to setup different state stores on Kubernetes.
{{< /tabs >}}
## 2. Save state
## Step 2: Save state
The following example shows how to save two key/value pairs in a single call using the state management API, both of which are saved with the single `key1`name over http.
The following example shows how to save two key/value pairs in a single call using the state management API.
*The following example is written in Python, but is applicable to any programming language*
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}}
```python
import requests
import json
stateReq = '[{ "key": "k1", "value": "Some Data"}, { "key": "k2", "value": "Some More Data"}]'
response = requests.post("http://localhost:3500/v1.0/state/key1", json=stateReq)
{{% codetab %}}
Begin by ensuring a Dapr sidecar is running:
```bash
dapr --app-id myapp --port 3500 run
```
## 3. Get state
Then in a separate terminal run:
```bash
curl -X POST -H "Content-Type: application/json" -d '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' http://localhost:3500/v1.0/state/statestore
```
{{% /codetab %}}
The following example shows how to get an item by using a key with the state management API over http:
*The following example is written in Python, but is applicable to any programming language*
```python
import requests
import json
response = requests.get("http://localhost:3500/v1.0/state/key1")
print(response.text)
{{% codetab %}}
Begin by ensuring a Dapr sidecar is running:
```bash
dapr --app-id myapp --port 3500 run
```
## 4. Delete state
The following example shows how to delete an item by using a key with the state management API over http:
*The following example is written in Python, but is applicable to any programming language*
```python
import requests
import json
response = requests.delete("http://localhost:3500/v1.0/state/key1")
Then in a separate terminal run:
```powershell
Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": "key1", "value": "value1"}, { "key": "key2", "value": "value2"}]' -Uri 'http://localhost:3500/v1.0/state/statestore'
```
{{% /codetab %}}
{{% codetab %}}
Make sure to install the Dapr Python SDK with `pip3 install dapr`. Then create a file named `state.py` with:
```python
from dapr.clients import DaprClient
from dapr.clients.grpc._state import StateItem
with DaprClient() as d:
d.save_states(store_name="statestore",
states=[
StateItem(key="key1", value="value1"),
StateItem(key="key2", value="value2")
])
```
Run with `dapr run --app-id myapp run python state.py`
{{% /codetab %}}
{{< /tabs >}}
## Step 3: Get state
The following example shows how to get an item by using a key with the state management API:
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}}
{{% codetab %}}
With the same dapr instance running from above run:
```bash
curl http://localhost:3500/v1.0/state/statestore/key1
```
{{% /codetab %}}
{{% codetab %}}
With the same dapr instance running from above run:
```powershell
Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/key1'
```
{{% /codetab %}}
{{% codetab %}}
Add the following code to `state.py` from above and run again:
```python
data = d.get_state(store_name="statestore",
key="key1",
state_metadata={"metakey": "metavalue"}).data
print(f"Got value: {data}")
```
{{% /codetab %}}
{{< /tabs >}}
## Step 4: Delete state
The following example shows how to delete an item by using a key with the state management API:
{{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)" "Python SDK">}}
{{% codetab %}}
With the same dapr instance running from above run:
```bash
curl -X DELETE 'http://localhost:3500/v1.0/state/statestore/key1'
```
Try getting state again and note that no value is returned.
{{% /codetab %}}
{{% codetab %}}
With the same dapr instance running from above run:
```powershell
Invoke-RestMethod -Method Delete -Uri 'http://localhost:3500/v1.0/state/statestore/key1'
```
Try getting state again and note that no value is returned.
{{% /codetab %}}
{{% codetab %}}
Add the following code to `state.py` from above and run again:
```python
d.delete_state(store_name="statestore"",
key="key1",
state_metadata={"metakey": "metavalue"})
data = d.get_state(store_name="statestore",
key="key1",
state_metadata={"metakey": "metavalue"}).data
print(f"Got value after delete: {data}")
```
{{% /codetab %}}
{{< /tabs >}}

View File

@ -8,7 +8,7 @@ description: "Overview of the state management building block"
## Introduction
Dapr offers key/value storage APIs for state management. If a microservice uses state management, it can use these APIs to leverage any of the [supported state stores](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK.
Dapr offers key/value storage APIs for state management. If a microservice uses state management, it can use these APIs to leverage any of the [supported state stores]({{< ref supported-state-stores.md >}}), without adding or learning a third party SDK.
When using state management your application can leverage several features that would otherwise be complicated and error-prone to build yourself such as:
@ -18,7 +18,7 @@ When using state management your application can leverage several features that
See below for a diagram of state management's high level architecture.
<img src="/images/state_management.png" width=900>
<img src="/images/state-management-overview.png" width=900>
## Features
@ -112,13 +112,6 @@ SELECT AVG(value) FROM StateTable WHERE Id LIKE '<app-id>||<thermometer>||*||tem
## Next steps
* Follow these guides on
* [How-to: Set up Azure Cosmos DB store]({{< ref setup-azure-cosmosdb.md >}})
* [How-to: query Azure Cosmos DB store]({{< ref query-cosmosdb-store.md >}})
* [How-to: Set up PostgreSQL store]({{< ref setup-postgresql.md >}})
* [How-to: Set up Redis store]({{< ref configure-redis.md >}})
* [How-to: Query Redis store]({{< ref query-redis-store.md >}})
* [How-to: Set up SQL Server store]({{< ref setup-sqlserver.md >}})
* [How-to: Query SQL Server store]({{< ref query-sqlserver-store.md >}})
* Follow the [state store setup guides]({{< ref setup-state-store >}})
* Read the [state management API specification]({{< ref state_api.md >}})
* Read the [actors API specification]({{< ref actors_api.md >}})

View File

@ -7,25 +7,25 @@ weight: 20000
type: docs
---
# Supported state stores
The following stores are supported, at various levels, by the Dapr state management building block:
| Name | CRUD | Transactional
| ------------- | -------|------ |
| Aerospike | ✅ | ❌ |
| Cassandra | ✅ | ❌ |
| Cloudstate | ✅ | ❌ |
| Couchbase | ✅ | ❌ |
| etcd | ✅ | ❌ |
| Hashicorp Consul | ✅ | ❌ |
| Hazelcast | ✅ | ❌ |
| Memcached | ✅ | ❌ |
| MongoDB | ✅ | ✅ |
| PostgreSQL | ✅ | ✅ |
| Redis | ✅ | ✅ |
| Zookeeper | ✅ | ❌ |
| Azure CosmosDB | ✅ | ✅ |
| Azure SQL Server | ✅ | ✅ |
| Azure Table Storage | ✅ | ❌ |
| Azure Blob Storage | ✅ | ❌ |
| Google Cloud Firestore | ✅ | ❌ |
| Name | CRUD | Transactional |
|------------------------|------|---------------|
| Aerospike | ✅ | ❌ |
| Cassandra | ✅ | ❌ |
| Cloudstate | ✅ | ❌ |
| Couchbase | ✅ | ❌ |
| etcd | ✅ | ❌ |
| Hashicorp Consul | ✅ | ❌ |
| Hazelcast | ✅ | ❌ |
| Memcached | ✅ | ❌ |
| MongoDB | ✅ | ✅ |
| PostgreSQL | ✅ | ✅ |
| Redis | ✅ | ✅ |
| Zookeeper | ✅ | ❌ |
| Azure CosmosDB | ✅ | ✅ |
| Azure SQL Server | ✅ | ✅ |
| Azure Table Storage | ✅ | ❌ |
| Azure Blob Storage | ✅ | ❌ |
| Google Cloud Firestore | ✅ | ❌ |

Binary file not shown.

After

Width:  |  Height:  |  Size: 88 KiB