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
    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. Valid value: https://iot-as-http.cn-shanghai.aliyuncs.com.
    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.
    body The device information for authentication, in JSON format. For more information, see Table 2.
    Table 2. body parameters
    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 consoleand 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 created. 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. These parameters are sorted in alphabetical order and spliced without a splicing symbol.

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