mirror of https://github.com/dapr/docs.git
Merge branch 'v1.4' into issue/1752
This commit is contained in:
Ori Zohar
GitHub
commit
97238009aa
|
|
@ -35,7 +35,7 @@ Every actor is defined as an instance of an actor type, identical to the way an
|
|||
|
||||
## Actor lifetime
|
||||
|
||||
Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actors runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr Actors runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later.
|
||||
Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actor runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr actor runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later.
|
||||
|
||||
Invocation of actor methods and reminders reset the idle time, e.g. reminder firing will keep the actor active. Actor reminders fire whether an actor is active or inactive, if fired for inactive actor, it will activate the actor first. Actor timers do not reset the idle time, so timer firing will not keep the actor active. Timers only fire while the actor is active.
|
||||
|
||||
|
|
@ -77,11 +77,13 @@ POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/<met
|
|||
|
||||
You can provide any data for the actor method in the request body, and the response for the request would be in the response body which is the data from actor call.
|
||||
|
||||
Another, and perhaps more convenient, way of interacting with actors is via SDKs. Dapr currently supports actors SDKs in [.NET]({{< ref "dotnet-actors" >}}), [Java]({{< ref "java#actors" >}}), and [Python]({{< ref "python-actor" >}}).
|
||||
|
||||
Refer to [Dapr Actor Features]({{< ref howto-actors.md >}}) for more details.
|
||||
|
||||
### Concurrency
|
||||
|
||||
The Dapr Actors runtime provides a simple turn-based access model for accessing actor methods. This means that no more than one thread can be active inside an actor object's code at any time. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access. It also means systems must be designed with special considerations for the single-threaded access nature of each actor instance.
|
||||
The Dapr actor runtime provides a simple turn-based access model for accessing actor methods. This means that no more than one thread can be active inside an actor object's code at any time. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access. It also means systems must be designed with special considerations for the single-threaded access nature of each actor instance.
|
||||
|
||||
A single actor instance cannot process more than one request at a time. An actor instance can cause a throughput bottleneck if it is expected to handle concurrent requests.
|
||||
|
||||
|
|
@ -94,9 +96,9 @@ As an enhancement to the base actors in dapr, reentrancy can now be enabled as a
|
|||
|
||||
### Turn-based access
|
||||
|
||||
A turn consists of the complete execution of an actor method in response to a request from other actors or clients, or the complete execution of a timer/reminder callback. Even though these methods and callbacks are asynchronous, the Dapr Actors runtime does not interleave them. A turn must be fully finished before a new turn is allowed. In other words, an actor method or timer/reminder callback that is currently executing must be fully finished before a new call to a method or callback is allowed. A method or callback is considered to have finished if the execution has returned from the method or callback and the task returned by the method or callback has finished. It is worth emphasizing that turn-based concurrency is respected even across different methods, timers, and callbacks.
|
||||
A turn consists of the complete execution of an actor method in response to a request from other actors or clients, or the complete execution of a timer/reminder callback. Even though these methods and callbacks are asynchronous, the Dapr actor runtime does not interleave them. A turn must be fully finished before a new turn is allowed. In other words, an actor method or timer/reminder callback that is currently executing must be fully finished before a new call to a method or callback is allowed. A method or callback is considered to have finished if the execution has returned from the method or callback and the task returned by the method or callback has finished. It is worth emphasizing that turn-based concurrency is respected even across different methods, timers, and callbacks.
|
||||
|
||||
The Dapr actors runtime enforces turn-based concurrency by acquiring a per-actor lock at the beginning of a turn and releasing the lock at the end of the turn. Thus, turn-based concurrency is enforced on a per-actor basis and not across actors. Actor methods and timer/reminder callbacks can execute simultaneously on behalf of different actors.
|
||||
The Dapr actor runtime enforces turn-based concurrency by acquiring a per-actor lock at the beginning of a turn and releasing the lock at the end of the turn. Thus, turn-based concurrency is enforced on a per-actor basis and not across actors. Actor methods and timer/reminder callbacks can execute simultaneously on behalf of different actors.
|
||||
|
||||
The following example illustrates the above concepts. Consider an actor type that implements two asynchronous methods (say, Method1 and Method2), a timer, and a reminder. The diagram below shows an example of a timeline for the execution of these methods and callbacks on behalf of two actors (ActorId1 and ActorId2) that belong to this actor type.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,11 +6,11 @@ weight: 20
|
|||
description: Learn more about the actor pattern
|
||||
---
|
||||
|
||||
The Dapr actors runtime provides support for [virtual actors]({{< ref actors-overview.md >}}) through following capabilities:
|
||||
The Dapr actor runtime provides support for [virtual actors]({{< ref actors-overview.md >}}) through following capabilities:
|
||||
|
||||
## Actor method invocation
|
||||
|
||||
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint
|
||||
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint.
|
||||
|
||||
```html
|
||||
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>
|
||||
|
|
@ -20,6 +20,8 @@ You can provide any data for the actor method in the request body and the respon
|
|||
|
||||
Refer [api spec]({{< ref "actors_api.md#invoke-actor-method" >}}) for more details.
|
||||
|
||||
Alternatively, you can use the Dapr SDK in [.NET]({{< ref "dotnet-actors" >}}), [Java]({{< ref "java#actors" >}}), or [Python]({{< ref "python-actor" >}}).
|
||||
|
||||
## Actor state management
|
||||
|
||||
Actors can save state reliably using state management capability.
|
||||
|
|
@ -31,25 +33,60 @@ To use actors, your state store must support multi-item transactions. This mean
|
|||
|
||||
Actors can schedule periodic work on themselves by registering either timers or reminders.
|
||||
|
||||
The functionality of timers and reminders is very similar. The main difference is that Dapr actor runtime is not retaining any information about timers after deactivation, while persisting the information about reminders using Dapr actor state provider.
|
||||
|
||||
This distintcion allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.
|
||||
|
||||
The scheduling configuration of timers and reminders is identical, as summarized below:
|
||||
|
||||
---
|
||||
`dueTime` is an optional parameter that sets time at which or time interval before the callback is invoked for the first time. If `dueTime` is omitted, the callback is invoked immediately after timer/reminder registration.
|
||||
|
||||
Supported formats:
|
||||
- RFC3339 date format, e.g. `2020-10-02T15:00:00Z`
|
||||
- time.Duration format, e.g. `2h30m`
|
||||
- [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`
|
||||
|
||||
---
|
||||
`period` is an optional parameter that sets time interval between two consecutive callback invocations. When specified in `ISO 8601-1 duration` format, you can also configure the number of repetition in order to limit the total number of callback invocations.
|
||||
If `period` is omitted, the callback will be invoked only once.
|
||||
|
||||
Supported formats:
|
||||
- time.Duration format, e.g. `2h30m`
|
||||
- [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`, `R5/PT1M30S`
|
||||
|
||||
---
|
||||
`ttl` is an optional parameter that sets time at which or time interval after which the timer/reminder will be expired and deleted. If `ttl` is omitted, no restrictions are applied.
|
||||
|
||||
Supported formats:
|
||||
* RFC3339 date format, e.g. `2020-10-02T15:00:00Z`
|
||||
* time.Duration format, e.g. `2h30m`
|
||||
* [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format. Example: `PT2H30M`
|
||||
|
||||
---
|
||||
The actor runtime validates correctess of the scheduling configuration and returns error on invalid input.
|
||||
|
||||
When you specify both the number of repetitions in `period` as well as `ttl`, the timer/reminder will be stopped when either condition is met.
|
||||
|
||||
### Actor timers
|
||||
|
||||
You can register a callback on actor to be executed based on a timer.
|
||||
|
||||
The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees.This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
|
||||
The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees. This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
|
||||
|
||||
The next period of the timer starts after the callback completes execution. This implies that the timer is stopped while the callback is executing and is started when the callback finishes.
|
||||
The Dapr actor runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated.
|
||||
|
||||
The Dapr actors runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated.
|
||||
All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actor runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
|
||||
|
||||
All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actors runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
|
||||
|
||||
You can create a timer for an actor by calling the HTTP/gRPC request to Dapr.
|
||||
You can create a timer for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
|
||||
|
||||
```md
|
||||
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
|
||||
```
|
||||
|
||||
The timer `duetime` and callback are specified in the request body. The due time represents when the timer will first fire after registration. The `period` represents how often the timer fires after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid.
|
||||
**Examples**
|
||||
|
||||
The timer parameters are specified in the request body.
|
||||
|
||||
The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
|
||||
```json
|
||||
|
|
@ -59,11 +96,27 @@ The following request body configures a timer with a `dueTime` of 9 seconds and
|
|||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it fires immediately after registration, then every 3 seconds after that.
|
||||
The following request body configures a timer with a `period` of 3 seconds (in ISO 8601 duration format). It also limits the number of invocations to 10. This means it will fire 10 times: first, immediately after registration, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m0s0ms",
|
||||
"period":"0h0m3s0ms"
|
||||
"period":"R10/PT3S",
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `period` of 3 seconds (in ISO 8601 duration format) and a `ttl` of 20 seconds. This means it fires immediately after registration, then every 3 seconds after that for the duration of 20 seconds.
|
||||
```json
|
||||
{
|
||||
"period":"PT3S",
|
||||
"ttl":"20s"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `dueTime` of 10 seconds, a `period` of 3 seconds, and a `ttl` of 10 seconds. It also limits the number of invocations to 4. This means it will first fire after 10 seconds, then every 3 seconds after that for the duration of 10 seconds, but no more than 4 times in total.
|
||||
```json
|
||||
{
|
||||
"dueTime":"10s",
|
||||
"period":"R4/PT3S",
|
||||
"ttl":"10s"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -77,69 +130,15 @@ Refer [api spec]({{< ref "actors_api.md#invoke-timer" >}}) for more details.
|
|||
|
||||
### Actor reminders
|
||||
|
||||
Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted or the number in invocations is exhausted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actors runtime persists the information about the actors' reminders using Dapr actor state provider.
|
||||
Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted or the number in invocations is exhausted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actor runtime persists the information about the actors' reminders using Dapr actor state provider.
|
||||
|
||||
You can create a persistent reminder for an actor by calling the Http/gRPC request to Dapr.
|
||||
You can create a persistent reminder for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
|
||||
|
||||
```md
|
||||
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
The reminder `duetime` and callback can be specified in the request body. The due time represents when the reminder first fires after registration. The `period` represents how often the reminder will fire after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid. To register a reminder that fires only once, set the period to an empty string.
|
||||
|
||||
The following request body configures a reminder with a `dueTime` 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m9s0ms",
|
||||
"period":"0h0m3s0ms"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a reminder with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it will fire immediately after registration, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m0s0ms",
|
||||
"period":"0h0m3s0ms"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a reminder with a `dueTime` 15 seconds and a `period` of empty string. This means it will first fire after 15 seconds, then never fire again.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m15s0ms",
|
||||
"period":""
|
||||
}
|
||||
```
|
||||
|
||||
[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) can also be used to specify `period`. The following request body configures a reminder with a `dueTime` 0 seconds an `period` of 15 seconds.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m0s0ms",
|
||||
"period":"P0Y0M0W0DT0H0M15S"
|
||||
}
|
||||
```
|
||||
The designators for zero are optional and the above `period` can be simplified to `PT15S`.
|
||||
ISO 8601 specifies multiple recurrence formats but only the duration format is currently supported.
|
||||
|
||||
#### Reminders with repetitions
|
||||
|
||||
When configured with ISO 8601 durations, the `period` column also allows to specify number of times a reminder can run. The following request body will create a reminder that will execute for 5 number of times with a period of 15 seconds.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m0s0ms",
|
||||
"period":"R5/PT15S"
|
||||
}
|
||||
```
|
||||
|
||||
The number of repetitions i.e. the number of times the reminder is run should be a positive number.
|
||||
|
||||
**Example**
|
||||
|
||||
Watch this [video](https://www.youtube.com/watch?v=B_vkXqptpXY&t=1002s) for more information on using ISO 861 for Reminders
|
||||
|
||||
<div class="embed-responsive embed-responsive-16by9">
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/B_vkXqptpXY?start=1003" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
</div>
|
||||
The request structure for reminders is identical to those of actors. Please refer to the [actor timers examples]({{< ref "#actor-timers" >}}).
|
||||
|
||||
#### Retrieve actor reminder
|
||||
|
||||
|
|
@ -161,7 +160,7 @@ Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details.
|
|||
|
||||
## Actor runtime configuration
|
||||
|
||||
You can configure the Dapr Actors runtime configuration to modify the default runtime behavior.
|
||||
You can configure the Dapr actor runtime configuration to modify the default runtime behavior.
|
||||
|
||||
### Configuration parameters
|
||||
- `actorIdleTimeout` - The timeout before deactivating an idle actor. Checks for timeouts occur every `actorScanInterval` interval. **Default: 60 minutes**
|
||||
|
|
|
|||
|
|
@ -33,6 +33,10 @@ spec:
|
|||
value: *****************
|
||||
- name: sessionToken
|
||||
value: mysession
|
||||
- name: decodeBase64
|
||||
value: <bool>
|
||||
- name: encodeBase64
|
||||
value: <bool>
|
||||
```
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
|
|
@ -48,13 +52,18 @@ The above example uses secrets as plain strings. It is recommended to use a secr
|
|||
| accessKey | Y | Output | The AWS Access Key to access this resource | `"key"` |
|
||||
| secretKey | Y | Output | The AWS Secret Access Key to access this resource | `"secretAccessKey"` |
|
||||
| sessionToken | N | Output | The AWS session token to use | `"sessionToken"` |
|
||||
| decodeBase64 | N | Output | Configuration to decode base64 file content before saving to bucket storage. (In case of saving a file with binary content). `true` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `false` | `true`, `false` |
|
||||
| encodeBase64 | N | Output | Configuration to encode base64 file content before return the content. (In case of opening a file with binary content). `true` is the only allowed positive value. Other positive variations like `"True", "1"` are not acceptable. Defaults to `false` | `true`, `false` |
|
||||
|
||||
|
||||
## Binding support
|
||||
|
||||
This component supports **output binding** with the following operations:
|
||||
|
||||
- `create`
|
||||
- `create` : [Create file](#create-file)
|
||||
- `get` : [Get file](#get-file)
|
||||
- `delete` : [Delete file](#delete-file)
|
||||
- `list`: [List file](#list-files)
|
||||
|
||||
### Create file
|
||||
|
||||
|
|
@ -70,8 +79,6 @@ To perform a create operation, invoke the AWS S3 binding with a `POST` method an
|
|||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
|
||||
##### Save text to a random generated UUID file
|
||||
|
||||
{{< tabs Windows Linux >}}
|
||||
|
|
@ -111,10 +118,33 @@ To perform a create operation, invoke the AWS S3 binding with a `POST` method an
|
|||
|
||||
{{< /tabs >}}
|
||||
|
||||
##### Save a file to a object
|
||||
|
||||
##### Upload a file
|
||||
To upload a file, encode it as Base64 and let the Binding know to deserialize it:
|
||||
|
||||
To upload a file, pass the file contents as the data payload; you may want to encode this in e.g. Base64 for binary content.
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: <NAME>
|
||||
namespace: <NAMESPACE>
|
||||
spec:
|
||||
type: bindings.aws.s3
|
||||
version: v1
|
||||
metadata:
|
||||
- name: bucket
|
||||
value: mybucket
|
||||
- name: region
|
||||
value: us-west-2
|
||||
- name: accessKey
|
||||
value: *****************
|
||||
- name: secretKey
|
||||
value: *****************
|
||||
- name: sessionToken
|
||||
value: mysession
|
||||
- name: decodeBase64
|
||||
value: <bool>
|
||||
```
|
||||
|
||||
Then you can upload it as you would normally:
|
||||
|
||||
|
|
@ -122,19 +152,172 @@ Then you can upload it as you would normally:
|
|||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d "{ \"operation\": \"create\", \"data\": \"(YOUR_FILE_CONTENTS)\", \"metadata\": { \"key\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
curl -d "{ \"operation\": \"create\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"key\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ "operation": "create", "data": "$(cat my-test-file.jpg)", "metadata": { "key": "my-test-file.jpg" } }' \
|
||||
curl -d '{ "operation": "create", "data": "YOUR_BASE_64_CONTENT", "metadata": { "key": "my-test-file.jpg" } }' \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
#### Response
|
||||
|
||||
The response body will contain the following JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"location":"https://<your bucket>.s3.<your region>.amazonaws.com/<key>",
|
||||
"versionID":"<version ID if Bucket Versioning is enabled"
|
||||
}
|
||||
```
|
||||
|
||||
### Get object
|
||||
|
||||
To perform a get file operation, invoke the AWS S3 binding with a `POST` method and the following JSON body:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "get",
|
||||
"metadata": {
|
||||
"key": "my-test-file.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The metadata parameters are:
|
||||
|
||||
- `key` - the name of the object
|
||||
|
||||
#### Example
|
||||
|
||||
{{< tabs Windows Linux >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ \"operation\": \"get\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ "operation": "get", "metadata": { "key": "my-test-file.txt" }}' \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
#### Response
|
||||
|
||||
The response body contains the value stored in the object.
|
||||
|
||||
|
||||
### Delete object
|
||||
|
||||
To perform a delete object operation, invoke the AWS S3 binding with a `POST` method and the following JSON body:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "delete",
|
||||
"metadata": {
|
||||
"key": "my-test-file.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The metadata parameters are:
|
||||
|
||||
- `key` - the name of the object
|
||||
|
||||
|
||||
#### Examples
|
||||
|
||||
##### Delete object
|
||||
|
||||
{{< tabs Windows Linux >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ \"operation\": \"delete\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ "operation": "delete", "metadata": { "key": "my-test-file.txt" }}' \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
#### Response
|
||||
|
||||
An HTTP 204 (No Content) and empty body will be retuned if successful.
|
||||
|
||||
|
||||
### List objects
|
||||
|
||||
To perform a list object operation, invoke the S3 binding with a `POST` method and the following JSON body:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "list",
|
||||
"data": {
|
||||
"maxResults": 10,
|
||||
"prefix": "file",
|
||||
"marker": "hvlcCQFSOD5TD",
|
||||
"delimiter": "i0FvxAn2EOEL6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The data parameters are:
|
||||
|
||||
- `maxResults` - (optional) sets the maximum number of keys returned in the response. By default the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
|
||||
- `prefix` - (optional) limits the response to keys that begin with the specified prefix.
|
||||
- `marker` - (optional) marker is where you want Amazon S3 to start listing from. Amazon S3 starts listing after this specified key. Marker can be any key in the bucket.
|
||||
The marker value may then be used in a subsequent call to request the next set of list items.
|
||||
- `delimiter` - (optional) A delimiter is a character you use to group keys.
|
||||
|
||||
|
||||
#### Response
|
||||
|
||||
The response body contains the list of found objects.
|
||||
|
||||
The list of objects will be returned as JSON array in the following form:
|
||||
|
||||
```json
|
||||
{
|
||||
"CommonPrefixes": null,
|
||||
"Contents": [
|
||||
{
|
||||
"ETag": "\"7e94cc9b0f5226557b05a7c2565dd09f\"",
|
||||
"Key": "hpNdFUxruNuwm",
|
||||
"LastModified": "2021-08-16T06:44:14Z",
|
||||
"Owner": {
|
||||
"DisplayName": "owner name",
|
||||
"ID": "owner id"
|
||||
},
|
||||
"Size": 6916,
|
||||
"StorageClass": "STANDARD"
|
||||
}
|
||||
],
|
||||
"Delimiter": "",
|
||||
"EncodingType": null,
|
||||
"IsTruncated": true,
|
||||
"Marker": "hvlcCQFSOD5TD",
|
||||
"MaxKeys": 1,
|
||||
"Name": "mybucketdapr",
|
||||
"NextMarker": "hzaUPWjmvyi9W",
|
||||
"Prefix": ""
|
||||
}
|
||||
```
|
||||
## Related links
|
||||
|
||||
- [Basic schema for a Dapr component]({{< ref component-schema >}})
|
||||
|
|
|
|||
|
|
@ -26,6 +26,7 @@ Table captions:
|
|||
| [Hazelcast]({{< ref setup-hazelcast.md >}}) | Alpha | v1 | 1.0 |
|
||||
| [MQTT]({{< ref setup-mqtt.md >}}) | Alpha | v1 | 1.0 |
|
||||
| [NATS Streaming]({{< ref setup-nats-streaming.md >}}) | Beta | v1 | 1.0 |
|
||||
| [JetStream]({{< ref setup-jetstream.md >}}) | Alpha | v1 | 1.4 |
|
||||
| [Pulsar]({{< ref setup-pulsar.md >}}) | Alpha | v1 | 1.0 |
|
||||
| [RabbitMQ]({{< ref setup-rabbitmq.md >}}) | Alpha | v1 | 1.0 |
|
||||
| [Redis Streams]({{< ref setup-redis-pubsub.md >}}) | GA | v1 | 1.0 |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,97 @@
|
|||
---
|
||||
type: docs
|
||||
title: "JetStream"
|
||||
linkTitle: "JetStream"
|
||||
description: "Detailed documentation on the NATS JetStream component"
|
||||
aliases:
|
||||
- "/operations/components/setup-pubsub/supported-pubsub/setup-jetstream/"
|
||||
---
|
||||
|
||||
## Component format
|
||||
To setup JetStream pubsub create a component of type `pubsub.jetstream`. See
|
||||
[this guide]({{< ref
|
||||
"howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to
|
||||
create and apply a pubsub configuration.
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: jetstream-pubsub
|
||||
namespace: default
|
||||
spec:
|
||||
type: pubsub.jetstream
|
||||
version: v1
|
||||
metadata:
|
||||
- name: natsURL
|
||||
value: "nats://localhost:4222"
|
||||
- name: name
|
||||
value: "connection name"
|
||||
- name: durableName
|
||||
value: "consumer durable name"
|
||||
- name: queueGroupName
|
||||
value: "queue group name"
|
||||
- name: startSequence
|
||||
value: 1
|
||||
- name: startTime # in Unix format
|
||||
value: 1630349391
|
||||
- name: deliverAll
|
||||
value: false
|
||||
- name: flowControl
|
||||
value: false
|
||||
```
|
||||
|
||||
## Spec metadata fields
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|----------------|:--------:|---------|---------|
|
||||
| natsURL | Y | NATS server address URL | "`nats://localhost:4222`"|
|
||||
| name | N | NATS connection name | `"my-conn-name"`|
|
||||
| durableName | N | [Durable name] | `"my-durable"` |
|
||||
| queueGroupName | N | Queue group name | `"my-queue"` |
|
||||
| startSequence | N | [Start Sequence] | `1` |
|
||||
| startTime | N | [Start Time] in Unix format | `1630349391` |
|
||||
| deliverAll | N | Set deliver all as [Replay Policy] | `true` |
|
||||
| flowControl | N | [Flow Control] | `true` |
|
||||
|
||||
## Create a NATS server
|
||||
|
||||
{{< tabs "Self-Hosted" "Kubernetes">}}
|
||||
|
||||
{{% codetab %}}
|
||||
You can run a NATS Server with JetStream enabled locally using Docker:
|
||||
|
||||
```bash
|
||||
docker run -d -p 4222:4222 nats:latest -js
|
||||
```
|
||||
|
||||
You can then interact with the server using the client port: `localhost:4222`.
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
Install NATS JetStream on Kubernetes by using the [helm](https://github.com/nats-io/k8s/tree/main/helm/charts/nats#jetstream):
|
||||
|
||||
```bash
|
||||
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
|
||||
helm install my-nats nats/nats
|
||||
```
|
||||
|
||||
This installs a single NATS server into the `default` namespace. To interact
|
||||
with NATS, find the service with: `kubectl get svc my-nats`.
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Related links
|
||||
- [Basic schema for a Dapr component]({{< ref component-schema >}})
|
||||
- Read [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components
|
||||
- [Pub/Sub building block]({{< ref pubsub >}})
|
||||
- [JetStream Documentation](https://docs.nats.io/jetstream/jetstream)
|
||||
- [NATS CLI](https://github.com/nats-io/natscli)
|
||||
|
||||
|
||||
[Durable Name]: https://docs.nats.io/jetstream/concepts/consumers#durable-name
|
||||
[Start Sequence]: https://docs.nats.io/jetstream/concepts/consumers#deliverbystartsequence
|
||||
[Start Time]: https://docs.nats.io/jetstream/concepts/consumers#deliverbystarttime
|
||||
[Replay Policy]: https://docs.nats.io/jetstream/concepts/consumers#replaypolicy
|
||||
[Flow Control]: https://docs.nats.io/jetstream/concepts/consumers#flowcontrol
|
||||
|
|
@ -54,6 +54,11 @@ spec:
|
|||
The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
|
||||
{{% /alert %}}
|
||||
|
||||
{{% alert title="Warning" color="warning" %}}
|
||||
NATS Streaming has been [deprecated](https://github.com/nats-io/nats-streaming-server/#warning--deprecation-notice-warning).
|
||||
Please consider using [NATS JetStream]({{< ref setup-jetstream >}}) going forward.
|
||||
{{% /alert %}}
|
||||
|
||||
## Spec metadata fields
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|
|
@ -111,3 +116,4 @@ For example, if installing using the example above, the NATS Streaming address w
|
|||
- [Basic schema for a Dapr component]({{< ref component-schema >}})
|
||||
- Read [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components
|
||||
- [Pub/Sub building block]({{< ref pubsub >}})
|
||||
- [NATS Streaming Deprecation Notice](https://github.com/nats-io/nats-streaming-server/#warning--deprecation-notice-warning)
|
||||
|
|
|
|||
Loading…
Reference in New Issue