At the Ditto API there are different ways for getting notified of such events:
- Via the WebSocket API a WebSocket client gets all Events the authenticated subject (e.g. a user) is authorized to receive as Ditto Protocol messages.
- Via HTTP SSEs a consumer of the SSE
EventSourcegets all Events the authenticated subject (e.g. a user) is authorized to receive directly in the format of the changed entity (e.g. as Thing JSON format).
- Via an established connection in the connectivity service
In order to not get all of the events an authenticated subject (e.g. a user added in nginx) is allowed to see, but to filter for specific criteria, events may be filtered on the Ditto backend side before they are sent to an event receiver.
The above mentioned different APIs provide their own mechanisms on how to define such filters, but they all share the common functionality of based on which information events may be filtered.
By providing the
namespaces filter, a comma separated list of which namespaces to include in the result, only Things
in namespaces of interest are considered and thus only events of these Things are emitted at the API.
For example, one would only subscribe for events occurring in 2 specific namespaces by defining:
By RQL expression
If filtering by namespaces is not sufficient, Ditto also allows to provide an RQL expression specifying:
- a Thing payload based condition determining which events should be emitted and which should not
- a filter based on the fields of the Ditto Protocol message which should be filtered,
- using the
topic:actionplaceholder as query property, filtering for lifecycle events (
deleted) and other filter options on the Ditto Protocol topic can be done
- using the
resource:pathplaceholder as query property, filtering based on the affected Ditto Protocol path of a Ditto Protocol message can be done
- for all supported placeholders, please refer to the placeholders documentation
- using the
Data which was not changed will only be considered when it was enriched via “extraFields”.
This provides the opportunity to formulate filters like the following:
Only emit events when attribute “count” was changed to a value greater than 42:
Only emit events for Things starting with myThing when a feature “lamp” was modified:
Only emit events when the attribute “manufacturer” was changed to starting with “ACME & Sons”.
& must be escaped in that case:
filter=like(attributes/manufacturer,"ACME %26 Sons*")
Only emit events for Thing creation and deletion:
You get the idea of how mighty this becomes by utilizing Ditto’s RQL expressions.