HTTPS Access_IoT Device Access

Overview

Hypertext Transfer Protocol Secure (HTTPS) is a secure communication protocol based on HTTP and encrypted using SSL. IoTDA supports communication through HTTPS.

Constraints

Description	Limit
Supported HTTP version	HTTP 1.0 HTTP 1.1
Supported HTTPS	The platform supports only the HTTPS protocol. For details about how to download a certificate, see Certificates.
Supported TLS version	TLS 1.2
Body length	1 MB
API specifications	Specifications
Number of child devices of which properties can be reported by a gateway at a time	50

API Calling

For details about the platform endpoint, see Platform Connection Information.

NOTE:

Use the endpoint of IoTDA and the HTTPS port number 443.

Communication Between HTTPS Devices and the Platform

When a device connects to the platform through HTTPS, HTTPS APIs are used for their communication. These APIs can be used for device authentication as well as message and property reporting.

Message Type	Description
Device authentication	Devices obtain access tokens.
Device reporting properties	Devices report property data to IoTDA in the format defined in the product model.
Device reporting messages	Devices report custom data to IoTDA, which then forwards reported messages to an application or other Huawei Cloud services for storage and processing.
Gateway reporting device properties in batches	A gateway reports property data of multiple child devices to the platform.

Service Flow

Create a product on the IoTDA console or by calling the API for creating a product.
Register a device on the IoTDA console or calling the API for creating a device.
Call the device authentication API to obtain the access token of the device.

Figure 1 Obtaining the access token
The obtained access token can be used by devices to report messages and properties. The access token is in the message header. The following uses property reporting as an example.

Figure 2 Reporting properties

Figure 3 Reporting properties

HTTP APIs

The following table describes the platform APIs.

API Category	API	API	Description
Device authentication API	Device Authentication API	/v5/device-auth	This API is used to authenticate a device. Connections can be established between devices and IoTDA after successful authentication. After the authentication is successful, IoTDA returns an access token. An access token is required when APIs for property reporting and message reporting are called. If an access token expires, you need to authenticate the device again to obtain an access token. If you obtain a new access token before the old one expires, the old access token will be valid for 30 seconds before expiration.
Device message reporting API	Device Message Reporting	/v5/devices/{device_id}/sys/messages/up	This API is used by a device to report custom data to IoTDA, which then forwards reported messages to an application or other Huawei Cloud services for storage and processing.
Device property reporting APIs	Device Property Reporting	/v5/devices/{device_id}/sys/properties/report	This API is used by a device to report property data in the format defined in the product model to IoTDA.
Device property reporting APIs	Gateway Reporting Child Device Property	/v5/devices/{device_id}/sys/gateway/sub-devices/properties/report	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.

Device Authentication API

This API is used to authenticate a device. After successful authentication, connections can be established between devices and IoTDA, and the platform returns an access token. The access token is required when APIs for property reporting and message reporting are called. If an access token expires, you need to authenticate the device again to obtain an access token. If you obtain a new access token before the old one expires, the old access token will be valid for 30 seconds before expiration.

Request Method	POST
URI	/v5/device-auth
Transport Protocol	HTTPS

Parameter	Mandatory	Type	Location	Description
device_id	Yes	String	Body	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]. The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Value length: 1 to 128 characters
sign_type	Yes	Integer	Body	Password verification mode. 0: When the timestamp is verified using the HMAC-SHA256 algorithm, IoTDA does not check whether the message timestamp is consistent with the IoTDA time but only checks whether the password is correct. 1: When the timestamp is verified using the HMAC-SHA256 algorithm, IoTDA checks whether the message timestamp is consistent with the IoTDA time and then checks whether the password is correct. Value range: 0 to 1
timestamp	Yes	String	Body	The timestamp is the UTC time when the device was connected to IoTDA, in the format of YYYYMMDDHH. For example, if the UTC time is 2018/7/24 17:56:20, the timestamp is 2018072417. Value length: a fixed length of 10 characters
password	Yes	String	Body	The value of this parameter is the value of the device secret signed by using the HMAC-SHA256 algorithm with the timestamp as the key. For details, see the secret generation tool. The device secret is returned by IoTDA upon successful device registration. Value length: a fixed length of 64 characters

Parameter	Type	Description
access_token	String	Device token, which is used for device authentication. Value length: 32 to 256 characters
expires_in	Integer	Remaining validity period of the authentication information, in seconds.

Parameter

Type

Description

access_token

String

Device token, which is used for device authentication.

Value length: 32 to 256 characters

expires_in

Integer

Remaining validity period of the authentication information, in seconds.

Request example:

POST https://{endpoint}/v5/device-auth
Content-Type: application/json

{
  "device_id" : "********",
  "sign_type" : 0,
  "timestamp" : "2019120219",
  "password" : "********"
}

Response example:

Status Code: 200 OK

Content-Type: application/json

{
  "access_token" : "********",
  "expires_in" : 86399
}

HTTP Status Code	Description	Error Code	Error Message	Error Description
200	OK	-	-	-
400	Bad Request	IOTDA.000006	Invalid input data.	Invalid request parameters.
401	Unauthorized	IOTDA.000002	Authentication failed.	Authentication failed.
403	Forbidden	IOTDA.021101	Request reached the maximum rate limit.	The request frequency has reached the upper limit.
403	Forbidden	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.

Device Message Reporting

This API is used by a device to report custom data to IoTDA, which then forwards reported messages to an application or other Huawei Cloud services for storage and processing.

Request Method	POST
URI	/v5/devices/{device_id}/sys/messages/up
Transport Protocol	HTTPS

Parameter	Mandatory	Type	Location	Description
access_token	Yes	String	Header	Access token returned after the device authentication API is called. Value length: 1 to 256 characters
device_id	Yes	String	Path	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]. The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Value length: 1 to 128 characters

Parameter

Mandatory

Type

Location

Description

access_token

Yes

String

Header

Access token returned after the device authentication API is called.

Value length: 1 to 256 characters

device_id

Yes

String

Path

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].

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

Value length: 1 to 128 characters

NOTE:

This API allows a device to use a request body to report custom data to IoTDA, which then forwards the body content to applications or other Huawei Cloud services for storage and processing. IoTDA has no specific format requirements on the body content. This API can carry data whose size is smaller than 1 MB.

Request example:

POST https://{endpoint}/v5/devices/{device_id}/sys/messages/up
Content-Type: application/json
access_token: ********
{
  "name" : "name",
  "id" : "id",
  "content" : "messageUp"
}

Response example:

Status Code: 200 ok

HTTP Status Code	Description	Error Code	Error Message	Error Description
200	OK	-	-	-
400	Bad Request	IOTDA.000006	Invalid input data.	Invalid request parameters.
401	Unauthorized	IOTDA.000002	Authentication failed.	Authentication failed.
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.

Device Property Reporting

This API is used by a device to report property data in the format defined in the product model to IoTDA.

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

Parameter	Mandatory	Type	Location	Description
access_token	Yes	String	Header	Access token returned after the device authentication API is called. Value length: 1 to 256 characters
device_id	Yes	String	Path	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]. The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Value length: 1 to 128 characters
services	Yes	List<Table 1>	Body	Device service data list.

Parameter

Mandatory

Type

Location

Description

access_token

Yes

String

Header

Access token returned after the device authentication API is called.

Value length: 1 to 256 characters

device_id

Yes

String

Path

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].

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

Value length: 1 to 128 characters

services

Yes

List<Table 1>

Body

Device service data list.

**Table 1** ServiceProperty
Parameter	Mandatory	Type	Description
service_id	Yes	String	Service ID of the device.
properties	Yes	Object	Service properties, which are defined in the product model of the device.
event_time	No	String	UTC time when the device collects data. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. If this parameter is not carried in the reported data or is in an incorrect format, the time when IoTDA receives the data is used.

Example request:

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

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

Response example:

If the status code is 200, reporting is successful.

HTTP Status Code	Description	Error Code	Error Message	Error Description
200	OK	-	-	-
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.021105	The content reported in a single request cannot exceed 1 MB.	The content reported in a single request cannot exceed 1 MB.

Gateway Reporting Child Device Property

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.

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

Parameter	Mandatory	Type	Location	Description
access_token	Yes	String	Header	Access token returned after the device authentication API is called. Value length: 1 to 256 characters
device_id	Yes	String	Path	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]. The value is a string of no more than 128 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Value length: 1 to 128 characters
devices	Yes	List<Table 2>	Body	Device data list. Value length: 50 characters at most

Parameter

Mandatory

Type

Location

Description

access_token

Yes

String

Header

Access token returned after the device authentication API is called.

Value length: 1 to 256 characters

device_id

Yes

String

Path

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].

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

Value length: 1 to 128 characters

devices

Yes

List<Table 2>

Body

Device data list.

Value length: 50 characters at most

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

**Table 3** ServiceProperty
Parameter	Mandatory	Type	Description
service_id	Yes	String	Service ID of the device.
properties	Yes	Object	Service properties, which are defined in the product model of the device.
event_time	No	String	UTC time when the device collects data. The value is in the format of yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. If this parameter is not carried in the reported data or is in an incorrect format, the time when IoTDA receives the data is used.

An example request is as follows:

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"
    } ]
  } ]
}

Response example:

If the status code is 200, reporting is successful.

HTTP Status Code	Description	Error Code	Error Message	Error Description
200	OK	-	-	-
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.
401	Unauthorized	IOTDA.000002	Authentication failed.	Authentication failed.
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 number of child devices in the request has reached the upper 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.

HTTPS Access

Overview

Constraints

API Calling

Communication Between HTTPS Devices and the Platform

Service Flow

HTTP APIs

Device Authentication API

Device Message Reporting

Device Property Reporting

Gateway Reporting Child Device Property

Feedback

Was this page helpful?

Feedback