Invoking other parts of the Cumulocity IoT REST API
For individual event types, Apama provides event-specific interfaces for performing actions. See
Using managed objects,
Using alarms,
Using events,
Using measurements, or
Using operations for more information. This topic covers how to interact with the remaining Cumulocity IoT REST API.
Typically, interacting with the REST API or making HTTP requests through the Cumulocity IoT platform requires manual setup, including configuring tenant information and authentication methods. The generic request/response interface described below does this for you. This is also the case for users creating EPL apps with the Streaming Analytics application in Cumulocity IoT.
Note:
While the
GenericRequest/
GenericResponse interface can be used for any request to the platform, it makes several assumptions about the request and response format that the Cumulocity IoT REST API guarantees. The
CumulocityRequestInterface event described in
Invoking microservices is more appropriate for low-level requests, such as making requests to other microservices.
Create a new com.apama.cumulocity.GenericRequest using new GenericRequest and then individually set whichever fields are needed by name. You must always set the reqId (which is used to tie requests and responses together) to a unique identifier generated by the com.apama.cumulocity.Util.generateReqId() action. You will also need to set the HTTP method (also known as the verb) and path. For some APIs, you will also need the queryParams (which populates the query string), body (typically a sequence or dictionary that will be converted to JSON by the plug-in) and/or additional HTTP headers. The GenericRequest event should be sent to the channel specified by the GenericRequest.SEND_CHANNEL constant.
To receive responses, you must subscribe to the channel given in the GenericResponse.SUBSCRIBE_CHANNEL constant. The response events will contain the reqId identifier specified in the request, as well as a body in a dictionary<any,any> where the AnyExtractor can be used to extract the expected content. This dictionary contains a structure which is equivalent to the JSON payload returned by Cumulocity IoT. For the cases where no body is expected in the response (for example, for a DELETE request), only a GenericResponseComplete event will be received for the request identifier.
When using an API which returns a collection, the results are automatically split into multiple GenericResponse events, followed by a GenericResponseComplete, all with the reqId identifier provided in the request.
Here is a simple example of using the API:
GenericRequest request := new GenericRequest;
request.reqId := com.apama.cumulocity.Util.generateReqId();
request.method := "GET";
request.isPaging := true;
request.path := "/measurement/measurements";
monitor.subscribe(GenericResponse.SUBSCRIBE_CHANNEL);
on all GenericResponse(reqId=request.reqId) as response
and not GenericResponseComplete(reqId=request.reqId)
{
AnyExtractor dict := AnyExtractor(response.getBody());
AnyExtractor source := AnyExtractor(dict.getDictionary("source"));
try{
AnyExtractor speed :=
AnyExtractor(dict.getDictionary("c8y_SpeedMeasurement")["speed"]);
log "Found measurement of type: c8y_SpeedMeasurement with id : " +
dict.getString("id") + " and source id :" + source.getString("id") +
" and speed "+speed.getFloat("value").toString()+
" "+speed.getString("unit")
at INFO;
}
catch(Exception e){
log "Failed to parse unexpected measurement : " +
dict.toString() at WARN;
}
}
on GenericResponseComplete(reqId=request.reqId)
{
monitor.unsubscribe(GenericResponse.SUBSCRIBE_CHANNEL);
}
send request to GenericRequest.SEND_CHANNEL;