IoT Platform:Structure de données ThingModelJson

Pour connaître les limites relatives aux définitions de fonctionnalités TSL pour les produits et les appareils, consultez la rubrique Limites des définitions de fonctionnalités TSL pour les produits et les appareils.

Structure de données

Les modules TSL par défaut et personnalisés possèdent des structures de données différentes.

• Module TSL par défaut

  {
    "_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 du produit auquel appartient le modèle TSL.
  _ppk	String	Informations de version du modèle TSL, contenant les champs suivants : version : Numéro de version du modèle TSL. Ce paramètre n'est renvoyé que pour les modèles TSL publiés. description : Description de la version du module TSL par défaut. Ce paramètre n'est renvoyé que pour les modèles TSL publiés.
  properties	List	Liste des propriétés du modèle TSL. Pour plus d'informations sur la structure de données des propriétés, consultez la section Spécification de la structure de données des propriétés. Utilisez extendConfig dans chaque structure de données de propriété pour définir les informations étendues. Pour plus d'informations, consultez la section Spécification de la structure de données extendConfig. Si une propriété ne comporte aucune information étendue, il n'est pas nécessaire de transmettre extendConfig.
  services	List	Liste des services du modèle TSL. Pour plus d'informations sur la structure de données des services, consultez la section Spécification du format de données des services. Utilisez extendConfig dans chaque structure de données de service pour définir les informations étendues. Pour plus d'informations, consultez la section Spécification de la structure de données extendConfig. Si un service ne comporte aucune information étendue, il n'est pas nécessaire de transmettre extendConfig.
  events	List	Liste des événements du modèle TSL. Pour plus d'informations sur la structure de données des événements, consultez la section Spécification du format de données des événements. Utilisez extendConfig dans chaque structure de données d'événement pour définir les informations étendues. Pour plus d'informations, consultez la section Spécifications de la structure de données extendConfig. Si un événement ne comporte aucune information étendue, il n'est pas nécessaire de transmettre extendConfig.
  functionBlocks	List	Liste des modules TSL personnalisés. Inclus uniquement si le produit comporte des modules personnalisés. Contient les champs suivants : productKey : ProductKey du produit auquel appartient le modèle TSL. functionBlockId : Identifiant unique du module TSL personnalisé au sein d'un produit. functionBlockName : Nom du module TSL personnalisé.

• Module TSL personnalisé

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

  Le tableau suivant répertorie les paramètres de base d'un module TSL personnalisé. Pour les autres paramètres, reportez-vous aux descriptions du module TSL par défaut.

  Parameter	Type	Description
  identifier	String	Identifiant unique du module TSL personnalisé au sein d'un produit. L'identifiant peut comporter jusqu'à 30 caractères et contenir des lettres majuscules, des lettres minuscules, des chiffres et des traits de soulignement (_).
  name	String	Nom du module TSL personnalisé. Le nom doit comporter entre 4 et 30 caractères et peut contenir des caractères chinois, japonais, des lettres anglaises, des chiffres et des traits de soulignement (_). Un caractère chinois ou japonais compte pour un seul caractère.
  description	String	Description du module, d'une longueur maximale de 100 caractères.

Structure de données des propriétés

Le tableau suivant répertorie les paramètres permettant de définir une propriété.

• Exemple de dataSpecs lorsque dataType est INT :

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

• Exemple de dataSpecs lorsque dataType est TEXT :

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

• Exemple de dataSpecs lorsque dataType est ARRAY :

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

• Exemple de dataSpecsList lorsque dataType est ENUM :

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

• Exemple d'un élément dans dataSpecsList lorsque dataType est STRUCT :

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

Format de données des services

Le tableau suivant répertorie les paramètres permettant de définir un service.

Format des données d'événement

Le tableau suivant répertorie les paramètres permettant de définir un événement.

Structure des paramètres d'entrée et de sortie

Le tableau suivant liste les champs utilisés pour définir les paramètres d'entrée et de sortie d'un service ou d'un événement.

Structure des données INT, FLOAT et DOUBLE

Si une fonctionnalité ou un paramètre possède un type de données INT, FLOAT ou DOUBLE, sa structure de données comprend les paramètres suivants.

Structure des données DATE et TEXT

La structure de données pour les types DATE et TEXT comprend les paramètres suivants.

Spécification des données ARRAY

Lorsque le type de données d'une fonctionnalité ou d'un paramètre est ARRAY, la spécification des données inclut les paramètres suivants.

Types ENUM et BOOL

Si une fonctionnalité ou un paramètre est de type BOOL ou ENUM, sa structure de données inclut les paramètres suivants.

Structure de données Struct

Lorsque le type de données d'une fonctionnalité ou d'un paramètre est struct, sa structure de données inclut les paramètres suivants.

Structure de données extendConfig

Dans la structure de données de chaque propriété, événement ou service, utilisez extendConfig pour définir les informations étendues qui mappent les protocoles de communication des appareils au modèle TSL standard.

IoT Platform prend en charge les informations étendues pour les appareils utilisant les protocoles Modbus, OPC UA ou les protocoles de passerelle personnalisés. Les spécifications de données diffèrent selon le protocole :

Type Modbus

Modbus prend en charge les informations étendues uniquement pour les propriétés.

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

Type OPC UA

OPC UA prend en charge les informations étendues pour les propriétés, les services et les événements.

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

Type personnalisé

Le type personnalisé prend en charge les informations étendues pour les propriétés, les services et les événements.

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

Validation

Vous pouvez utiliser json-schema pour valider les paramètres d'entrée dans ThingModelJson.

Pour la définition du schéma, consultez schema.json.

L'exemple suivant montre comment effectuer la validation :

• Pour télécharger la bibliothèque json-schema, ajoutez la dépendance suivante à votre projet Maven.

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

• Exemple de code :

  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); // throws a ValidationException if this object is invalid
              System.out.println(System.currentTimeMillis() - start);
          }
          catch (ValidationException exception) {
              System.out.println(exception);
          }
      }
  }

Rédaction de ThingModelJson

Utilisez Visual Studio Code pour rédiger ThingModelJson avec la prise en charge de la saisie semi-automatique.

1. Accédez au site Web officiel de Visual Studio Code pour télécharger et installer la dernière version de Visual Studio Code.

2. Ouvrez Visual Studio Code, cliquez sur le bouton Settings

   

   dans le coin inférieur gauche, puis sélectionnez

   .

3. Dans l'onglet User Settings, choisissez Extensions > JSON. Sous Schemas, cliquez sur Edit in settings.json, ajoutez la configuration suivante et enregistrez le fichier.

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

   Après avoir enregistré la configuration, des invites de saisie semi-automatique apparaissent lorsque vous définissez un modèle d'objet.

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