Queries multiple properties that are submitted by a device within a specified period.

Limits

  • A maximum of 10 properties can be queried at a time. A maximum of 100 records can be queried for each property.
  • You can query property data that is generated within the last 30 days.
    Note The storage period of a property record is calculated from the day when the property record was generated.
  • Each Alibaba Cloud account can run a maximum of 10 queries per second (QPS).
    Note RAM users of an Alibaba Cloud account share the quota of the account.

Usage notes

When you call this operation to query property records within a specified period, the number of records for a property at a point in time may reach the limit. The limit is specified by the PageSize parameter. In this case, the query stops. Some records of other properties may be not returned. You can check whether all records of a property are returned based on the NextValid repsonse parameter:

  • If the value of the NextValid parameter is true, unretrieved records exist in the period that is indicated by the NextTime and EndTime parameter.

    You can use the value of the NextTime response parameter as the value of the StartTime request parameter and call this operation again to query the rest records. You can call this operation multiple times until the value of the NextValid parameter is false.
    Note To retrieve all property records within a specified period, you can set the PageSize parameter to the maximum value. Then, call this operation multiple times until the value of the NextValid parameter is false.
  • If the value of the NextValid parameter is false, all property records are returned.

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 QueryDevicePropertiesData

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

Asc Integer Yes 0

The sorting order of the returned property records. Valid values:

  • 0: in reverse chronological order. In this case, the time that is specified by the StartTime parameter must be later than the time that is specified by the EndTime parameter.
  • 1: in chronological order. In this case, the time that is specified by the StartTime parameter must be earlier than the time that is specified by the EndTime parameter.
DeviceName String Yes airconditioning

The DeviceName of the device.

EndTime Long Yes 1579249499000

The end of the time range to query. The value is a 13-digit timestamp in milliseconds, for example 1579249499000.

Identifier.N RepeatList Yes temperature

The identifiers of the properties.

The property identifiers must be unique.

You can view the property identifiers in the IoT Platform console. Go to the Define Feature tab of the Product Details page. You can also call the QueryThingModel operation and view the property identifiers in the returned TSL data.

Note If a property named temperature belongs to a custom module named testFb, set this pararmeter to testFb:temperature. The custom module is not the default module.
PageSize Integer Yes 10

The maximum number of records that is returned for each property. Maximum value: 100.

The number of records that are returned for an arbitrary property cannot exceed the limit.

ProductKey String Yes a1BwAGV****

The ProductKey of the product to which the device belongs.

StartTime Long Yes 1579249499000

The start of the time range to query. The value is a 13-digit timestamp in milliseconds, for example, 1579249499000.

IotInstanceId String No iot_instc_pu****_c*-v64********

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

Notice
  • If your instance has an ID, you must configure this parameter. If you do not set this parameter, the call fails.
  • If your instance has no Overview page or ID, you do not need to set this parameter.

For more information, see Overview.

IotId String No Q7uOhVRdZRRlDnTLv****00100

The ID of the device. The device ID is issued by IoT Platform.

Note The IotId parameter is a globally unique identifier (GUID), and corresponds to a combination of the ProductKey and DeviceName parameters. If you specify the IotId parameter and a combination of the ProductKey and DeviceName parameters at the same time, the IotId parameter is used.

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 request parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

ErrorMessage String A system exception occurred.

The error message returned if the call fails.

NextTime Long 1579249499000

The start time to query on the next page.

You can use the value of the NextTime parameter as the value of the StartTime parameter when you query the next page of results.

NextValid Boolean true

Indicates whether the next page exists.

  • true: The next page exists.
  • false: The next page does not exist.

If the return value of the NextValid parameter is true, you can use the value of the NextTime parameter as the value of the StartTime parameter when you query the next page of results.

PropertyDataInfos Array of PropertyDataInfo

The list of property records returned if the call is successful. For more information, see PropertyDataInfo.

PropertyDataInfo
Identifier String temperature

The identifier of the property.

List Array of PropertyInfo

The list of property records.

PropertyInfo
Time Long 1579249499000

The time when the property was submitted. The value is a timestamp in milliseconds, such as 1579249499000.

Value String 21.3

The value of the property.

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

The ID of the request.

Success Boolean true

Indicates whether the call was successful.

  • true: The call was successful.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=QueryDevicePropertiesData
&Asc=0
&DeviceName=water
&EndTime=1540115948152
&Identifier.1=Temperature
&Identifier.2=Humidity
&PageSize=100
&ProductKey=a1bd***
&StartTime=1540116010723
&<Common request parameters>

Sample success responses

XML format

<QueryDevicePropertiesData>
  <NextValid>false</NextValid>
  <RequestId>CC4CAC00-ED4C-4004-9E8D-E8B4A78552FA</RequestId>
  <PropertyDataInfos>
        <PropertyDataInfo>
              <List>
                    <PropertyInfo>
                          <Value>32.46</Value>
                          <Time>1579249151178</Time>
                    </PropertyInfo>
              </List>
              <Identifier>Temperature</Identifier>
        </PropertyDataInfo>
        <PropertyDataInfo>
              <List>
                    <PropertyInfo>
                          <Value>48</Value>
                          <Time>1579249151178</Time>
                    </PropertyInfo>
              </List>
              <Identifier>Humidity</Identifier>
        </PropertyDataInfo>
  </PropertyDataInfos>
  <Success>true</Success>
</QueryDevicePropertiesData>

JSON format

{
  "NextValid": false, 
  "RequestId": "CC4CAC00-ED4C-4004-9E8D-E8B4A78552FA", 
  "PropertyDataInfos": {
    "PropertyDataInfo": [
      {
        "List": {
          "PropertyInfo": [
            {
              "Value": "32.46", 
              "Time": 1579249151178
            }
          ]
        }, 
        "Identifier": "Temperature"
      }, 
      {
        "List": {
          "PropertyInfo": [
            {
              "Value": "48", 
              "Time": 1579249151178
            }
          ]
        }, 
        "Identifier": "Humidity"
      }
    ]
  }, 
  "Success": true
}

Error codes

For a list of error codes, visit the API Error Center.