提交物模型訊息解析指令碼 - IoT Platform

本文以解析上、下行屬性訊息資料的指令碼為例，介紹在資料格式為透傳或自訂的產品下，如何編寫並提交物模型訊息解析指令碼。

前提條件

建立產品時已定義資料格式為透傳/自訂。具體操作，請參見建立產品。

背景資訊

資料格式為ICA標準資料格式，裝置按照物聯網平台定義的標準資料格式產生訊息上報，標準Alink JSON資料格式說明，請參見裝置屬性、事件、服務。

資料格式為透傳/自訂，裝置通訊時，需要物聯網平台叫用您提交的訊息解析指令碼，將上行物模型訊息解析為物聯網平台定義的標準格式（Alink JSON），將下行物模型訊息據解析為裝置的自訂資料格式。

說明本樣本中的屬性為預設模組屬性，若使用自訂模組，標識符（identifier）的格式為${模組標識符}:${屬性標識符}。例如，model1:prop_int16 。

步驟一：編輯指令碼

建立產品：在物聯網平台控制台，建立產品，資料格式選擇為透傳/自訂。

單個添加物模型：為該產品定義物模型屬性。

本樣本中定義了以下三個屬性：

標識符（identifier）	資料類型	取值範圍	讀寫類型
prop_float	浮點單精確度（float）	-100~100	讀寫
prop_int16	整數型（int32）	-100~100	讀寫
prop_bool	布爾型（bool）	0：開；1：關	讀寫

本樣本通訊中參數值長度定義：

裝置上報資料請求
欄位 位元組數
框架類型 1位元組
請求ID 4位元組
屬性prop_int16 2位元組
屬性prop_bool 1位元組
屬性prop_float 4位元組
裝置上報資料響應
欄位 位元組數
框架類型 1位元組
請求ID 4位元組
結果code 1位元組
設定屬性請求
欄位 位元組數
框架類型 1位元組
請求ID 4位元組
屬性prop_int16 2位元組
屬性prop_bool 1位元組
屬性prop_float 4位元組
屬性設定響應
欄位 位元組數
框架類型 1位元組
請求ID 4位元組
結果code 1位元組

編寫指令碼。

在產品頁面，單擊產品對應的查看。
在產品詳情頁面，單擊訊息解析頁簽。

選擇指令碼語言，然後在編輯指令碼下的輸入框中輸入指令碼。

支援的指令碼語言	裝置自訂資料格式轉Alink JSON格式資料的函數（上行通訊）	Alink JSON格式資料轉為裝置自訂資料格式的函數（下行通訊）	範例程式碼
JavaScript（ECMAScript 5）	rawDataToProtocol	protocolToRawData	JavaScript指令碼樣本
Python 2.7	raw_data_to_protocol	protocol_to_raw_data	Python指令碼樣本
PHP 7.2	rawDataToProtocol	protocolToRawData	PHP指令碼樣本

說明您還需編寫自訂Topic的上行訊息解析指令碼，相關指令碼編寫說明，請參見提交訊息解析指令碼。

有關自訂Topic訊息解析和物模型訊息解析的完整樣本指令碼，請參見透傳/自訂產品完整樣本指令碼（JavaScript）、透傳/自訂產品完整樣本指令碼（Python）和透傳/自訂產品完整樣本指令碼（PHP）。

步驟二：線上測試指令碼

重要下文中傳入和返回的十六進位字串和JSON格式資料僅為樣本，實際情境中，不可直接用於調試。

指令碼編輯完成後，在類比輸入下，選擇類比類型，輸入類比資料線上測試指令碼。

類比解析裝置上報的屬性資料。
選擇類比類型為裝置上報資料，輸入以下類比的裝置上報資料，然後單擊執行。
說明以下傳入參數類比資料僅適用於JavaScript指令碼，更多樣本內容，請參見JavaScript指令碼樣本。
Python、PHP指令碼的傳入參數類比資料，請參見Python指令碼樣本、PHP指令碼樣本。
您可使用字串轉十六進位工具，將待傳入參數JSON格式資料轉為十六進位格式資料。例如轉化後為00002233441232013fa00000，則輸入如下資料。
```
0x00002233441232013fa00000
```
資料解析引擎會按照指令碼規則，將透傳資料轉換為JSON格式資料。
單擊運行結果，查看解析結果。
```
{
    "method": "thing.event.property.post", 
    "id": "2241348", 
    "params": {
        "prop_float": 1.25, 
        "prop_int16": 4658, 
        "prop_bool": 1
    }, 
    "version": "1.0"
}
```
類比解析物聯網平台下發的返回結果資料。
選擇類比類型為裝置接收資料，輸入以下JSON格式資料，然後單擊執行。
```
{
  "id": "12345",
  "version": "1.0",
  "code": 200,
  "method": "thing.event.property.post",
  "data": {}
}
```
資料解析引擎會將JSON格式資料轉換為以下資料：
```
0x0200003039c8
```

類比解析物聯網平台下發的屬性設定資料。

選擇類比類型為裝置接收資料，輸入以下JSON格式資料，然後單擊執行。

{
    "method": "thing.service.property.set", 
    "id": "12345", 
    "version": "1.0", 
    "params": {
        "prop_float": 123.452, 
        "prop_int16": 333, 
        "prop_bool": 1
    }
}

資料解析引擎會將JSON格式資料轉換為以下資料：

0x0100003039014d0142f6e76d

類比解析裝置返回的屬性設定結果資料。
選擇類比類型為裝置上報資料，輸入以下資料，然後單擊執行。
```
0x0300223344c8
```
資料解析引擎會將透傳資料轉換為以下JSON格式資料：
```
{
  "code": "200",
  "data": {},
  "id": "2241348",
  "version": "1.0"
}
```

步驟三：提交指令碼

重要僅提交後的指令碼才能被物聯網平台叫用；草稿狀態的指令碼不能被調用。

確認指令碼可以正確解析資料後，單擊提交，將該指令碼提交到物聯網平台系統，以供裝置資料上下行時，物聯網平台叫用該指令碼解析資料。

步驟四：使用真實裝置調試

正式使用指令碼之前，請使用真實裝置與物聯網平台進行上下行訊息通訊，以驗證物聯網平台能順利呼叫指令碼，解析上下行資料。

您可使用物聯網平台提供的Link SDK開發裝置接入物聯網平台。詳細內容，請參見Link SDK。

測試上報屬性資料。
1. 使用裝置端上報裝置屬性資料，例如0x00002233441232013fa00000。
2. 在物聯網平台控制台，選擇裝置管理 > 裝置。
3. 單擊裝置對應的查看，然後在裝置詳情頁物模型資料 > 運行狀態頁簽下，查看是否有相應的屬性資料。
測試下發屬性資料。
1. 在物聯網平台控制台，選擇監控營運 > 線上調試。
2. 選擇要調試的產品和裝置，並選擇預設模組，功能選擇為要調試的屬性identifier，如屬性（prop_int16），方法選擇為設定，輸入以下資料，單擊發送指令。
```
{
    "method": "thing.service.property.set", 
    "id": "12345", 
    "version": "1.0", 
    "params": {
        "prop_float": 123.452, 
        "prop_int16": 333, 
        "prop_bool": 1
    }
}
```
3. 查看裝置端是否收到該屬性設定指令。
4. 在該裝置的裝置詳情頁面的物模型資料 > 運行狀態頁簽下，查看裝置是否上報當前屬性資料。

可選：更新訊息解析指令碼

提交訊息解析指令碼成功後，您可在訊息解析頁簽，修改或刪除指令碼代碼後，參考本文操作步驟重新測試和提交。提交成功後，等待一分鐘，就會對該產品下已有裝置和新增裝置的訊息解析服務生效。

警告

修改指令碼代碼重新提交後，請同步修改訊息解析服務相關商務邏輯，否則可能導致相關業務中斷。
刪除指令碼代碼重新提交後，該產品下裝置訊息解析服務不可用、使用者業務中斷。

請謹慎操作。

IoT Platform：提交物模型訊息解析指令碼