HTTPS device connection and data reporting - IoT Platform - IoT Platform

Usage and limits

HTTPS communication is supported only in the China (Shanghai) regions.
Only the China (Shanghai) region supports short-lived HTTPS connections. Device online and offline statuses are visible in the IoT Platform console. Subscribe to device status changes through AMQP server-side subscriptions.
Only directly connected devices can communicate over HTTPS. Gateway devices and sub-devices are not supported.
Designed for simple data reporting. The data uplink payload is limited to 128 KB.
Topics follow the MQTT topic format and can be reused from MQTT connections. To report data, send a POST request to ${endpoint}/topic/${topic}. Query string parameters (?query_String=xxx) are not supported.
HTTPS connections support only the POST request method.
The authentication token is valid for seven days. Your application must handle token expiry and re-authentication.

Connection flow

The connection flow has two steps: authenticate the device to obtain a token, then use the token to report data.

Authenticate the device to obtain a token.

Device authentication request:

POST /auth HTTP/1.1
Host: ${YourEndpoint}
Content-Type: application/json
Content-Length: 214
body: {"version":"default","clientId":"mylight1000002","signmethod":"hmacsha1","sign":"4870141D4067227128CBB4377906C3731CAC221C","productKey":"ZG1EvTE****","deviceName":"NlwaSPXsCpTQuh8FxBGH","timestamp":"1501668289957"}

Table 1. Parameter description
Parameter	Description
Method	Request method. Only POST is supported.
URL	URL. HTTPS only. Value: /auth.
Host	The HTTP endpoint. Obtain the endpoint from View and configure instance endpoints.
Content-Type	Data encoding format. Only application/json is supported. Other formats return a parameter error.
Content-Length	The length of the HTTP message body. Important HTTP/1.1+ includes Content-Length by default; HTTP/1.0 does not. Include the Content-Length field when authenticating over HTTP. The Content-Length value must exactly match the body length. A mismatch causes the body to fail parsing and authentication to fail.
body	The device authentication information in JSON format. Parameters are described in the body parameters table.

Table 2. body parameters
Field name	Required	Description
productKey	Yes	The device's ProductKey. Find it on the Device Details page in the corresponding instance.
deviceName	Yes	The device name. Find it on the Device Details page in the IoT Platform console.
clientId	Yes	The client ID. Maximum 64 characters. Use a MAC address or serial number (SN) as the clientId.
timestamp	No	The timestamp in milliseconds since January 1, 1970 (UTC). The request expires 15 minutes after this timestamp.
sign	Yes	The signature. Signature format: `hmacmd5(DeviceSecret,content)`. content is all parameters (except version, sign, and signmethod) sorted alphabetically and concatenated without delimiters. Signature example: Given clientId = 127.0.0.1, deviceName = http_test, productKey = a1FHTWxQ**, timestamp = 1567003778853, signmethod = hmacmd5, deviceSecret = 89VTJylyMRFuy2T3sywQGbm5Hmk1, the signature is: `hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1","clientId127.0.0.1deviceNamehttp_testproductKeya1FHTWxQ**timestamp1567003778853").toHexString();` The `toHexString()` function converts binary data to a case-insensitive hexadecimal string. For example, the decimal array [60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71] converts to: 3C44BDF9EF631E4575CAC6C667E97147.
signmethod	No	The signing algorithm. Valid values: hmacmd5, hmacsha1. Default: hmacmd5.
version	No	The version number. Default: default.

Successful authentication response:

body:
{
  "code": 0,
  "message": "success",
  "info": {
    "token":  "6944e5bfb92e4d4ea3918d1eda39****"
  }
}

Note

Cache the returned token locally.
Include the token in each data reporting request. If the token expires, re-authenticate to obtain a new token.

Table 3. Error codes
code	message	Remarks
10000	common error	Unknown error.
10001	param error	The request parameters are invalid.
20000	auth check error	Device authentication failed.
20004	update session error	The update failed.
40000	request too many	The number of requests exceeds the limit. Throttling is triggered.

Report data.

Devices send data to topics with Publish permission. Custom topics are supported.

For example, if the topic is /${YourProductKey}/${YourDeviceName}/pub, the device name is device123, and the ProductKey of the product is a1GFjLP****, you can call the https://iot-as-http.cn-shanghai.aliyuncs.com/topic/a1GFjLP****/device123/pub URL to report data.

Data reporting request:

POST /topic/${topic} HTTP/1.1
Host: ${YourEndpoint}
password:${token}
Content-Type: application/octet-stream
Content-Length: 53
body: ${your_data}

Table 4. Data reporting parameters
Parameter	Description
Method	Request method. Only POST is supported.
URL	`/topic/${topic}`. Replace `${topic}` with the destination topic. HTTPS only.
Host	The endpoint address.
password	Header parameter. Set to the token returned by the auth operation.
Content-Type	Data encoding format. Only application/octet-stream is supported. Other formats return a parameter error.
Content-Length	The length of the HTTP message entity.
body	The data to send to ${topic}.

Successful response:

body:
{
  "code": 0,
  "message": "success",
  "info": {
    "messageId": 892687****47040
  }
}

Table 5. Error codes
code	message	Remarks
10000	common error	Unknown error.
10001	param error	The request parameters are invalid.
20001	token is expired	The token has expired. Call the auth operation again to obtain a new token.
20002	token is null	The token is not found in the request header.
20003	check token error	Failed to retrieve identity information from the token. Call the auth operation again to obtain a new token.
30001	publish message error	Failed to report data.
40000	request too many	The number of requests exceeds the limit. Throttling is triggered.

Examples

To connect an HTTP client to IoT Platform, follow the steps in Connect an HTTP client.