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.
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 it not sufficient, Ditto also allows to provide an RQL expression specifying a Thing payload based condition determining which events should be emitted and which don’t.
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*")
You get the idea of how mighty this becomes by utilizing Ditto’s RQL expressions.