attribute.history
The attribute.history command is used to obtain historical attribute data for a thing.
Attribute history can be requested by specifying:
- A definite time period using a start and end date
- A time period defined by the "last period of time" style query (last "24h", etc.)
- A last number of records
TR50 Request
// Definite time period request
{
"1": {
"command": "attribute.history",
"params": {
"thingKey": "mything",
"key": "myattr",
"start": "2014-01-01T00:00:00Z",
"end": "2014-01-31T23:59:59Z"
}
}
}
// Last period of time request
{
"1": {
"command": "attribute.history",
"params": {
"thingKey": "mything",
"key": "myattr",
"last": "24h"
}
}
}
// Last number of records request
{
"1": {
"command": "attribute.history",
"params": {
"thingKey": "mything",
"key": "myattr",
"records": 100
}
}
}
Request Parameters
Name |
Type | Required |
Description |
---|---|---|---|
thingKey | String | Yes* | Key of the thing. |
thingId | String | Id of the thing. | |
esn | String | ESN of the thing. | |
iccid | String | ICCID of the thing. | |
imei | String | IMEI of the thing. | |
imsi | String | IMSI of the thing. | |
meid | String | MEID of the thing. | |
msisdn | String | MSISDN of the thing. | |
*One of the above parameters is required to identify the thing. The parameter identifies the thing to which the alarm data is associated. If omitted, the thingKey associated with your session will be used. | |||
key | String | Yes | The key for the attribute that you wish to publish. |
split | Bool | Set to true if you want the timestamp and value fields to be split into two arrays | |
start | String | When doing a definite time period request this is the timestamp for the start of the specified time window. | |
end | String | When doing a definite time period request this is the timestamp for the end of the specified time window. | |
last | String | When doing a last period of time request this specifies the last X amount of time in seconds (s), minutes (m), hours (h), or days (d). | |
offset | Integer | The starting list offset, used for pagination. Defaults to 0 if not specified. The maximum offset you can set is 5000 | |
limit | Integer | Limit the number of results returned. The maximum limit you can set is 5000. | |
sort | String | A string indicated the direction (+ for ascending, - for descending) and column to sort the results by. To sort by the value descending, use "-value". | |
records | Integer | When doing a last number of records request this specifies the number of records to return. A value of zero returns the global maximum number of records. | |
returnIds | Bool | Returns the id of the attributes. | |
showMillis | Bool | Returns the ts with milliseconds. |
If the command is sent successfully a success message and the attribute values found are returned. Otherwise, an error and error message will be returned.
The number of records returned is limited to 5000 by the deviceWISE Cloud. If your query returns more results than the limit of the deviceWISE Cloud, you should shorten your time window or lower the number of records you are requesting.
{
"1": {
"success": true,
"params": {
"values": [
{
"value": "attribute value 1",
"ts": "2014-01-01T01:01:01Z"
},
{
"value": "attribute value 2",
"ts": "2014-01-01T01:11:02Z"
},
{
"value": "attribute value 3",
"ts": "2014-01-01T01:22:01Z"
}
]
}
}
}
// "split" response example
{
"cmd": {
"success": true,
"params": {
"values": [
"attribute value 1",
"attribute value 2",
"attribute value 3"
],
"timestamps": [
"2014-01-01T01:01:01Z",
"2014-01-01T01:11:02Z",
"2014-01-01T01:22:01Z"
],
"corrIds": [
"",
"123TestCorrId",
""
]
}
}
}
Response Parameters
The attribute.history response can be either:
- Values array with the following parameters
Name | Type | Description |
---|---|---|
id | String | The id of the attribute (if returnIds is set to true) |
value | Integer | The value for the given timestamp. |
ts | String | Timestamp for the given value. |
corrId | String | The correlation identifier associated with the attribute. |
- Multiple arrays: when the split request parameter is set to true
Name | Type | Description |
---|---|---|
ids | Array | Array of ids (if returnIds is set to true) |
values | Array | Array of values |
timestamps | Array | Array of timestamps |
corrIds | Array | Array of correlation IDs. |
The attribute.history response can also contain the following key:
Name | Type | Description |
---|---|---|
truncated | Boolean | If this value is in the response, it will be true. It is defined if the number of possible records is equal to or greater than the maximum configured. |