diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md index f6d6abc34..433979ff2 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/howto-get-save-state.md @@ -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 >}} diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md index 3022892d5..6c74a3e3a 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md @@ -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. - + ## Features @@ -112,13 +112,6 @@ SELECT AVG(value) FROM StateTable WHERE Id LIKE '||||*||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 >}}) diff --git a/daprdocs/content/en/operations/components/setup-state-store/supported-state-stores.md b/daprdocs/content/en/operations/components/setup-state-store/supported-state-stores.md index 1f6e03d9f..fbf277a04 100644 --- a/daprdocs/content/en/operations/components/setup-state-store/supported-state-stores.md +++ b/daprdocs/content/en/operations/components/setup-state-store/supported-state-stores.md @@ -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 | ✅ | ❌ | diff --git a/daprdocs/static/images/state-management-overview.png b/daprdocs/static/images/state-management-overview.png new file mode 100644 index 000000000..5c8e181cb Binary files /dev/null and b/daprdocs/static/images/state-management-overview.png differ