Skip to content

Commit

Permalink
add documentation on live channel condition
Browse files Browse the repository at this point in the history 
Signed-off-by: Johannes Schneider <johannes.schneider@bosch.io>
  • Loading branch information
@jokraehe
jokraehe committed Dec 10, 2021
1 parent f1e84d9 commit b1be814
Show file tree
Hide file tree
Showing 2 changed files with 31 additions and 15 deletions.
17 changes: 16 additions & 1 deletion documentation/src/main/resources/pages/ditto/basic-conditional-requests.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ Conditional requests are supported by HTTP API, WebSocket, Ditto protocol and Di

READ permission is necessary on the resource specified in the condition, otherwise, the request will fail.


## Examples

In this part, we will show how to use conditional updates via HTTP API, Ditto protocol, and Ditto Java Client.
Expand Down Expand Up @@ -117,6 +116,22 @@ client.twin().forFeature(ThingId.of("org.eclipse.ditto:fancy-thing"), "temperatu
});
```

## Live channel condition

Ditto also supports retrieving thing data with an automatic approach for switching between [twin](protocol-twinlive.html#twin) and [live](protocol-twinlive.html#live) channel.

Conditions are defined with RQL as described [before](#defining-conditions). If a condition is matched, the Thing data is retrieved from the device itself.

```
GET .../things/{thingId}?live-channel-condition=eq(attributes/useLiveChannel,'true')
```

Additionally, a strategy to handle timeouts for retrieving live thing data can be specified with the http header `on-live-channel-timeout`.
The request can either `fail` with a status code 408 or `use-twin` as a fallback, in that case the Thing date would be returned from Ditto directly.

The response includes two additional http headers `live-channel-condition-matched` and `channel` to indicate which channel was used to retrieve the thing data.
Also, it can be used to update the twin state via a specific [payload mapper](connectivity-mapping.html#updatetwinwithliveresponse-mapper).

## Further reading on RQL expressions

See [RQL expressions](basic-rql.html).
29 changes: 15 additions & 14 deletions documentation/src/main/resources/pages/ditto/protocol-specification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,20 +78,21 @@ since they are themselves not case-sensitive.

There are some pre-defined headers, which have a special meaning for Ditto:

| Header Key | Description | Possible values |
|------------|--------------------------------|---------------------------|
| `content-type` | The content-type which describes the [value](#value) of Ditto Protocol messages. | `String` |
| `correlation-id` | Used for correlating protocol messages (e.g. a **command** would have the same correlation-id as the sent back **response** message). | `String` |
| `ditto-originator` | Contains the first authorization subject of the command that caused the sending of this message. Set by Ditto. | `String` |
| `if-match` | Has the same semantics as defined for the [HTTP API](httpapi-concepts.html#conditional-requests). | `String` |
| `if-none-match` | Has the same semantics as defined for the [HTTP API](httpapi-concepts.html#conditional-requests). | `String` |
| `response-required` | Configures for a **command** whether or not a **response** should be sent back. | `Boolean` - default: `true` |
| `requested-acks` | Defines which [acknowledgements](basic-acknowledgements.html) are requested for a command processed by Ditto. | `JsonArray` of `String` - default: `["twin-persisted"]` |
| `ditto-weak-ack` | Marks [weak acknowledgements](basic-acknowledgements.html) issued by Ditto. | `Boolean` - default: `false` |
| `timeout` | Defines how long the Ditto server should wait, e.g. applied when waiting for requested acknowledgements. | `String` - e.g.: `42s` or `250ms` or `1m` - default: `60s`|
| `version` | Determines in which schema version the `payload` should be interpreted. | `Number` - currently: \[1,2\] |
| `put-metadata` | Determines which Metadata information is stored in the thing. | `JsonArray` of `JsonObject`s containing [metadata](basic-metadata.html) to apply. |
| `condition` | The condition to evaluate before applying the request. | `String` containing [condition](basic-conditional-requests.html) to apply. |
| Header Key | Description | Possible values |
|------------|--------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| `content-type` | The content-type which describes the [value](#value) of Ditto Protocol messages. | `String` |
| `correlation-id` | Used for correlating protocol messages (e.g. a **command** would have the same correlation-id as the sent back **response** message). | `String` |
| `ditto-originator` | Contains the first authorization subject of the command that caused the sending of this message. Set by Ditto. | `String` |
| `if-match` | Has the same semantics as defined for the [HTTP API](httpapi-concepts.html#conditional-requests). | `String` |
| `if-none-match` | Has the same semantics as defined for the [HTTP API](httpapi-concepts.html#conditional-requests). | `String` |
| `response-required` | Configures for a **command** whether or not a **response** should be sent back. | `Boolean` - default: `true` |
| `requested-acks` | Defines which [acknowledgements](basic-acknowledgements.html) are requested for a command processed by Ditto. | `JsonArray` of `String` - default: `["twin-persisted"]` |
| `ditto-weak-ack` | Marks [weak acknowledgements](basic-acknowledgements.html) issued by Ditto. | `Boolean` - default: `false` |
| `timeout` | Defines how long the Ditto server should wait, e.g. applied when waiting for requested acknowledgements. | `String` - e.g.: `42s` or `250ms` or `1m` - default: `60s` |
| `version` | Determines in which schema version the `payload` should be interpreted. | `Number` - currently: \[1,2\] |
| `put-metadata` | Determines which Metadata information is stored in the thing. | `JsonArray` of `JsonObject`s containing [metadata](basic-metadata.html) to apply. |
| `condition` | The condition to evaluate before applying the request. | `String` containing [condition](basic-conditional-requests.html) to apply. |
| `live-channel-condition` | The condition to evaluate before retrieving thing data from the device. | `String` containing [live channel condition](basic-conditional-requests.html#live-channel-condition) to apply. |

Custom headers of messages through the [live channel](protocol-twinlive.html) are delivered verbatim. When naming
custom headers, it is best to attach a prefix specific to your application, that does not conflict with Ditto or
Expand Down

0 comments on commit b1be814

Please sign in to comment.