IoT Platform：HTTPS串連通訊

使用與限制

• 僅華東2（上海）地區支援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方法。
   URL	URL地址，只支援HTTPS，取值：/auth。
   Host	HTTP接入地址：公用執行個體和企業版執行個體中，HTTP的接入網域名稱，請參見查看和配置執行個體終端節點資訊（Endpoint）。
   Content-Type	裝置發送給物聯網平台的上行資料的編碼格式，目前只支援application/json。若使用其他編碼格式，會返回參數錯誤。
   Content-Length	HTTP訊息體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. 錯誤碼說明

   code	message	備忘
   10000	common error	未知錯誤。
   10001	param error	請求的參數異常。
   20000	auth check error	裝置鑒權失敗。
   20004	update session error	更新失敗。
   40000	request 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。
   Host	Endpoint地址。
   password	放在Header中的參數，取值為調用裝置認證介面auth返回的token值。
   Content-Type	裝置發送給物聯網平台的上行資料的編碼格式，目前僅支援application/octet-stream。若使用其他編碼格式，會返回參數錯誤。
   Content-Length	HTTP訊息實體的傳輸長度。
   body	發往${topic}的資料內容。資料格式說明，請參見Topic分類和通訊說明。

   返回結果樣本：

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

   表 5. 錯誤碼說明

   code	message	備忘
   10000	common error	未知錯誤。
   10001	param error	請求的參數異常。
   20001	token is expired	token失效。需重新調用auth進行鑒權，擷取token。
   20002	token is null	請求header中無token資訊。
   20003	check token error	根據token擷取identify資訊失敗。需重新調用auth進行鑒權，擷取token。
   30001	publish message error	資料上行失敗。
   40000	request too many	請求次數過多，流控限制。

樣本

使用HTTP用戶端接入物聯網平台的樣本，請參見HTTP用戶端接入樣本。