Gateway Reporting Child Device Properties

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

View PDF

Function

This API is used to report device data in batches to IoTDA. A gateway can use this API to report the property data of a maximum of 50 child devices at the same time.

URI

Request Method	POST
URI	/v5/devices/{device_id}/sys/gateway/sub-devices/properties/report
Transport Protocol	HTTPS

Request Parameters

Parameter	Mandatory	Type	Location	Description
access_token	Yes	String	Header	Explanation: Access token returned after the device authentication API is called. Value range: 1–256 characters.
device_id	Yes	String	Path	Explanation: Device ID, which uniquely identifies a device. The value of this parameter is specified during device registration or allocated by IoTDA. If the value is allocated by the platform, the value is in the format of [product_id]_[node_id]. Value range: The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
devices	Yes	List<DeviceProperty>	Body	Explanation: Device data list. Value range: Max. 50 characters.

Parameter

Mandatory

Type

Location

Description

access_token

Yes

String

Header

Explanation:

Access token returned after the device authentication API is called.

Value range:

1–256 characters.

device_id

Yes

String

Path

Explanation:

Device ID, which uniquely identifies a device. The value of this parameter is specified during device registration or allocated by IoTDA. If the value is allocated by the platform, the value is in the format of [product_id]_[node_id].

Value range:

The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.

devices

Yes

List<DeviceProperty>

Body

Explanation:

Device data list.

Value range:

Max. 50 characters.

**Table 1** DeviceProperty
Parameter	Mandatory	Type	Description
device_id	Yes	String	Explanation: ID of the child device, which is unique and is allocated by IoTDA during device registration. Value range: The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed.
services	Yes	List<ServiceProperty>	Explanation: List of device services.

**Table 2** ServiceProperty
Parameter	Mandatory	Type	Description
service_id	Yes	String	Explanation: Device service ID.
properties	Yes	Object	Explanation: Service properties, which are defined in the product model of the device.
event_time	No	String	Explanation: UTC time when the device collects data. The format is yyyy-MM-dd'T'HH:mm:ss.SSS'Z', for example, 2021-08-13T10:10:10.555Z. If the data reported by a device does not contain this parameter or the parameter format is incorrect, the data reporting time is the platform time. The format is yyyyMMdd'T'HHmmss'Z', for example, 20230523T014506Z.

Example Request

POST https://{endpoint}/v5/devices/{device_id}/sys/gateway/sub-devices/properties/report
Content-Type: application/json
access_token: ******

{
  "devices" : [ {
    "device_id" : "deviceId_0001",
    "services" : [ {
      "service_id" : "serviceId",
      "properties" : {
        "Height" : 124,
        "Speed" : 23.24
      },
      "event_time" : "2021-08-13T10:10:10.555Z"
    } ]
  }, {
    "device_id" : "deviceId_0002",
    "services" : [ {
      "service_id" : "serviceId",
      "properties" : {
        "Height" : 124,
        "Speed" : 23.24
      },
      "event_time" : "2021-08-13T10:10:10.555Z"
    } ]
  } ]
}

Example Response

If the status code is 200, reporting is successful.

Error Code

HTTP Status Code	HTTP Status Code Description	Error Code	Error Message	Error Description
400	Bad Request	IOTDA.000006	Invalid input data.	Invalid request parameters.
400	Bad Request	IOTDA.021104	Subdevices in the request does not exist or does not belong to the gateway.	Some child devices in the request do not exist or do not belong to the gateway.
403	Forbidden	IOTDA.000004	Invalid access token.	Invalid token.
		IOTDA.021101	Request reached the maximum rate limit.	The request frequency has reached the upper limit.
		IOTDA.021102	The request rate has reached the upper limit of the tenant, limit %s.	The request frequency has reached the upper limit of the tenant.
		IOTDA.021103	The request batch properties number has reached the upper limit, limit %s.	The number of child devices in the request reaches the upper limit.
		IOTDA.021105	The content reported in a single request cannot exceed 1 MB.	The content reported in a single request cannot exceed 1 MB.