IoT Platform:Struktur data ThingModelJson

Untuk batasan definisi fitur TSL pada produk dan perangkat, lihat Batasan Definisi Fitur TSL untuk Produk dan Perangkat.

Struktur data

Modul TSL bawaan dan kustom memiliki struktur data yang berbeda.

• Modul TSL bawaan

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

  Parameter	Type	Description
  productKey	String	ProductKey dari produk tempat model TSL tersebut berada.
  _ppk	String	Informasi versi model TSL, yang mencakup field berikut: version: Nomor versi model TSL. Parameter ini hanya dikembalikan untuk model TSL yang telah dipublikasikan. description: Deskripsi versi modul TSL bawaan. Parameter ini hanya dikembalikan untuk model TSL yang telah dipublikasikan.
  properties	List	Daftar properti dalam model TSL. Untuk informasi lebih lanjut mengenai struktur data properti, lihat Spesifikasi struktur data properti. Gunakan extendConfig dalam setiap struktur data properti untuk mendefinisikan informasi tambahan. Untuk informasi lebih lanjut, lihat Spesifikasi struktur data extendConfig. Jika suatu properti tidak memiliki informasi tambahan, Anda tidak perlu meneruskan extendConfig.
  services	List	Daftar layanan dalam model TSL. Untuk informasi lebih lanjut mengenai struktur data layanan, lihat Spesifikasi format data layanan. Gunakan extendConfig dalam setiap struktur data layanan untuk mendefinisikan informasi tambahan. Untuk informasi lebih lanjut, lihat Spesifikasi struktur data extendConfig. Jika suatu layanan tidak memiliki informasi tambahan, Anda tidak perlu meneruskan extendConfig.
  events	List	Daftar event dalam model TSL. Untuk informasi lebih lanjut mengenai struktur data event, lihat Spesifikasi format data event. Gunakan extendConfig dalam setiap struktur data event untuk mendefinisikan informasi tambahan. Untuk informasi lebih lanjut, lihat Spesifikasi struktur data extendConfig. Jika suatu event tidak memiliki informasi tambahan, Anda tidak perlu meneruskan extendConfig.
  functionBlocks	List	Daftar modul TSL kustom. Hanya disertakan jika produk memiliki modul kustom. Berisi field berikut: productKey: ProductKey dari produk tempat model TSL tersebut berada. functionBlockId: Pengidentifikasi unik untuk modul TSL kustom dalam suatu produk. functionBlockName: Nama modul TSL kustom.

• Modul TSL kustom

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

  Tabel berikut mencantumkan parameter dasar modul TSL kustom. Untuk parameter lainnya, lihat deskripsi modul TSL bawaan.

  Parameter	Type	Description
  identifier	String	Pengidentifikasi unik untuk modul TSL kustom dalam suatu produk. Pengidentifikasi dapat terdiri dari maksimal 30 karakter dan boleh berisi huruf kapital, huruf kecil, angka, serta garis bawah (_).
  name	String	Nama modul TSL kustom. Nama harus terdiri dari 4 hingga 30 karakter dan boleh berisi karakter Tionghoa, Jepang, huruf Latin, angka, serta garis bawah (_). Satu karakter Tionghoa atau Jepang dihitung sebagai satu karakter.
  description	String	Deskripsi modul, dengan panjang maksimum 100 karakter.

Struktur data properti

Tabel berikut mencantumkan parameter untuk mendefinisikan sebuah properti.

• Contoh dataSpecs ketika dataType adalah INT:

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

• Contoh dataSpecs ketika dataType adalah TEXT:

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

• Contoh dataSpecs ketika dataType adalah ARRAY:

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

• Contoh dataSpecsList ketika dataType adalah ENUM:

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

• Contoh item dalam dataSpecsList ketika dataType adalah STRUCT:

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

Format data layanan

Tabel berikut mencantumkan parameter untuk mendefinisikan sebuah layanan.

Format data event

Tabel berikut mencantumkan parameter untuk mendefinisikan sebuah event.

Struktur parameter input dan output

Tabel berikut mencantumkan field untuk mendefinisikan parameter input dan output layanan atau event.

Struktur data INT, FLOAT, dan DOUBLE

Jika fitur atau parameter memiliki tipe data INT, FLOAT, atau DOUBLE, struktur datanya mencakup parameter berikut.

Struktur data DATE dan TEXT

Struktur data untuk tipe data DATE dan TEXT mencakup parameter berikut.

Spesifikasi data ARRAY

Ketika tipe data fitur atau parameter adalah ARRAY, spesifikasi datanya mencakup parameter berikut.

Tipe ENUM dan BOOL

Jika fitur atau parameter bertipe BOOL atau ENUM, struktur datanya mencakup parameter berikut.

Struktur data Struct

Ketika tipe data fitur atau parameter adalah struct, struktur datanya mencakup parameter berikut.

Struktur data extendConfig

Dalam struktur data setiap properti, event, atau layanan, gunakan extendConfig untuk mendefinisikan informasi tambahan yang memetakan protokol komunikasi perangkat ke model TSL standar.

IoT Platform mendukung informasi tambahan untuk perangkat yang menggunakan protokol Modbus, OPC UA, atau gateway kustom. Spesifikasi data berbeda-beda tergantung protokolnya:

Tipe Modbus

Modbus hanya mendukung informasi tambahan untuk properti.

{
  "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}
  }
}

Tipe OPC UA

OPC UA mendukung informasi tambahan untuk properti, layanan, dan event.

{
  "identifier":"extend2",
  "displayName":"Action",
  "inputData":[
    {
      "identifier":"xxxx",
      "index":1
    },
    {
      "identifier":"xxxx",
      "index":2 
    }
  ],
  "outputData":[
     {
      "identifier":"xxxx",
      "index":1
    },
    {
      "identifier":"xxxx",
      "index":2
    }
  ]
}

Tipe kustom

Tipe kustom mendukung informasi tambahan untuk properti, layanan, dan event.

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

Validasi

Anda dapat menggunakan json-schema untuk memvalidasi parameter input dalam ThingModelJson.

Untuk definisi skema, lihat schema.json.

Contoh berikut menunjukkan cara melakukan validasi:

• Untuk mengunduh library json-schema, tambahkan dependensi berikut ke proyek Maven Anda.

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

• Kode contoh:

  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"
                      + "\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); // melempar ValidationException jika objek ini tidak valid
              System.out.println(System.currentTimeMillis() - start);
          }
          catch (ValidationException exception) {
              System.out.println(exception);
          }
      }
  }

Menulis ThingModelJson

Gunakan Visual Studio Code untuk menulis ThingModelJson dengan dukungan auto-completion.

1. Buka situs resmi Visual Studio Code untuk mengunduh dan menginstal versi terbaru Visual Studio Code.
2. Buka Visual Studio Code, klik tombol di pojok kiri bawah, lalu pilih Settings.
3. Pada tab User Settings, pilih Extensions > JSON. Di bawah Schemas, klik Edit in settings.json, tambahkan konfigurasi berikut, lalu simpan file tersebut.

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

   Setelah Anda menyimpan konfigurasi, prompt auto-completion akan muncul saat Anda mendefinisikan Thing Model.

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