On this page

Show all

Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Device Properties/ Platform Querying Device Properties

Platform Querying Device Properties

Updated on 2024-12-02 GMT+08:00

View PDF

Function

This API is used by the platform to query property information from a device. For details of the API, see Query Device Properties. When a device receives a property query request, the device needs to return its property data to the platform. Otherwise, the request is considered to have timed out by the platform.

NOTE:

It is not suitable to report data in JSON format for devices with low configuration and limited resources or with limits on bandwidth usage. In this case, devices can transparently transmit the original binary data to the platform, but a codec is required to convert binary data to JSON format. For details about how to develop codecs, see Developing a Codec.

Topic

Downstream: $oc/devices/{device_id}/sys/properties/get/request_id={request_id}

Upstream: $oc/devices/{device_id}/sys/properties/get/response/request_id={request_id}

NOTE:

{request_id} is used to uniquely identify a request. If a device receives a downstream request with a topic carrying a request ID, the request ID must be included in the topic of the upstream response returned by the device.
When an application queries device properties, the platform generates a unique ID to identify the request. This ID is carried in request_id in the downstream topic of the platform-side device property query.
The device cannot detect the request_id in advance. When a device subscribes to a topic that ends with request_id={request_id}, the number sign (#) can be used to replaced request_id={request_id}, for example, $oc/devices/{device_id}/sys/properties/get/#.

Downstream Request Parameters

Parameter	Mandatory/Optional	Type	Description
object_device_id	Optional	String	Explanation: For directly connected device: This parameter is not carried. For gateway child device: The value is the child device ID in the topic.
service_id	Optional	String	Explanation: Service ID of the device, which is determined by the product model.

Parameter

Mandatory/Optional

Type

Description

object_device_id

Optional

String

Explanation:

For directly connected device: This parameter is not carried.
For gateway child device: The value is the child device ID in the topic.

service_id

Optional

String

Explanation:

Service ID of the device, which is determined by the product model.

Upstream Response Parameters

Parameter	Mandatory/Optional	Type	Description
services	Optional	List<ServiceProperty>	Explanation: Indicates a list of device services.

Parameter

Mandatory/Optional

Type

Description

services

Optional

List<ServiceProperty>

Explanation:

Indicates a list of device services.

ServiceProperty structure

Parameter	Mandatory/Optional	Type	Description
service_id	Mandatory	String	Explanation: Service ID of the device, which is determined by the product model.
properties	Mandatory	Object	Explanation: Indicates the property list of the device service. Multiple property parameters can be defined in the product model associated with the device.
event_time	Optional	String	Explanation: Indicates the UTC time when the device collects data. The format is yyyyMMdd'T'HHmmss'Z', for example, 20161219T114920Z. If this parameter is not carried in the reported data or is in incorrect format, the time when the platform receives the data is used.

Parameter

Mandatory/Optional

Type

Description

service_id

Mandatory

String

Explanation:

Service ID of the device, which is determined by the product model.

properties

Mandatory

Object

Explanation:

Indicates the property list of the device service. Multiple property parameters can be defined in the product model associated with the device.

event_time

Optional

String

Explanation:

Indicates the UTC time when the device collects data. The format is yyyyMMdd'T'HHmmss'Z', for example, 20161219T114920Z.

If this parameter is not carried in the reported data or is in incorrect format, the time when the platform receives the data is used.

Example Downstream Request

Topic: $oc/devices/{device_id}/sys/properties/get/request_id={request_id} 
Data format:
{
    "object_device_id": "{object_device_id}"
    "service_id": "Temperature"
}

Example Upstream Response

Topic: $oc/devices/{device_id}/sys/properties/get/response/request_id={request_id}
Data format:
{
    "services": [
        {
            "service_id": "Temperature",
            "properties": {
                "PhV_phsA": "1",
                "PhV_phsB": "2"
            },
            "event_time": "20190606T121212Z"
        }
    ]
}

Parent topic: Device Properties

Previous topic: Platform Setting Device Properties

Next topic: Device Obtaining Device Shadow Data from the Platform