API調試-Postman模擬器
OneNET平台通用OTA設備側使用說明
通用遠端升級功能，包括模組升級和MCU應用升級兩類，待升級的設備通過HTTP協定RESTful標準格式與OneNET平台進行資料交互以完成升級。
南向設備目前所需的RESTful API一共有三類：檢測任務、拉取檔、上報狀態，其中拉取檔包括校驗TOKEN和獲取檔兩個API。
本頁內容介紹的是API的使用以及通過postman模擬器測試拉取固件的過程。
本文檔適用於使用OneNET平台進行通用OTA功能操作的設備側操作相關人員。
1. 鑒權參數
此處採用Python來計算產品Authorization,實際操作時更改產品id和accesskey即可,具體過程參考API鑒權，Python代碼如圖2所示：
圖 1 產品id和accesskey
圖 2 Phthon代碼
如圖2所示，計算出來的鑒權參數為：
version=2018-10-31&res=products%2F245528&et=7559008892&method=sha1&sign=TPllhakDDnUV90epLnOqpj6aWqI%3D
2. 檢測任務
http://ota.heclouds.com/ota/south/check?dev_id=527776559&manuf=102&model=10201&type=2&version=V1&cdn=false
Headers的參數Authorization：value為圖2計算出來的產品token。
manuf=102&model=10201這兩個參數參考下面的表格。
dev_id=527776559修改為需要升級的設備id。
其他參數不改變。
| 晶片平臺 | 晶片型號 | 廠商編號 | 晶片編號 |
|---|---|---|---|
| 樂鑫 | ESP32 | 101 | 10101 |
| nordic | nrf52832 | 102 | 10201 |
| 兆易 | GD32 | 103 | 10301 |
| 其他 | 其他 | 100 | 10001 |
圖 3 postman模擬器測試示例-URL參數
圖 4 postman模擬器測試示例-Header
如圖4所示，示例的請求回應的代碼如下:
{
"errno": 0,
"error": "succ",
"data": {
"target": "V1",
"token": "ota_iF0hnXrq2CxLrP8vZ39l",
"size": 22,
"md5": "ad2f4e4ea2a27eace7e4913139f8f01a",
"signal": 10,
"power": 50,
"retry": 0,
"interval": 0,
"type": 1
}
}
3. 校驗TOKEN
校驗TOKEN使用說明和回應資訊請參考OTA-SDK說明文檔。http://ota.heclouds.com/ota/south/download/ota_iF0hnXrq2CxLrP8vZ39l/check?dev_id=527776559
Headers的參數Authorization：value為上面計算出來的產品token。
dev_id=527776559修改為需要升級的設備id。
ota_iF0hnXrq2CxLrP8vZ39l為鑒權參數步驟獲取到的任務token。
其他參數不改變。
圖 5 postman模擬器測試示例-URL參數
4. 拉取文件
拉取檔使用說明和回應資訊請參考OTA-SDK說明文檔。http://ota.heclouds.com/ota/south/download/ota_iF0hnXrq2CxLrP8vZ39l
ota_iF0hnXrq2CxLrP8vZ39l為鑒權參數步驟獲取到的任務token，其他參數不改變。
可以拉取整個檔，如圖6所示,也可以拉取部分檔，如圖7所示：
圖 6 postman-拉取整個文件
圖 7 postman-拉取部分檔
頭部Range欄位解釋：
Range: bytes={start}-{end}
目前只支援如下幾種模式
(1) Range: bytes={start}-，獲取第{start}+1個位元組到最後的資料 例如：Range: bytes=0-，獲取所有資料; Range: bytes=2-，獲取第3個資料到最後1個資料; 注意：如果{start}>=檔總長度，則默認{start}=0 。(2) Range: bytes={start}-{end}，獲取第{start}+1個位元組到第{end}+1個位元組 例如：Range: bytes=0-99，獲取前100個位元組; 注意：若{end}>=文件總長度len，則默認end=len-1; 若{start}>{end}，start被設置為0。
(3) Range: bytes=-{end}，獲取最後end個位元組資料 例如：Range: bytes=-100，獲取最後100個位元組資料； 注意：如果{end}>檔總長度len，則默認end=len（獲取所有檔）。
分片狀態碼
分片返回的狀態碼：206
不分片返回的狀態碼：200
5. 上報狀態
上報狀態使用說明和回應資訊請參考OTA-SDK說明文檔。http://ota.heclouds.com/ota/south/report?dev_id=527776559&token=ota_iF0hnXrq2CxLrP8vZ39l
Headers的參數Authorization：value為上面計算出來的產品token。
Body內容為：
{
"result": 201
}
result:
101:升級包下載成功
102:下載失敗,空間不足
103:下載失敗,記憶體溢出
104:下載失敗,下載請求超時
105:下載失敗,電量不足
106:下載失敗,信號不良
107:下載失敗,未知異常
201:升級成功
202:升級失敗,電量不足
203:升級失敗,記憶體溢出
204:升級失敗,版本不一致
205:升級失敗,md5校驗失敗
206:升級失敗,未知異常
error:
0:上報狀態成功
1:上報狀態失敗，token鑒權失敗
2:上報狀態失敗，狀態碼有誤
20:上報狀態失敗，升級任務已經完成
21:無效的操作
22:上報狀態失敗，升級任務已被取消
24:請求內容result錯誤
說明
dev_id=527776559修改為需要升級的設備id。
ota_iF0hnXrq2CxLrP8vZ39l為鑒權參數步驟獲取到的任務token。
其他參數不改變。
圖 8 postman-上報狀態
圖 9 postman-上報升級成功狀態
上報升級成功狀態後，平台會顯示任務狀態為完成。