Event Service¶
Introduction¶
Event Service allows high rate of insertion and retrieval of time series events. It allows to store in-order or out of order sequence of events and does not allow to alter or tamper any events stored on it. It can be used as event sourcing. Filtering and aggregation operations can be done on stored events using its APIs.This service can be used as an asynchronous pub-sub with storage facility with no loss of data.
Purpose of the Document¶
The following section describes how to work on Event service. After going through this document user will able to do the following activities using Event Service API swagger
Insert events in stream with payload format as sos json
Insert events in stream with payload format as flat json(sos compliant json)
Insert events in stream with payload format as flat json(any json)
Get events from stream by filtering with starttime and endtime
Get events from stream by filtering with observed property
Get aggregated event from stream by using aggrgation function(SUM,AVG,MAX,MIN,COUNT)
Get event from a stream by eventId
Get latest subscribed event from stream
Get list of subscribed events from stream
Get length of stream
Delete events from stream
Reference Document¶
Please refer to the following documents to get more details on Event Service
To understand the basic concepts of EventService please refer to the Concept guide.
For API details of EventService please refer to the API guide.
Event Service Using Swagger¶
Accessing Swagger¶
Currently Event Service is accessible only from Swagger no seperate portal is available for this. To access Event Service swagger, after signing into TCUP, click on the link API sandbox on the left hand side menu and then click on Explore button of Event Service in the below.
Insert Events in Stream with sos json¶
This API is used to insert events in a stream with sos payload format,single as well as bulk observations can be inserted.
Events will be inserted using various combinations of values of the below mentioned parameters
Parameter
Values
streamName
feature(“feature” value of the observation JSON will be used as a streamName) or sensor(“sensor” value of the observation JSON will be used as a streamName) or any custom stream name.
eventId
starttime(while inserting in stream ,“id” will be the “starttime” in observation JSON converted to epoch time +“-”+sequenceNumber),this will be used for inorder data or auto(while inserting in stream, “id” will be the system generated epochtime+”-”+sequenceNumber),this will be used for outorder data
payloadFormat
sos format
streamNameType
constant for defining custom stream name or variable for defining variable stream name
Following is the sample input json in sos format for inserting 2 events in a stream :-
{
"version": "1.0.1",
"observations": [{
"sensor": "NEXUS12",
"feature": "room1",
"record": [{
"starttime": "03-Jun-2019 14:50:10.640 IST",
"output": [{
"name": "temp",
"value": "40.0",
"type": "decimal"
},
{
"name": "humidity",
"value": "91.0",
"type": "decimal"
}
]
}],
"meta-data": []
},
{
"sensor": "NEXUS12",
"feature": "room1",
"record": [{
"starttime": "03-Jun-2019 14:52:10.640 IST",
"output": [{
"name": "temp",
"value": "41.0",
"type": "decimal"
},
{
"name": "humidity",
"value": "92.0",
"type": "decimal"
}
]
}],
"meta-data": []
}
]}
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on POST /streams api in swagger, use the above json template and hit Try it out! button, it will insert events in stream as shown in the figure below:
Insert Events in Stream with flat json(sos compliant json)¶
This API is used to insert events in a stream with flat payload format,single as well as bulk observations can be inserted.
Events will be inserted using various combinations of values of the below mentioned parameters
Parameter
Values
streamName
feature(“feature” value of the observation JSON will be used as a streamName) or sensor(“sensor” value of the observation JSON will be used as a streamName) or any custom stream name.
eventId
starttime(while inserting in stream ,“id” will be the “starttime” in observation JSON converted to epoch time +“-”+sequenceNumber),this will be used for inorder data or auto(while inserting in stream, “id” will be the system generated epochtime+”-”+sequenceNumber),this will be used for outorder data
payloadFormat
flat format
streamNameType
constant for defining custom stream name or variable for defining variable stream name
Following is the sample input json in flat format for inserting 2 events in a stream :-
[
{
"startTime": "24-JUL-2019 15:30:00.640 IST",
"endtime": "24-JUL-2019 15:30:00.640 IST",
"associatedObservation": "O_209",
"position-global_latitude": "87",
"position-global_longitude": "57",
"position-global_altitude": "2m",
"feature": "bus-1",
"sensor": "sensor1",
"offering": "bus-tracking",
"validUpto": "23-JUL-2023 15:30:00 IST",
"privacy": "public",
"position-local_floor": "4A",
"position-local_floor_type": "text",
"speed": "40.0",
"speed_type": "decimal",
"meta-data_speedometer-version": "3.0",
"meta-data_speedometer-version_type": "double",
"parameter_traffic": "heavy",
"parameter_traffic_type": "text",
"quality_accuracy": "99",
"quality_accuracy_type": "number"
},{
"startTime": "24-JUL-2019 15:40:00.640 IST",
"endtime": "24-JUL-2019 15:40:00.640 IST",
"associatedObservation": "O_209",
"position-global_latitude": "88",
"position-global_longitude": "58",
"position-global_altitude": "2m",
"feature": "bus-2",
"sensor": "sensor2",
"offering": "bus-tracking",
"validUpto": "23-JUL-2023 15:30:00 IST",
"privacy": "public",
"position-local_floor": "4A",
"position-local_floor_type": "text",
"speed": "45.0",
"speed_type": "decimal",
"meta-data_speedometer-version": "3.0",
"meta-data_speedometer-version_type": "double",
"parameter_traffic": "heavy",
"parameter_traffic_type": "text",
"quality_accuracy": "99",
"quality_accuracy_type": "number"
}]
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on POST /streams api in swagger, use the above json template and hit Try it out! button, it will insert events in stream as shown in the figure below:
Insert Events in Stream with flat json(any json)¶
This API is used to insert events in a stream with flat payload format,single as well as bulk observations can be inserted.
Events will be inserted using various combinations of values of the below mentioned parameters
Parameter
Values
streamName
any custom stream name
eventId
auto(while inserting in stream, “id” will be the system generated epochtime+”-”+sequenceNumber),this will be used for outorder data
payloadFormat
flat format
streamNameType
constant for defining custom stream name or variable for defining variable stream name
Following is the sample input json in flat format for inserting 2 events in a stream :-
[
{
"temp": "35",
"humidity": "91"
},{
"temp": "42",
"humidity": "96"
}]
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on POST /streams api in swagger, use the above json template and hit Try it out! button, it will insert events in stream as shown in the figure below:
Get events from stream by filtering with starttime and endtime¶
This API is used to get events from stream by filtering with starttime and endtime.
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
startTime
Start datetime (DD-MMM-YYYY HH:mm:ss.SSS zzz)
endTime
End datetime (DD-MMM-YYYY HH:mm:ss.SSS zzz)
Following is the sample output json when starttime is given as 04-May-2020 14:55:10.640 IST and endtime is given as 04-May-2020 14:58:10.640 IST :-
[{
"id": "1588604170640-0",
"startTime": "04-May-2020 14:56:10.640 IST",
"feature": "room2",
"sensor": "sensor2",
"temp": "43.0",
"temp_type": "decimal",
"humidity": "94.0",
"humidity_type": "decimal"
},
{
"id": "1588604290640-0",
"startTime": "04-May-2020 14:58:10.640 IST",
"feature": "room2",
"sensor": "sensor2",
"temp": "45.0",
"temp_type": "decimal",
"humidity": "96.0",
"humidity_type": "decimal"
}
]
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams api in swagger, hit Try it out! button, it will fetch the desired events as shown in the figure below:
Get events from stream by filtering with observed property¶
This API is used to get events from stream by filtering with observed property.
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
fields
Logical operations (>,>=,<,<=,==,!=)with fields ,Example:fields=speed(>40) means fetch events from stream Where speed is greater than 40
Following is the sample output json when fields is given temp(>=42)
[
{
"id": "1588604050640-0",
"startTime": "04-May-2020 14:54:10.640 IST",
"feature": "room2",
"sensor": "sensor1",
"temp": "42.0",
"temp_type": "decimal",
"humidity": "93.0",
"humidity_type": "decimal"
},
{
"id": "1588604170640-0",
"startTime": "04-May-2020 14:56:10.640 IST",
"feature": "room2",
"sensor": "sensor2",
"temp": "43.0",
"temp_type": "decimal",
"humidity": "94.0",
"humidity_type": "decimal"
},
{
"id": "1588604290640-0",
"startTime": "04-May-2020 14:58:10.640 IST",
"feature": "room2",
"sensor": "sensor2",
"temp": "45.0",
"temp_type": "decimal",
"humidity": "96.0",
"humidity_type": "decimal"
}
]
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams api in swagger, hit Try it out! button, it will fetch the desired events as shown in the figure below:
Get aggregated event from stream by using aggrgation function(SUM,AVG,MAX,MIN,COUNT)¶
This API is used to get aggregated event from stream by using one aggrgation function(SUM,AVG,MAX,MIN,COUNT)
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
f
Aggregate functions(SUM,AVG,COUNT,MAX,MIN),Example:fields=temp&f=SUM means calculate sum of temp and return that event from stream
Following is the sample output json when fields given as ‘temp’ and aggregate function given as ‘SUM’
[
{
"SUM_temp": 211
}
]
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams api in swagger, hit Try it out! button, it will fetch the desired event as shown in the figure below:
Get event from a stream by eventId¶
This API is used to get event from a stream by eventId
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
eventId
Event id
Following is the sample output json when eventId is given as ‘1588603810640-0’
{
"id": "1588603810640-0",
"startTime": "04-May-2020 14:50:10.640 IST",
"feature": "room1",
"sensor": "sensor1",
"temp": "40.0",
"temp_type": "decimal",
"humidity": "91.0",
"humidity_type": "decimal"
}
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams/{streamName}/{eventId} api in swagger, hit Try it out! button, it will fetch the desired event as shown in the figure below:
Get latest subscribed event from stream¶
This API is used to get latest subscribed event from stream
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
timeout
Timeout in seconds
Following is the sample output json
{
"id": "1570797482261-0",
"temp": "41",
"humidity": "92"
}
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams/subscribelatest api in swagger, hit Try it out! button, it will fetch the desired event as shown in the figure below:
Get list of subscribed events from stream¶
This API is used to get list of subscribed events from stream
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
timeout
Timeout in seconds
Following is the sample output json
[
{
"id": "1570797412460-0",
"temp": "41",
"humidity": "92"
},
{
"id": "1570797426693-0",
"temp": "41",
"humidity": "92"
},
{
"id": "1570797443144-0",
"temp": "41",
"humidity": "93"
}
]
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams/subscribe api in swagger, hit Try it out! button, it will fetch the desired events as shown in the figure below:
Get length of stream¶
This API is used to get length of stream by stream name
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
Following is the sample output json
{
"length": 5
}
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on GET /streams/length api in swagger, hit Try it out! button, it will fetch the desired event as shown in the figure below:
Delete events from stream¶
This API is used to delete events from stream by eventId.If no eventId is specified then entire stream will be deleted
Below are the mentioned parameters used
Parameter
Values
streamName
Stream name
eventId
Event ID’s separated by comma
Following is the sample output json
{
"message": "successfully deleted from stream ",
"status": "200"
}
Now we will execute the above API in the following way:
Using Event Service API swagger¶
Click on DELETE /streams/{streamName} api in swagger, hit Try it out! button, it will delete events from stream as shown in the figure below:
