Querying for events
To search for an event or a collection of events, send the com.apama.cumulocity.FindEvent event to Cumulocity IoT, with a unique reqId to the com.apama.cumulocity.FindEvent.SEND_CHANNEL channel.
The transport will then respond with zero or more com.apama.cumulocity.FindEventResponse events and then one com.apama.cumulocity.FindEventResponseAck event on the com.apama.cumulocity.FindEventResponse.SUBSCRIBE_CHANNEL channel.
Example:
integer reqId := com.apama.cumulocity.Util.generateReqId();
com.apama.cumulocity.FindEvent request := new com.apama.cumulocity.FindEvent;
request.reqId := reqId;
// Filter based on event type
request.params.add("type", "c8y_DoorOpenedEvent");
// Subscribe to com.apama.cumulocity.FindEventResponse.SUBSCRIBE_CHANNEL to listen
// for responses
monitor.subscribe(com.apama.cumulocity.FindEventResponse.SUBSCRIBE_CHANNEL);
// Listen for responses based on reqId
on all com.apama.cumulocity.FindEventResponse(reqId=reqId) as response
// Avoid listener leaks by terminating the listener on completion of the request
and not com.apama.cumulocity.FindEventResponseAck(reqId=reqId)
{
log "Received Event " + response.toString() at INFO;
}
// Listen for com.apama.cumulocity.FindEventResponseAck,
// this indicates that all responses have been received
on com.apama.cumulocity.FindEventResponseAck(reqId=reqId) as requestCompleted
{
log "Received all Event(s) for request " +
requestCompleted.reqId.toString() at INFO;
// Request is completed and we can unsubscribe from this channel
monitor.unsubscribe(com.apama.cumulocity.FindEventResponse.SUBSCRIBE_CHANNEL);
}
// Send request to find available events
send request to com.apama.cumulocity.FindEvent.SEND_CHANNEL;
Supported query parameters
You can provide the following query parameters with the request:
Parameter | Description |
id | Search for an event based on eventId. When searching for an event based on Id, all the query parameters listed below are ignored. |
source | Search for events based on the device identifier or asset identifier of the source. |
type | Search for events based on the type. |
dateFrom | Search for events from a start date. The date and time is provided as seconds since the epoch. |
dateTo | Search for events within a time range. This is to be used in combination with dateFrom. The date and time is provided as seconds since the epoch. |
fromCreationDate | Similar to dateFrom, but fetches the events based on the creation date. The date and time is provided as seconds since the epoch. |
toCreationDate | Search for events that have been created within a date range. This is to be used in combination with fromCreationDate. The date and time is provided as seconds since the epoch. |
pageSize | Indicates how many entries of the collection are to be retrieved from Cumulocity IoT. This is a batching parameter for getting multiple responses from Cumulocity IoT. A larger pageSize does fewer requests to Cumulocity IoT to retrieve all the events, but each request is larger. By default, 1000 events are in each page and there is an upper limit of 2000. |
currentPage | Retrieve a specific page of results for the given pageSize. If currentPage is set, then only a single page is requested. If currentPage is not set (default), all the pages are requested. |
revert | Boolean parameter. If a range query is used (that is, the query includes at least one of the dateFrom or dateTo parameters), you can reverse the order in which the matching events are returned by adding the query parameter revert=true. This returns the oldest events first. By default, Cumulocity IoT returns the latest events first. |
Query result paging
Cumulocity IoT queries support paging of data for requesting a specific range of the responses received. For more information, see
Paging Cumulocity IoT queries.