物聯網平臺支持接入業務場景為HTTPS協議的設備。本文介紹使用HTTPS連接通信的接入流程。

使用與限制

  • 僅華東2（上海）、華北2（北京）、華南1（深圳）地域支持HTTPS協議通信。
  • 僅華東2（上海）地域支持設備使用HTTPS短連接狀態接入物聯網平臺。使用HTTPS短連接的設備，在物聯網平臺控制臺也有在線和離線狀態變化。您可通過AMQP服務端訂閱設備上下線狀態變化時通知的消息。
  • 僅直連設備支持使用HTTPS協議通信，網關設備與網關子設備不支持使用HTTPS協議通信。
  • 適合單純的數據上報場景，數據上行接口傳輸的數據大小限制為128 KB。
  • Topic規范和MQTT的Topic規范一致，可以復用MQTT連接通信的Topic。使用HTTPS協議連接，上報數據請求：${endpoint}/topic/${topic}。不支持以?query_String=xxx格式傳參。
  • HTTPS協議接入僅支持POST請求方法。
  • 設備認證返回的token會在一定周期后失效。目前token有效期是7天，請務必考慮token失效邏輯的處理。

接入流程

接入流程主要包含：進行設備認證以獲取設備token、使用獲取的token進行持續地數據上報。

  1. 認證設備，獲取設備的token。

    認證設備請求：

    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"}
    表 1. 參數說明
    參數說明
    Method請求方法，只支持POST方法。
    URLURL地址，只支持HTTPS，取值：/auth。
    HostHTTP接入地址：公共實例和企業版實例中，HTTP的接入域名，請參見查看實例終端節點。
    Content-Type設備發送給物聯網平臺的上行數據的編碼格式，目前只支持application/json。若使用其他編碼格式，會返回參數錯誤。
    Content-LengthHTTP消息體body的傳輸長度。
    重要
    • 對于字段Content-Length，HTTP/1.1及之后版本協議中，默認已攜帶，HTTP/1.0及之前版本協議中，默認未攜帶。使用HTTP協議認證設備時，必須傳入字段Content-Length。
    • 字段Content-Length值必須與body傳輸長度完全一致，否則無法正確解析body內容，設備認證會失敗。
    body設備認證信息。JSON數據格式。具體信息，請參見下表body參數。
    表 2. body參數
    字段名稱是否必需說明
    productKey是設備所屬產品的ProductKey。可從物聯網平臺控制臺對應實例下的設備詳情頁面獲取。
    deviceName是設備名稱。可從物聯網平臺控制臺對應實例下的設備詳情頁面獲取。
    clientId是客戶端ID。長度為64字符內，建議以MAC地址或SN碼作為clientId。
    timestamp否時間戳。校驗時間戳15分鐘內的請求有效。時間戳格式為數值，值為自GMT 1970年01月01日0時0分到當前時間點所經過的毫秒數。
    sign是簽名。

    簽名計算格式為hmacmd5(DeviceSecret,content)。

    其中，content為將所有提交給服務器的參數（除version、sign和signmethod外），按照英文字母升序，依次拼接排序（無拼接符號）的結果。

    簽名示例：

    假設clientId = 127.0.0.1，deviceName = http_test，productKey = a1FHTWxQ****，timestamp = 1567003778853，signmethod = hmacmd5，deviceSecret = 89VTJylyMRFuy2T3sywQGbm5Hmk1****，簽名計算為：

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

    其中，toHexString()是將計算結果二進制數據的每個byte按4 bit轉化為十六進制字符串，大小寫不敏感。例如，計算結果byte數組是：[60 68 -67 -7 -17 99 30 69 117 -54 -58 -58 103 -23 113 71]，轉換后得到的字符串為：3C44BDF9EF631E4575CAC6C667E97147。

    signmethod否算法類型，支持hmacmd5和hmacsha1。

    若不傳入此參數，則默認為hmacmd5。

    version否版本號。若不傳入此參數，則默認default。

    設備認證返回結果示例： 

    body:
{
  "code": 0,
  "message": "success",
  "info": {
    "token":  "6944e5bfb92e4d4ea3918d1eda39****"
  }
}
    說明
    • 請將返回的token值緩存到本地。
    • 每次上報數據時，都需要攜帶token信息。如果token失效，需要重新認證設備獲取token。
    表 3. 錯誤碼說明
    codemessage備注
    10000common error未知錯誤。
    10001param error請求的參數異常。
    20000auth check error設備鑒權失敗。
    20004update session error更新失敗。
    40000request too many請求次數過多，流控限制。
  2. 上報數據。

    設備發送數據到某個Topic，只支持發布權限的Topic，支持自定義Topic。

    例如：Topic為/${YourProductKey}/${YourDeviceName}/pub，假設當前設備名稱為device123，產品的ProductKey為a1GFjLP****，那么您可以調用 https://iot-as-http.cn-shanghai.aliyuncs.com/topic/a1GFjLP****/device123/pub地址來上報數據。

    上報數據請求：

    POST /topic/${topic} HTTP/1.1
Host: ${YourEndpoint}
password:${token}
Content-Type: application/octet-stream
Content-Length: 53
body: ${your_data}
    表 4. 上報數據參數說明
    參數說明
    Method請求方法，只支持POST方法。
    URL/topic/${topic}。其中，變量${topic}需替換為數據發往的目標Topic。只支持HTTPS。
    HostEndpoint地址。
    password放在Header中的參數，取值為調用設備認證接口auth返回的token值。
    Content-Type設備發送給物聯網平臺的上行數據的編碼格式，目前僅支持application/octet-stream。若使用其他編碼格式，會返回參數錯誤。
    Content-LengthHTTP消息實體的傳輸長度。
    body發往${topic}的數據內容。

    數據內容的格式說明如下：

    返回結果示例： 

    body:
{
  "code": 0,
  "message": "success",
  "info": {
    "messageId": 892687****47040
  }
}
    表 5. 錯誤碼說明
    codemessage備注
    10000common error未知錯誤。
    10001param error請求的參數異常。
    20001token is expiredtoken失效。需重新調用auth進行鑒權，獲取token。
    20002token is null請求header中無token信息。
    20003check token error根據token獲取identify信息失敗。需重新調用auth進行鑒權，獲取token。
    30001publish message error數據上行失敗。
    40000request too many請求次數過多，流控限制。

示例

使用HTTP客戶端接入物聯網平臺的示例，請參見HTTP客戶端接入示例。