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

Limits

  • You can establish connections over HTTPS only in the China (Shanghai) region.
  • Connections over HTTPS are used for devices to submit data. A device can submit a maximum of 128 KB at a time.
  • The standards of HTTPS topics and MQTT topics are the same. If you connect a device to IoT Platform over HTTPS, you can use MQTT topics for message 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. You cannot specify a parameter by using the ?query_String=xxx format.
  • 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.

Procedure

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: 192
    body: {"version":"default","clientId":"mylight1000002","signmethod":"hmacsha1","sign":"4870141D4067227128CBB4377906C3731CAC221C","productKey":"ZG1EvTE****","deviceName":"NlwaSPXsCpTQuh8FxBGH","timestamp":"1501668289957"}
    Table 1. Parameters
    Parameter Description
    Method The request method. Valid value: POST.
    URL The URL. Only HTTPS is supported. Valid value: /auth.
    Host The endpoint. For more information, see View the endpoint of an instance.
    Content-Type The 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.
    Notice
    • 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 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 Table 2.
    Table 2. Parameters included in the body parameter
    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 view the ProductKey on the Device Details page.
    deviceName Yes The DeviceName of the device. You can log on to the IoT Platform console and view the DeviceName on the Device Details page.
    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 within 15 minutes after the timestamp is generated. The timestamp is in the numeric format. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
    sign Yes The signature value.

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

    The value of content is a string that contains all the parameters to be submitted to IoT Platform, except for the version, sign, and signmethod parameters. The submitted parameters are sorted in alphabetical order and spliced without splicing 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 case-insensitive. 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
    • 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
    HTTP status code Error message Description
    10000 common error The error message returned because an unknown error 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 IoT Platform cannot process this number of requests. The throttling policy is applied.
  2. Submit data.

    The device sends data to a topic. Only custom topics with the Publish permission are supported.

    For example, the topic is /${YourProductKey}/${YourDeviceName}/pub. Assume that 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 What is a topic?.

    Sample response:

    body:
    {
      "code": 0,
      "message": "success",
      "info": {
        "messageId": 892687627916247040
      }
    }
    Table 5. Error codes
    HTTP status code Error message Description
    10000 common error The error message returned because an unknown error 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 another 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 another 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 IoT Platform cannot process this number of requests. The throttling policy is applied.

Example

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