You can connect devices to IoT Platform over HTTPS. This topic describes how to connect a device to IoT Platform over HTTPS.

Usage notes and limits

  • You can connect devices to IoT Platform over HTTPS only in the China (Shanghai) region.
  • Short-lived connections over HTTPS between devices and IoT Platform can be established only in the China (Shanghai) region. You can view the status changes of devices with short-lived HTTPS connections in the IoT Platform console when the devices connect to or disconnect from IoT Platform. You can configure an Advanced Message Queuing Protocol (AMQP) server-side subscription to receive messages about device status changes.
  • You can connect only directly connected devices to IoT Platform over HTTPS. You cannot connect gateways or sub-devices to IoT Platform over HTTPS.
  • Connections over HTTPS are used for devices to submit data. A device can submit a maximum of 128 KB of data at a time.
  • HTTPS topics and MQTT topics share the same standards. If you connect a device to IoT Platform over HTTPS, you can use MQTT topics for communication between the device and IoT Platform. When you connect a device to IoT Platform over HTTPS, the device submits data to a topic in the ${endpoint}/topic/${topic} format. The ?query_String=xxx format is not supported.
  • Only the POST request method is supported.
  • The token that is returned during device authentication expires after a specified period. The current validity period is seven days. Make sure that you specify the logic to process expired tokens.

Process

You must authenticate a device to obtain the device token, and then use the token to submit data.

  1. Authenticate the device to obtain the device token.

    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. The following table describes the parameters.
    Parameter Description
    Method The request method. Valid value: POST.
    URL The URL. Only HTTPS is supported. Valid value: /auth.
    Host The endpoint of the public instance or Enterprise Edition instance to which you want to connect your device over HTTP. For more information, see View the endpoint of an instance.
    Content-Type The Multipurpose Internet Mail Extensions (MIME) type of upstream data that the device submits to IoT Platform. Valid value: application/json. If another MIME type is specified, an error occurs.
    Content-Length The length of the HTTP message body.
    Important
    • If you use HTTP/1.1 or later, the Content-Length parameter is carried in the request by default. If you use HTTP/1.0 or earlier, this parameter is not carried in the request by default. If you use the HTTP protocol to authenticate a device, you must specify the Content-Length parameter.
    • The value of Content-Length must be the same as the exact length of the message body. Otherwise, the message body cannot be parsed and the authentication fails.
    body The device information for authentication in JSON format. For more information, see Parameters in the message body.
    Table 2. Parameters in the message body
    Parameter Required Description
    productKey Yes The ProductKey of the product to which the device belongs. You can log on to the IoT Platform console and obtain the ProductKey on the Device Details page of the instance.
    deviceName Yes The DeviceName of the device. You can log on to the IoT Platform console and obtain the DeviceName on the Device Details page of the instance.
    clientId Yes The ID of the client. The client ID must be 1 to 64 characters in length. We recommend that you use the MAC address or SN of the device as the value of the clientId parameter.
    timestamp No The timestamp. A request is valid for 15 minutes after the timestamp is generated. The timestamp is a numeric format in which the value represents the number of milliseconds that have elapsed since 00:00:00 Thursday, January 1, 1970.
    sign Yes The signature.

    The signature is calculated by using the hmacmd5(deviceSecret,content) function.

    The value of content is a string that contains all the parameters that the device submits to IoT Platform, except for the version, sign, and signmethod parameters. The submitted parameters are sorted in alphabetical order and concatenated without concatenation symbols.

    Example:

    If the clientId parameter is set to 127.0.0.1, the deviceName parameter is set to http_test, the productKey parameter is set to a1FHTWxQ****, the timestamp parameter is set to 1567003778853, the signmethod parameter is set to hmacmd5, and the deviceSecret parameter is set to 89VTJylyMRFuy2T3sywQGbm5Hmk1****, use the following function to calculate the signature:

    hmacmd5("89VTJylyMRFuy2T3sywQGbm5Hmk1****","clientId127.0.0.1deviceNamehttp_testproductKeya1FHTWxQ****timestamp1567003778853").toHexString();

    The toHexString() method is used to convert a set of four-bit binary digits that form the binary result into a hexadecimal string. The hexadecimal string is not case-sensitive. For example, an array that includes the result in the decimal format is [60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71]. The array is converted into the following hexadecimal string: 3C44BDF9EF631E4575CAC6C667E97147.

    signmethod No The signature algorithm. Valid values: hmacmd5 and hmacsha1.

    Default value: hmacmd5.

    version No The version number. Default value: default.

    Sample response: 

    body:
{
  "code": 0,
  "message": "success",
  "info": {
    "token":  "6944e5bfb92e4d4ea3918d1eda39****"
  }
}
    Note
    • You must cache the returned token on the device.
    • The token is required each time the device submits data to IoT Platform. If the token expires, you must re-authenticate the device to obtain another token.
    Table 3. Error codes
    code message Description
    10000 common error The error message returned because an unknown error has occurred.
    10001 param error The error message returned because one or more parameters are invalid.
    20000 auth check error The error message returned because the device failed to be authenticated.
    20004 update session error The error message returned because the device failed to be updated.
    40000 request too many The error message returned because the number of requests that IoT Platform can process exceeds the throttling threshold.
  2. Submit data.

    The device sends data only to a topic on which the device has the Publish permission. Custom topics can be used.

    For example, the topic is /${YourProductKey}/${YourDeviceName}/pub, the DeviceName is device123, and the ProductKey is a1GFjLP****. You can use the https://iot-as-http.cn-shanghai.aliyuncs.com/topic/a1GFjLP****/device123/pub URL to submit data.

    Sample request:

    POST /topic/${topic} HTTP/1.1
Host: ${YourEndpoint}
password:${token}
Content-Type: application/octet-stream
Content-Length: 53
body: ${your_data}
    Table 4. Parameters
    Parameter Description
    Method The request method. Valid value: POST.
    URL /topic/${topic}. Replace the ${topic} variable with the topic to which data is sent. Only HTTPS is supported.
    Host The endpoint.
    password This parameter is included in the request header. Set this parameter to the token that is returned after you call the auth operation to authenticate the device.
    Content-Type The MIME type of upstream data that the device submits to IoT Platform. Valid value: application/octet-stream. If another MIME type is specified, an error occurs.
    Content-Length The length of the HTTP message body.
    body The data that is sent to the specified topic. For more information about data formats, see Topics.

    Sample response: 

    body:
{
  "code": 0,
  "message": "success",
  "info": {
    "messageId": 892687****47040
  }
}
    Table 5. Error codes
    code message Description
    10000 common error The error message returned because an unknown error has occurred.
    10001 param error The error message returned because one or more parameters are invalid.
    20001 token is expired The error message returned because the token has expired. You must call the auth operation to re-authenticate the device and obtain a new token.
    20002 token is null The error message returned because no token is specified in the request header.
    20003 check token error The error message returned because IoT Platform failed to obtain the device identity information based on the token. You must call the auth operation to re-authenticate the device and obtain a new token.
    30001 publish message error The error message returned because the device failed to submit data.
    40000 request too many The error message returned because the number of requests that IoT Platform can process exceeds the throttling threshold.

Sample value

For information about how to connect an HTTP client with IoT Platform, see Access IoT Platform by using HTTP.