All Products
Search
Document Center

IoT Platform:QueryDevicesHotStorageData

Last Updated:Oct 20, 2023

Queries time series data.

Usage notes

The QueryDevicesHotStorageData operation is available only for Standard and Exclusive Enterprise Edition instances.

Limits

  • The volume of data that you can read per second from the time series data storage of an Enterprise Edition instance by calling this operation varies based on the value that you specified for the Time-series Data Storage IOPS parameter when you purchased the instance. For more information, see Purchase Enterprise Edition instances.

  • You can call the QueryDevicesHotStorageData operation to query the data that has not expired.

    Note

    The retention period of the data of a field starts from the day of the timestamp of the field value.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter

Type

Required

Example

Description

Action

String

Yes

QueryDevicesHotStorageData

The operation that you want to perform. Set the value to QueryDevicesHotStorageData.

Asc

Integer

Yes

0

The order in which you want to sort the returned data records. Valid values:

  • 0: reverse chronological order.

  • 1: chronological order.

EndTime

Long

Yes

1579249499000

The end of the time range to query. The end time must be later than the start time. Specify a UNIX timestamp representing the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC. Example: 1579249499000.

Identifier

String

Yes

temperature

The identifier of the field that is stored in time series data storage. The identifier is specified by Items when you call the WriteDevicesHotStorageData operation to write data to time series data storage.

IotInstanceId

String

Yes

iot-2w****

The instance ID. You can view the instance ID on the Overview page in the IoT Platform console.

PageSize

Integer

Yes

10

The number of entries per page. Valid values: 1 to 100.

The number of data records returned for a field cannot exceed this value.

StartTime

Long

Yes

1579249499000

The beginning of the time range to query. The start time must be earlier than the end time. Specify a UNIX timestamp representing the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC. Example: 1579249499000.

UserTopic

String

Yes

user/a***/b***

The name of the custom topic to which the data that you want to query belongs. Specify other levels that are required by the custom topic after the user level.

For more information, see Use custom topics.

ProductKey

String

No

a1BwAGV****

The ProductKey of the product to which the device belongs.

Important

If you specify this parameter, you must also specify DeviceName.

DeviceName

String

No

device1

The DeviceName of the device.

Important

If you specify this parameter, you must also specify ProductKey.

NextPageToken

String

No

Bo***x44Qx

The pagination token that is used in the next request to retrieve a new page of results. You do not need to specify this parameter for the first request. You must specify the token that is obtained from the previous query as the value of NextPageToken.

IotId

String

No

y4u2weAI********HMle1234

The device ID.

Important

IotId specifies a GUID for the device. The value of IotId is equivalent to the combination of the values of ProductKey and DeviceName. If you specify this parameter, you do not need to specify ProductKey or DeviceName. If you specify IotId, ProductKey, and DeviceName, the value of IotId takes precedence.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information, see Common parameters.

Response parameters

Parameter

Type

Example

Description

Code

String

iot.system.SystemException

The error code returned if the request failed. For more information, see the Error codes section of this topic.

Data

Struct

The data returned if the request was successful.

List

Array of PropertyInfo

The queried time series data.

PropertyInfo

Time

String

1516541885630

The timestamp of the field value. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC.

Value

String

2

The field value.

NextValid

Boolean

true

Indicates whether the next page exists. Valid values:

  • true

  • false

If true is returned for NextValid, you can specify the value of NextPageToken returned in the response as the value of NextPageToken in the next request. This way, you can query the data that is not included in the current query.

nextPageToken

String

Bo***x44Qx

A pagination token. It can be used in the next request to retrieve a new page of results.

ErrorMessage

String

A system exception occurred.

The error message returned if the request failed.

RequestId

String

E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565

The request ID.

Success

Boolean

true

Indicates whether the request was successful. Valid values:

  • true

  • false

Examples

Sample requests

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=QueryDevicesHotStorageData
&Asc=0
&EndTime=1579249499000
&Identifier=temperature
&IotInstanceId=iot-2w****
&PageSize=10
&StartTime=1579249499000
&UserTopic=user/a***/b***
$ProductKey=a1BwAGV****
$DeviceName=device1
&<Common request parameters>

Sample success responses

XML format

<QueryDevicesHotStorageDataResponse>
  <RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
  <Data>
        <NextValid>true</NextValid>
        <nextPageToken>Bo***x44Qx</nextPageToken>
        <List>
              <PropertyInfo>
                    <Value>2</Value>
                    <Time>1516541885630</Time>
              </PropertyInfo>
        </List>
  </Data>
  <Success>true</Success>
</QueryDevicesHotStorageDataResponse>

JSON format

{
    "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
    "Data": {
        "NextValid": true,
        "nextPageToken": "Bo***x44Qx",
        "List": {
            "PropertyInfo": [{
                "Value": 2,
                "Time": 1516541885630
            }]
        }
    },
    "Success": true
}

Error codes

HTTP status code

Error code

Error message

Description

400

iot.device.InvalidTimeBucket

The specified time range is invalid.

The specified time range is invalid.

400

iot.device.NullDeviceName

The DeviceName parameter cannot be empty.

DeviceName is not specified.

400

iot.prod.NullProductKey

The ProductKey parameter cannot be empty.

ProductKey is not specified.

400

iot.common.InvalidPageParams

The specified pagination size or pagination parameter is invalid.

The specified page size or page number is invalid.

400

iot.prod.NotExistedProduct

The specified product does not exist.

The product that you specify does not exist.

400

iot.device.PageTokenIsIllegal

The paging token is invalid.

The value of NextPageToken is invalid.

400

Iot.Device.NotExistedDevice

The device does not exist.

The device does not exist or is not activated.

400

iot.device.InvalidFormattedDeviceName

The DeviceName format is invalid.

The format of DeviceName is invalid.

400

iot.prod.InvalidFormattedProductkey

The ProductKey format is invalid.

The format of ProductKey is invalid.

400

iot.system.IllegalRequest

The request parameter is invalid.

One or more request parameters are invalid.

400

iot.device.InvalidIoTId

The specified device ID is invalid.

The device ID is invalid.

400

iot.storage.HotStorageIopsReadNotEnough

The timeline storage read IOPS is not enough.

The read IOPS of time series data storage is insufficient.

For a list of error codes, see Service error codes.