attribute.history

Attribute history can be requested by specifying on eof the following:

A definite time period using a start and end date
A time period defined by the "last period of time style query for example, "last":"24h"
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
	Thing Identifier Parameters		Identifies the thing to which the attribute data is to be associated. If omitted, the thingKey associated with your session is used. See Thing Identifier Parameters table below for supported parameters.
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.
limit	Integer		Limit the number of results returned. Defaults to the configured maximum limit.
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.

Thing Identifier Parameters


Name	Type	Description
thingKey	String	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

TR50 Response

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 by Device Cloud. In cases where your selection has more results than the limit of Device 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 one of the following:

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.

Two arrays: values & timestamps 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.