IoT Platform:ThingModelJson データ構造

製品およびデバイスの TSL 機能定義の制限については、「製品およびデバイスの TSL 機能定義の制限」をご参照ください。

データ構造

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

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

  {
    "_ppk":{
         "description":"test",
         "version":"159244410****"
    }
    "events":[],
    "productKey":"al12345****",
    "properties":[],
    "services":[],
    "functionBlocks":[{
        "productKey":"al12345****",
        "functionBlockId":"location0",
        "functionBlockName":"Location module 0"
      }]
  }

  パラメーター	タイプ	説明
  productKey	文字列	TSL モデルが属するプロダクトの productKey です。
  _ppk	オブジェクト	TSL モデルのバージョン情報です。次のフィールドが含まれます： version：TSL モデルのバージョン番号です。このパラメーターは、公開済みの TSL モデルに対してのみ返されます。 description：デフォルト TSL モジュールバージョンの説明です。このパラメーターは、公開済みの TSL モデルに対してのみ返されます。
  properties	リスト	TSL モデルのプロパティのリストです。プロパティのデータ構造の詳細については、「プロパティデータ構造の仕様」をご参照ください。 各プロパティのデータ構造で extendConfig を使用して、拡張情報を定義します。詳細については、「extendConfig データ構造の仕様」をご参照ください。プロパティに拡張情報がない場合は、extendConfig を渡す必要はありません。
  services	リスト	TSL モデルのサービスのリストです。サービスのデータ構造の詳細については、「サービスデータフォーマットの仕様」をご参照ください。 各サービスのデータ構造で extendConfig を使用して、拡張情報を定義します。詳細については、「extendConfig データ構造の仕様」をご参照ください。サービスに拡張情報がない場合は、extendConfig を渡す必要はありません。
  events	リスト	TSL モデルのイベントのリストです。イベントのデータ構造の詳細については、「イベントデータフォーマットの仕様」をご参照ください。 各イベントのデータ構造で extendConfig を使用して、拡張情報を定義します。詳細については、「extendConfig データ構造の仕様」をご参照ください。イベントに拡張情報がない場合は、extendConfig を渡す必要はありません。
  functionBlocks	リスト	カスタム TSL モジュールのリストです。プロダクトにカスタムモジュールがある場合にのみ含まれます。次のフィールドが含まれます： productKey：TSL モデルが属するプロダクトの productKey です。 functionBlockId：プロダクト内のカスタム TSL モジュールの一意の識別子です。 functionBlockName：カスタム TSL モジュールの名前です。

• カスタム TSL モジュール

  {
    "productKey":"al12345****", 
    "identifier":"location0",
    "name":"Location module 0",
    "properties":[],
    "services":[],
    "events":[],
    "description":""
  }

  次の表に、カスタム TSL モジュールの基本パラメーターを示します。その他のパラメーターについては、デフォルト TSL モジュールの説明をご参照ください。

  パラメーター	タイプ	説明
  identifier	文字列	プロダクト内のカスタム TSL モジュールの一意の識別子です。 識別子は最大 30 文字で、大文字、小文字、数字、アンダースコア (_) を使用できます。
  name	文字列	カスタム TSL モジュールの名前です。 名前は 4～30 文字で、中国語文字、日本語文字、英字、数字、アンダースコア (_) を使用できます。中国語または日本語の文字は、1 文字としてカウントされます。
  description	文字列	最大 100 文字のモジュールの説明です。

プロパティのデータ構造

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

• dataType が INT の場合の dataSpecs の例：

  {
    "dataSpecs": {
      "custom": true,
      "dataType": "INT",
      "defaultValue": "30",
      "max": "1440",
      "min": "0",
      "step": "10",
      "unit": "min"
    }
  }

• dataType が TEXT の場合の dataSpecs の例：

  {
    "dataSpecs": {
      "custom": true,
      "dataType": "TEXT",
      "id": 2412127,
      "length": 2048
    }
  }

• dataType が ARRAY の場合の dataSpecs の例：

  {
    "dataSpecs": {
      "childDataType": "INT",
      "custom": true,
      "dataType": "ARRAY",
      "size": 1
    }
  }

• dataType が ENUM の場合の dataSpecsList の例：

  {
    "dataSpecsList": [
      {
        "custom": false,
        "dataType": "ENUM",
        "defaultValue": "true",
        "name": "Open",
        "value": 1
      },
      {
        "custom": false,
        "dataType": "ENUM",
        "defaultValue": "false",
        "name": "Close",
        "value": 0
      }
    ]
  }

• dataType が STRUCT の場合の dataSpecsList の項目の例：

  {
    "childDataType": "TEXT",
    "childName": "Card number",
    "dataSpecs": {
      "custom": true,
      "dataType": "TEXT",
      "length": 128
    },
    "dataType": "STRUCT",
    "identifier": "CardNo",
    "name": "NVR chip information"
  }

サービスデータフォーマット

以下の表は、サービスを定義するためのパラメーターを示しています。

イベントデータフォーマット

以下の表は、イベントを定義するためのパラメーターを示しています。

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

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

INT、FLOAT、DOUBLE のデータ構造

機能またはパラメーターのデータ型が INT、FLOAT、または DOUBLE の場合、そのデータ構造には次のパラメーターが含まれます。

DATE および TEXT のデータ構造

DATE および TEXT データ型のデータ構造には、次のパラメーターが含まれます。

ARRAY データ仕様

機能またはパラメーターのデータ型が ARRAY の場合、そのデータ仕様には次のパラメーターが含まれます。

ENUM および BOOL タイプ

機能またはパラメーターのデータ型が BOOL または ENUM の場合、そのデータ構造には次のパラメーターが含まれます。

構造体のデータ構造

機能またはパラメーターのデータ型が構造体の場合、そのデータ構造には次のパラメーターが含まれます。

extendConfig のデータ構造

各プロパティ、イベント、またはサービスのデータ構造では、extendConfig を使用して、デバイス通信プロトコルを標準 TSL モデルにマッピングするための拡張情報を定義します。

IoT Platform は、Modbus、OPC UA、またはカスタムゲートウェイプロトコルを使用するデバイスの拡張情報をサポートします。データ仕様はプロトコルによって異なります。

Modbus タイプ

Modbus は、プロパティの拡張情報のみをサポートします。

{
  "identifier":"extend1",
  "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",
  "displayName":"Action",
  "inputData":[
    {
      "identifier":"xxxx",
      "index":1
    },
    {
      "identifier":"xxxx",
      "index":2 
    }
  ],
  "outputData":[
     {
      "identifier":"xxxx",
      "index":1
    },
    {
      "identifier":"xxxx",
      "index":2
    }
  ]
}

カスタムタイプ

カスタムタイプは、プロパティ、サービス、およびイベントの拡張情報をサポートします。

{
  "identifier":"xxx",
  "customize":{}
}

バリデーション

json-schema を使用して、ThingModelJson の入力パラメーターを検証できます。

スキーマ定義については、schema.json をご参照ください。

次の例は、バリデーションを実行する方法を示します。

• 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;
  /**
   * @作成者: ***
   * @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"
                      + "\t\t\t\"name\": \"Alert event\",\n"
                      + "\t\t\t\"identifier\": \"alarmEvent\",\n"
                      + "\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"
                      + "\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 resolved\",\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"
                      + "\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"
                      + "\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 公式サイト にアクセスし、最新バージョンの Visual Studio Code をダウンロードしてインストールします。
2. Visual Studio Code を開き、左下隅にある ボタンをクリックして、[設定] を選択します。
3. [ユーザー設定] タブで、[拡張機能] > [JSON] を選択します。[スキーマ] の下で [settings.json で編集] をクリックし、次の設定を追加してファイルを保存します。

    "json.schemas": [{
           "fileMatch": ["*.json"],
           "url": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json"
   }]

   設定を保存すると、Thing モデルを定義する際に自動補完プロンプトが表示されます。

   "$schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json"
   ""
     events
     functionBlockId
     functionBlockName
     functionBlocks
     properties
     services