Attributes
This section covers different scenarios. The first scenario shows how to assign one attribute with two different values to one time series. The next scenarios show different possibilities of aggregating time series data via attributes.
Assigning Attributes to Time Series
To assign one (or multiple) attributes, they must exist before. The "Type" property of the attribute needs to have a numeric value. The "Type" defines the data type which can be assigned to time series via attributes. The different numeric "Type" values can be looked up in a list that can be queried by the following URL: {URL}/api/attributetypes. In the following example, the type will define text (2) values.
Create attribute
POST {protocol://host:port/basePath}/api/repositories/{repository}/attributes HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 71
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"ID": -1,
"Name": "Documentation_Attribute",
"Type": 2
}The server now responds with the assigned ID of the attribute. Let's assume it's 192. Assigning an attribute with more than one values must be done through the ID of the time series. A certain value is valid until it get's replaced by a new value. In the following POST statement, the attribute has the value "null" from 1970 to 01.04.2017 at 00:00:00, from the 01.04.2017 to the 02.04.2017 at 00:00:00 it has the value "Text1". Ongoing from the 02.04.2017 at 00:00:00 the attribute has the value "Text2".
It is very important to notice, that the attributes being assigned before the following POST call will be overwritten, so the body has to contain all existing and new attribute values. One exception exists. If the request body only contains one attribute (this means without the square brackets), the attribute and its values will be added to the already assigned attributes of the time series in question. Changing values of one single already assigned attribute can be achieved via the PUT statement.
Assign one attribute with multiple values
POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/{TS_ID}/attributes HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 108
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
[
{
"AttributeID": 192,
"Values":{
"2017-04-01T00:00:00Z": "Text1",
"2017-04-02T00:00:00Z": "Text2"
}
}
]Aggregating Time Series Data Using Attributes
There are currently two possible ways of aggregating over attributes. The first one is via the {URL}/api/repositories/{repository}/timeseriescollections/data/sum call. This call searches for all time series with the attribute value "Text1" in the time from 01.04.2017 01:00:00 to 01.04.2017 02:00:00. The interval query parameter defines the interval of the returned data. In this example it is defined to be an one hour interval.
Aggregate via the timeseriescollection/data/sum call
GET {protocol://host:port/basePath}/api/repositories/{repository}/timeseriescollections/data/sum?from=2017-04-01T01:00:00Z&to=2017-04-01T02:00:00Z&interval=3&attribute=Automated_Test_Attribute|Text1 HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
The response from the server looks as follows:
Response from the server
{
"Interval": {
"Value": 3,
"Multiplier": 1
},
"Unit": null,
"Data": [
{
"From": "2017-04-01T01:00:00Z",
"Value": 110,
"Flag": 9
}
]
}Alternatively, aggregation can also be achieved via the TSAA call. The syntax or the TSAA formula is as follows: TSAA(unit:string, resultIsValidAsLongOneValueIsValid:boolean, attributeName:string|attributeValue:string). The second (boolean) parameter lets the service return values with the flag 9, as long one value of the aggregated values was valid (which means it had the flag 9). Otherwise, the service only returns the values with the flag 9, when all values are valid. In our example, the TSAA call looks as follows: TSAA("kW", "TRUE", "Automated_Test_Attribute|Test1").
TSAA call
GET {protocol://host:port/basePath}/api/repositories/{repository}/calculations?from=2017-04-01T01:00:00Z&to=2017-04-01T02:00:00Z&formula=TSAA("kW","TRUE","Automated_Test_Attribute|Test1")&calculationInterval=3&calculationIntervalMultiplier=1 HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)The server-response looks the same as in the example before.
Example
Reading aggregated data from time series with assigned attributes returns the sum of values of all time series in the specified time period. This subsection shows how to achieve this.
Posting time series will be left out in favor of the general overview.
The order of the first step (assigning the attribute and its values) and the second step (persisting data on the time series) can be switched.
The first step assigns the same attribute to two different time series. The values of the attribute change at on of the time series in the middle of the (to be queried) time period. This means, that the value changes from "AT123456" to "AT99999" from 2001-01-01T00:00:00Z. The other time series has the same value in the whole time period.
First step: first attribute assign call
POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Documentation_TS/attributes HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 174
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
[
{
"AttributeID": 192,
"Values":{
"2000-01-01T00:00:00Z": "AT123456",
"2001-01-01T00:00:00Z": "AT99999",
}
}
]First step: Second attribute assign call
POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Documentation_TS_2/attributes HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 174
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
[
{
"AttributeID": 192,
"Values":{
"2000-01-01T00:00:00Z": "AT123456",
}
}
]In the second step, data is being persisted on both time series in the time period from 2000-01-01T00:00:00Z to 2002-01-01T00:00:00Z:
Second step: First data persisting call
POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Documentation_TS/data HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 333
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"Interval": {
"Value": 8,
"Multiplier": 1
},
"Unit": "none",
"Data": [
{
"From":"2000-01-01T00:00:00Z",
"Value": 71.3,
"Flag": 9
}
]
}Second step: Second data persisting call
POST {protocol://host:port/basePath}/api/repositories/{repository}/timeseries/Documentation_TS_2/data HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Content-Length: 333
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
{
"Interval": {
"Value": 8,
"Multiplier": 1
},
"Unit": "none",
"Data": [
{
"From":"2000-01-01T00:00:00Z",
"Value": 3.7,
"Flag": 9
}
]
}Getting the data of alle time series with the assign attribute and the value "AT123456" in the time period from 2000-01-01T00:00:00Z to 2002-01-01T00:00:00Z results in the following answer from the server:
Third step: Getting the persisting
{
"Interval": {
"Value": 8,
"Multiplier": 1
},
"Unit": "none",
"Data": [
{
"From": "2000-01-01T00:00:00Z",
"Value": 75,
"Flag": 9
},
{
"From": "2001-01-01T00:00:00Z",
"Value": 3.7,
"Flag": 9
}
]
}Time Series With More Than One Attribute
Getting data from time series with multiple attributes (and values) is achieved by connecting multiple attribute query- parameters with an & operator, meaning that the data from those time series which have all attributes (and possibly values) assigned will be aggregated. The following call uses a text and a boolean attribute for filtering.
Mutliple attributes call
GET {protocol://host:port/basePath}/api/repositories/{repository}/timeseriescollections/data/sum?from=2017-04-01T01:00:00Z&to=2017-04-01T02:00:00Z&interval=3&attribute=Automated_Test_Attribute|Text1&attribute=Automated_Test_Attribute_2|true HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)Similarly, this can be done using ad-hoc calculations and the aforementioned TSAA function:
TSAA call
GET {protocol://host:port/basePath}/api/repositories/{repository}/calculations?from=2017-04-01T01:00:00Z&to=2017-04-01T02:00:00Z&formula=TSAA("kW","TRUE","Automated_Test_Attribute|Test1")&calculationInterval=3&calculationIntervalMultiplier=1 HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)Implicitly Assigning an Attribute to Multiple Time Series in a Single Request
The following request assigns the attribute with ID 123 to two series (one with ID 15, one with ID 16) and sets the value to "attribute value" starting with January 1st 2018.
Bulk assignment
PUT {protocol://host:port/basePath}/api/repositories/{repository}/timeseriescollections/attributes/123/values/2018-01-01T00:00:00Z HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at
Content-Type: application/json
[
{
"ID": 15,
"Value": "attribute value"
},
{
"ID": 16,
"Value": "attribute value"
},
]In order to delete the entire attribute assignment from both series, the following request can be used
Bulk removal of attributes
DELETE {protocol://host:port/basePath}/api/repositories/{repository}/timeseriescollections/attributes/123?ID=15&ID=16 HTTP/1.1
Accept: application/json
Authorization: Basic TWF4Ok11c3Rlcm1hbm4xMjM=
Host: webtsm.hakom.at