Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Actors] Add ttl and data to API reference #4188

Merged
merged 9 commits into from
Jun 19, 2024
29 changes: 27 additions & 2 deletions daprdocs/content/en/reference/api/actors_api.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ Parameter | Description

#### Examples

> Note, the following example uses the `ttlInSeconds` field, which requires the [`ActorStateTTL` feature enabled]]({{< ref "support-preview-features.md" >}}).
> Note, the following example uses the `ttlInSeconds` field, which requires the [`ActorStateTTL` feature enabled]({{< ref "support-preview-features.md" >}}).

```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
Expand Down Expand Up @@ -202,6 +202,8 @@ A JSON object with the following fields:
|-------|--------------|
| `dueTime` | Specifies the time after which the reminder is invoked. Its format should be [time.ParseDuration](https://pkg.go.dev/time#ParseDuration)
| `period` | Specifies the period between different invocations. Its format should be [time.ParseDuration](https://pkg.go.dev/time#ParseDuration) or ISO 8601 duration format with optional recurrence.
| `ttl` | Sets time at or interval after which the timer or reminder will be expired and deleted. Its format should be [time.ParseDuration format](https://pkg.go.dev/time#ParseDuration), RFC3339 date format, or ISO 8601 duration format.
| `data` | A string value and can be any related content. Content is returned when the reminder expires. For example this may be useful for returning a URL or anything related to the content.

`period` field supports `time.Duration` format and ISO 8601 format with some limitations. For `period`, only duration format of ISO 8601 duration `Rn/PnYnMnWnDTnHnMnS` is supported. `Rn/` specifies that the reminder will be invoked `n` number of times.

Expand All @@ -210,7 +212,11 @@ A JSON object with the following fields:

If `Rn/` is not specified, the reminder will run an infinite number of times until deleted.

The following specifies a `dueTime` of 3 seconds and a period of 7 seconds.
If only `ttl` and `dueTime` are set, the reminder will be accepted. However, only the `dueTime` takes effect. For example, the reminder triggers at `dueTime`, and `ttl` is ignored.

If `ttl`, `dueTime`, and `period` are set, the reminder first fires at `dueTime`, then repeatedly fires and expires according to `period` and `ttl`.

The following example specifies a `dueTime` of 3 seconds and a period of 7 seconds.

```json
{
Expand All @@ -237,6 +243,25 @@ To configure the reminder to fire only once, the period should be set to empty s
}
```

When you specify the repetition number in both `period` and `ttl`, the timer/reminder is stopped when either condition is met. The following example has a timer with a `period` of 3 seconds (in ISO 8601 duration format) and a `ttl` of 20 seconds. This timer fires immediately after registration, then every 3 seconds after that for the duration of 20 seconds, after which it never fires again since the `ttl` was met

```json
{
"period":"PT3S",
"ttl":"20s"
}
```

Need description for data.

```json
{
"data": "someData",
"dueTime": "1m",
"period": "20s"
}
```

#### HTTP Response Codes

Code | Description
Expand Down
Loading