IoT Platform:ThingModelJson のデータ構造

TSL 機能の制限については、「制限」をご参照ください。

データ構造

デフォルトの TSL モジュールのデータ構造は、カスタム TSL モジュールのデータ構造とは異なります。

• デフォルトの TSL モジュール

  {
    "_ppk":{
         "description":"test", // テスト
         "version":"159244410****" // バージョン
    }
    "events":[], // イベント
    "productKey":"al12345****", // プロダクトキー
    "properties":[], // プロパティ
    "services":[], // サービス
    "functionBlocks":[{ // ファンクションブロック
        "productKey":"al12345****", // プロダクトキー
        "functionBlockId":"location0", // ファンクションブロックID
        "functionBlockName":"Location module 0" // 位置モジュール 0
      }]
  }

  パラメーター	型	説明
  productKey	String	TSL モデルが属するプロダクトの ProductKey。
  _ppk	String	TSL モデルバージョンに関する情報。このパラメーターは、次のフィールドで構成されます。 version: 現在の TSL モデルのバージョン番号。このフィールドは、公開済みの TSL モデルでのみ使用できます。 description: 現在の TSL モデルの説明。このフィールドは、公開済みの TSL モデルでのみ使用できます。
  properties	List	TSL モデルが属するプロダクトのプロパティ。 properties パラメーターのデータ構造の詳細については、「properties パラメーターのデータ構造」をご参照ください。 各プロパティで、extendConfig パラメーターを使用して、TSL モデルに関する拡張情報を定義できます。詳細については、「extendConfig パラメーターのデータ構造」をご参照ください。拡張情報を定義する必要がない場合は、extendConfig パラメーターを指定する必要はありません。
  services	List	TSL モデルが属するプロダクトのサービス。 services パラメーターのデータ構造の詳細については、「services パラメーターのデータ構造」をご参照ください。 各サービスで、extendConfig パラメーターを使用して、TSL モデルに関する拡張情報を定義できます。詳細については、「extendConfig パラメーターのデータ構造」をご参照ください。拡張情報を定義する必要がない場合は、extendConfig パラメーターを指定する必要はありません。
  events	List	TSL モデルが属するプロダクトのイベント。 events パラメーターのデータ構造の詳細については、「events パラメーターのデータ構造」をご参照ください。 各イベントで、extendConfig パラメーターを使用して、TSL モデルに関する拡張情報を定義できます。詳細については、「extendConfig パラメーターのデータ構造」をご参照ください。拡張情報を定義する必要がない場合は、extendConfig パラメーターを指定する必要はありません。
  functionBlocks	List	カスタムモジュールのリスト。このパラメーターは、プロダクトに少なくとも 1 つのカスタム TSL モジュールが含まれている場合にのみ使用できます。このパラメーターは、次のフィールドで構成されます。 productKey: TSL モデルが属するプロダクトの ProductKey。 functionBlockId: カスタム TSL モジュールの ID。各 ID はプロダクト内で一意です。 functionBlockName: カスタム TSL モジュールの名前。

• カスタム TSL モジュール

  {
    "productKey":"al12345****", // プロダクトキー
    "identifier":"location0", // ID
    "name":"Location module 0", // 位置モジュール 0
    "properties":[], // プロパティ
    "services":[], // サービス
    "events":[], // イベント
    "description":"" // 説明
  }

  次の表に、デフォルトの TSL モジュールから継承されたものを除く、カスタム TSL モジュールのパラメーターを示します。

  パラメーター	型	説明
  identifier	String	カスタム TSL モジュールの ID。各 ID はプロダクト内で一意です。 ID は 1 ～ 30 文字で、文字、数字、およびアンダースコア(_)を含めることができます。
  name	String	カスタム TSL モジュールの名前。 名前は 4 ～ 30 文字で、文字、数字、およびアンダースコア(_)を含めることができます。
  description	String	カスタム TSL モジュールの説明。説明は最大 100 文字まで入力できます。

properties パラメーターのデータ構造

次の表に、プロパティを定義するために使用されるパラメーターを示します。

• dataSpecs パラメーターのサンプル値 (dataType パラメーターが INT に設定されている場合):

  {
    "dataSpecs": { // データ仕様
      "custom": true, // カスタム
      "dataType": "INT", // データ型
      "defaultValue": "30", // デフォルト値
      "max": "1440", // 最大値
      "min": "0", // 最小値
      "step": "10", // ステップ
      "unit": "min" // 単位
    }
  }

• dataSpecs パラメーターのサンプル値 (dataType パラメーターが TEXT に設定されている場合):

  {
    "dataSpecs": { // データ仕様
      "custom": true, // カスタム
      "dataType": "TEXT", // データ型
      "id": 2412127, // ID
      "length": 2048 // 長さ
    }
  }

• dataSpecs パラメーターのサンプル値 (dataType パラメーターが ARRAY に設定されている場合):

  {
    "dataSpecs": { // データ仕様
      "childDataType": "INT", // 子データ型
      "custom": true, // カスタム
      "dataType": "ARRAY", // データ型
      "size": 1 // サイズ
    }
  }

• dataSpecsList パラメーターのサンプル値 (dataType パラメーターが ENUM に設定されている場合):

  {
    "dataSpecsList": [ // データ仕様リスト
      {
        "custom": false, // カスタム
        "dataType": "ENUM", // データ型
        "defaultValue": "true", // デフォルト値
        "name": "Open", // 開く
        "value": 1 // 値
      },
      {
        "custom": false, // カスタム
        "dataType": "ENUM", // データ型
        "defaultValue": "false", // デフォルト値
        "name": "Close", // 閉じる
        "value": 0 // 値
      }
    ]
  }

• dataSpecsList パラメーターのサンプル値 (dataType パラメーターが STRUCT に設定されている場合):

  {
    "childDataType": "TEXT", // 子データ型
    "childName": "Card number", // カード番号
    "dataSpecs": { // データ仕様
      "custom": true, // カスタム
      "dataType": "TEXT", // データ型
      "length": 128 // 長さ
    },
    "dataType": "STRUCT", // データ型
    "identifier": "CardNo", // カード番号
    "name": "NVR chip information" // NVR チップ情報
  }

services パラメーターのデータ構造

次の表に、サービスを定義するために使用されるパラメーターを示します。

events パラメーターのデータ構造

次の表に、イベントを定義するために使用されるパラメーターを示します。

入力パラメーターと出力パラメーターのデータ構造

次の表に、サービスまたはイベントの入力パラメーターと出力パラメーターを定義するために使用されるパラメーターを示します。

INT、FLOAT、または DOUBLE 型のデータ構造

次の表に、INT、FLOAT、および DOUBLE 型のデータを定義するために使用されるパラメーターを示します。

DATE または TEXT 型のデータ構造

次の表に、DATE および TEXT 型のデータを定義するために使用されるパラメーターを示します。

ARRAY 型のデータ構造

次の表に、ARRAY 型のデータを定義するために使用されるパラメーターを示します。

ENUM または BOOL 型のデータ構造

次の表に、BOOL および ENUM 型のデータを定義するために使用されるパラメーターを示します。

STRUCT 型のデータ構造

次の表に、STRUCT 型のデータを定義するために使用されるパラメーターを示します。

extendConfig パラメーターのデータ構造

各プロパティ、イベント、およびサービスで、extendConfig パラメーターを使用して、TSL モデルに関する拡張情報を定義できます。拡張情報は、デバイスの接続プロトコルと標準 TSL モデル間のマッピングを示します。

Modbus、OPC UA、またはカスタムプロトコルがデバイスのゲートウェイ接続プロトコルとして使用されている場合は、デバイスに関する拡張情報を定義できます。拡張情報のタイプによって、データ仕様が異なります。

Modbus タイプ

Modbus がデバイスのゲートウェイ接続プロトコルとして使用されている場合は、プロパティに関する拡張情報のみを定義できます。

{
  "identifier":"extend1", // ID
  "writeFunctionCode":0, // 書き込みファンクションコード
  "writeOnly":0, // 書き込み専用
  "registerAddress":"0xFE", // レジスタアドレス
  "operateType":"coilStatus", // 操作タイプ
  "scaling":0.1, // スケーリング
  "pollingTime":1000, // ポーリング時間
  "trigger":1, // トリガー
  "bitMask":128, // ビットマスク
  "originalDataType":{ // 元のデータ型
     "type":"uint64", // タイプ
     "specs":{ // 仕様
        "swap":0, // スワップ
        "reverseRegister":0} // 逆レジスタ
  }
}

OPC UA タイプ

OPC UA がデバイスのゲートウェイ接続プロトコルとして使用されている場合は、プロパティ、サービス、およびイベントに関する拡張情報を定義できます。

{
  "identifier":"extend2", // ID
  "displayName":"Action", // アクション
  "inputData":[ // 入力データ
    {
      "identifier":"xxxx", // ID
      "index":1 // インデックス
    },
    {
      "identifier":"xxxx", // ID
      "index":2 // インデックス
    }
  ],
  "outputData":[ // 出力データ
     {
      "identifier":"xxxx", // ID
      "index":1 // インデックス
    },
    {
      "identifier":"xxxx", // ID
      "index":2 // インデックス
    }
  ]
}

カスタムタイプ

カスタムプロトコルがデバイスのゲートウェイ接続プロトコルとして使用されている場合は、プロパティ、サービス、およびイベントに関する拡張情報を定義できます。

{
  "identifier":"xxx", // ID
  "customize":{} // カスタマイズ
}

ThingModelJson パラメーターの検証

ThingModelJson パラメーターの入力パラメーターを検証するには、json-schema ファイルを使用できます。

詳細については、「schema.json」をご参照ください。

ThingModelJson パラメーターの検証例

• json-schema ライブラリをダウンロードするには、Maven プロジェクトに次の依存関係を追加します:

  <dependency>
      <groupId>com.github.everit-org.json-schema</groupId>
      <artifactId>org.everit.json.schema</artifactId>
      <version>1.11.0</version>
  </dependency>

• サンプルコード:

  package com.aliyun.iot.thingmodel;
  
  import java.io.InputStream;
  import java.net.URL;
  import java.util.ArrayList;
  import java.util.Arrays;
  
  import org.everit.json.schema.Schema;
  import org.everit.json.schema.ValidationException;
  import org.everit.json.schema.loader.SchemaLoader;
  import org.json.JSONObject;
  import org.json.JSONTokener;
  
  /**
   * @author: *** // 作成者
   * @date: 2020-01-14 15:11 // 日付
   */
  public class ThingModelJsonValidator {
  
      public static void main(String[] args) throws Exception {
  
          try (InputStream inputStream = new URL("https://iotx-thing-model-schema.oss-ap-southeast-1.aliyuncs.com/schema.json").openStream()) {
              JSONObject rawSchema = new JSONObject(new JSONTokener(inputStream));
              Schema schema = SchemaLoader.load(rawSchema);
              long start = System.currentTimeMillis();
              JSONObject object = new JSONObject();
              String jsonStr = "{\n"
                      + "\t\t\t\"productKey\": \"a1Q1Yrc****\",\n" // productKey
                      + "\t\t\t\"name\": \"Alert event\",\n" // 名前
                      + "\t\t\t\"identifier\": \"alarmEvent\",\n" // ID
                      + "\t\t\t\"eventName\": \"Alert event\",\n" // イベント名
                      + "\t\t\t\"eventType\": \"ALERT_EVENT_TYPE\",\n" // イベントタイプ
                      + "\t\t\t\"outputData\": [\n" // 出力データ
                      + "\t\t\t\t{\n"
                      + "\t\t\t\t\t\"paraOrder\": 0,\n" // パラメーター次数
                      + "\t\t\t\t\t\"direction\": \"PARAM_OUTPUT\",\n" // 方向
                      + "\t\t\t\t\t\"dataSpecsList\": [\n" // dataSpecsList
                      + "\t\t\t\t\t\t{\n"
                      + "\t\t\t\t\t\t\t\"dataType\": \"ENUM\",\n" // データ型
                      + "\t\t\t\t\t\t\t\"name\": \"Anti-detachment alert\",\n" // 名前
                      + "\t\t\t\t\t\t\t\"value\": 0\n" // 値
                      + "\t\t\t\t\t\t},\n"
                      + "\t\t\t\t\t\t{\n"
                      + "\t\t\t\t\t\t\t\"dataType\": \"ENUM\",\n" // データ型
                      + "\t\t\t\t\t\t\t\"name\": \"Anti-detachment alert\",\n" // 名前
                      + "\t\t\t\t\t\t\t\"value\": 1\n" // 値
                      + "\t\t\t\t\t\t}\n"
                      + "\t\t\t\t\t],\n"
                      + "\t\t\t\t\t\"dataType\": \"ENUM\",\n" // データ型
                      + "\t\t\t\t\t\"identifier\": \"alarmType\",\n" // ID
                      + "\t\t\t\t\t\"name\": \"Alert type\",\n" // アラートタイプ
                      + "\t\t\t\t\t\"index\": 0,\n" // インデックス
                      + "\t\t\t\t\t\"custom\": true\n" // カスタム
                      + "\t\t\t\t}\n"
                      + "\t\t\t],\n"
                      + "\t\t\t\"outputParams\": [\n" // 出力パラメーター
                      + "\t\t\t\t{\n"
                      + "\t\t\t\t\t\"index\": 0,\n" // インデックス
                      + "\t\t\t\t\t\"identifier\": \"alarmType\"\n" // ID
                      + "\t\t\t\t}\n"
                      + "\t\t\t],\n"
                      + "\t\t\t\"custom\": true\n" // カスタム
                      + "\t\t}";
  
              object.put("properties", new ArrayList<>());
              object.put("services", new ArrayList<>());
              object.put("events", Arrays.asList(com.alibaba.fastjson.JSONObject.parseObject(jsonStr)));
              object.put("productKey", "a1Q1Yrc****");
              schema.validate(object); // このオブジェクトが無効な場合、ValidationException がスローされます
              //}
              System.out.println(System.currentTimeMillis() - start);
          }
          catch (ValidationException exception) {
              System.out.println(exception);
          }
      }
  
  }

ThingModelJson パラメーターの指定

このセクションでは、Visual Studio Code ツールを使用して ThingModelJson パラメーターを指定する方法について説明します。

1. Visual Studio Code 公式 Web サイト にアクセスして、最新バージョンの Visual Studio Code ツールをダウンロードしてインストールします。
2. Visual Studio Code を開き、左下隅にある ボタンをクリックし、[設定] を選択します。
3. [ユーザー設定] タブで、[拡張機能] > [JSON] を選択します。[settings.json で編集][スキーマ] の下の

    "json.schemas": [{
           "fileMatch": ["/.json"], // .json ファイルに一致
           "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json" // スキーマの URL
   }]

   次に、プロンプトに従って ThingModelJson パラメーターを指定できます。