FAQ sur le modèle TSL et solutions - IoT Platform - Centre de documentation Alibaba Cloud

Ajout de fonctionnalités au modèle TSL

Les propriétés, événements et services d'un modèle TSL doivent être ajoutés et configurés dans le produit auquel l'appareil est associé. Vous pouvez définir un modèle TSL de plusieurs manières :

Appelez l'API CreateThingModel pour ajouter des fonctionnalités de modèle TSL à un produit spécifique.
Ajoutez des fonctionnalités de modèle TSL dans la console IoT Platform. Pour plus d'informations, consultez les rubriques Ajout d'un seul modèle TSL et Ajout de modèles TSL par lots.

Échec de la validation TSL lors de l'importation par lots

Symptômes

Lorsque vous importez un modèle TSL pour un produit dans la console IoT Platform, deux types d'échecs de validation peuvent se produire dans la boîte de dialogue Import TSL Model : un message d'erreur immédiat indiquant The file content is not in a valid JSON format, ou une exception de validation accompagnée d'un lien Download and View permettant de récupérer les détails de l'erreur.

Solutions

Les solutions suivantes correspondent aux deux types d'échecs de validation :

Vérifiez le fichier du modèle TSL, corrigez les erreurs de formatage JSON, puis téléchargez à nouveau le fichier.

Cliquez sur Download and View pour obtenir le fichier errors.txt. Utilisez ce fichier pour identifier et résoudre le problème.

Pour plus d'informations sur le fichier errors.txt, consultez l'exemple suivant.

Exemple de fichier de modèle TSL :

{
    "schema":"https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile":{
        "productKey":"a1Jk***"
    },
    "services":[],
    "properties": 1,
    "events": [],
    "functionBlockId": "modulemtest",
    "functionBlockName": "Custom Module 1"
}

Fichier errors.txt téléchargé :

[
  {
    "path": [
      "properties"
    ],
    "property": "instance.properties",
    "message": "is not of a type(s) array",
    "schema": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/propertyDefinition"
      }
    },
    "instance": 1,
    "name": "type",
    "argument": [
      "array"
    ],
    "stack": "instance.properties is not of a type(s) array"
  },
  {
    "path": [
      "functionBlockId"
    ],
    "property": "instance.functionBlockId",
    "message": "does not match pattern \"^[_a-zA-Z0-9]{1,30}$\"",
    "schema": {
      "type": "string",
      "pattern": "^[_a-zA-Z0-9]{1,30}$"
    },
    "instance": "module-test",
    "name": "pattern",
    "argument": "^[_a-zA-Z0-9]{1,30}$",
    "stack": "instance.functionBlockId does not match pattern \"^[_a-zA-Z0-9]{1,30}$\""
  }
]

Paramètre	Description
path	Chemin d'accès à l'élément ayant provoqué l'erreur de validation. Dans cet exemple, deux erreurs sont détectées : `// Le paramètre properties est incorrectement configuré. Il ne s'agit pas d'un tableau. "path": [ "properties" ] // La valeur de functionBlockId contient un trait d'union, ce qui n'est pas valide. "path": [ "functionBlockId" ]`
property	Objet spécifique situé sous le chemin d'accès qui enfreint la règle. Par exemple, la propriété correspondant à `"path": ["functionBlockId" ]` est `instance.functionBlockId`.
message	Message d'erreur spécifique. Par exemple, pour `"path": ["functionBlockId" ]`, le message d'erreur de la propriété est `does not match pattern \"^[_a-zA-Z0-9]{1,30}$\"`.
schema	Nom et contenu de la règle de validation. Par exemple, pour `"path": ["functionBlockId" ]`, les règles sont `type` et `pattern`. Pour plus d'informations sur les définitions des règles, consultez la page JSON Schema.
instance	Objet spécifique en cours de validation. Par exemple, pour `"path": ["functionBlockId" ]`, le contenu de `"functionBlockId": "module-test"` dans le fichier du modèle TSL est validé.
name	Nom de la règle dont la validation a échoué. Par exemple, pour `"path": ["functionBlockId" ]`, l'objet `module-test` ne respecte pas la règle `pattern`.
argument	Définition de la règle enfreinte. Par exemple, pour `"path": ["functionBlockId" ]`, la règle `pattern` non respectée est définie comme suit : `^[_a-zA-Z0-9]{1,30}$`.
stack	Message d'erreur complet combinant les champs property et message.

Pour plus d'informations, consultez la documentation jsonschema.

Différences entre les méthodes de reporting des données

Différences fonctionnelles

Fonctionnalité	Différence
Reporting des propriétés	Transmet un instantané des données de propriété de l'appareil. L'horodatage est facultatif : Si un horodatage est inclus, IoT Platform l'enregistre comme heure de reporting de la propriété. Un seul rapport de données ne peut contenir des données que pour un seul instant donné. Si aucun horodatage n'est inclus, IoT Platform génère automatiquement un horodatage basé sur l'heure actuelle et l'enregistre comme heure de reporting de la propriété.
Reporting des données historiques	Transmet les valeurs de différentes propriétés pour un même instant. Cette fonctionnalité est basée sur le temps. Un horodatage est requis. Un seul rapport de données peut inclure des données pour plusieurs instants.
Reporting des propriétés par lots	Transmet les valeurs d'une même propriété à différents instants. Cette fonctionnalité est basée sur la propriété. Un horodatage est requis. Un seul rapport de données peut inclure des données pour plusieurs propriétés à plusieurs instants.

Une fois que les données de propriété, les données historiques ou les données de propriété par lots ont été transmises à IoT Platform, la plateforme génère des enregistrements de données historiques basés sur les horodatages.

Différences au niveau des topics de communication et des formats de données

Le topic et le format de données diffèrent selon la méthode utilisée. Pour plus d'informations, consultez les rubriques Reporting des propriétés par l'appareil, Reporting des données historiques du modèle TSL et Reporting des propriétés par lots par l'appareil.

Exemple

Cet exemple utilise un appareil qui transmet des données de température.

Reporting des propriétés :

L'appareil transmet séquentiellement, de gauche à droite, des données d'instantané avec horodatages, comme indiqué dans le tableau suivant.

13:00

14:00

15:00

15:10

60

70

80

90

Ensuite, l'appareil transmet une autre valeur d'instantané de 100. La mise à jour des données varie selon qu'un horodatage est inclus ou non :
- Sans horodatage : l'heure correspond par défaut à l'heure actuelle (par exemple, 15:30). Dans ce cas, la valeur d'instantané affichée dans la console IoT Platform est 100 à 15:30, et la dernière entrée de la liste des données historiques est également 100 à 15:30.
- Avec horodatage : si l'horodatage est 15:00, les données de 15:00 sont mises à jour avec la valeur 100. La valeur d'instantané affichée dans la console IoT Platform devient 100 à 15:00, mais la dernière entrée de la liste des données historiques reste 90 à 15:10.

Reporting des données historiques :

L'appareil transmet simultanément les données historiques suivantes.

13:00

14:00

15:00

15:10

60

70

80

90

Ensuite, l'appareil transmet simultanément les données historiques suivantes.

13:10

14:10

100

200

Dans ce cas, la valeur d'instantané affichée dans la console IoT Platform est soit 100 à 13:10, soit 200 à 14:10, selon la dernière valeur écrite dans la base de données. La dernière entrée de la liste des données historiques reste 90 à 15:10.

Données TSL non mises à jour avec un topic personnalisé

Vous devez transmettre les données du modèle TSL de l'appareil en utilisant un topic de communication dédié au modèle TSL. Pour plus d'informations, consultez la rubrique Catégories de topics et communication.

Récupération des données du modèle TSL

Vous pouvez récupérer les données du modèle TSL de l'appareil de plusieurs manières :

Abonnement côté serveur : utilisez la fonctionnalité d'abonnement côté serveur d'IoT Platform pour vous abonner aux messages Device Upstream Notification. IoT Platform transfère ensuite ces messages de tous les appareils du produit vers votre serveur, selon vos paramètres d'abonnement. Deux méthodes d'abonnement côté serveur sont prises en charge :
- Abonnement côté serveur AMQP : utilisez un SDK AMQP pour recevoir les messages d'appareil transférés par IoT Platform.
- Abonnement côté serveur Message Service (MNS) : utilisez le SDK Simple Message Queue (anciennement MNS) pour recevoir les messages d'appareil qu'IoT Platform transfère vers Simple Message Queue (anciennement MNS).
Transfert de données : utilisez la fonctionnalité Data Forwarding du moteur de règles pour créer des règles qui transfèrent les données d'appareil spécifiées vers d'autres services cloud, tels que Simple Message Queue (anciennement MNS), ApsaraDB RDS, Tablestore, Function Compute, Time Series Database (TSDB), Lindorm, DataHub et Message Queue for Apache RocketMQ. Pour plus d'informations, consultez les rubriques Data Forwarding (hérité) et Data Forwarding (nouveau).

API Cloud :

API

Description

QueryDevicePropertyStatus

Interroge tous les instantanés de propriété d'un appareil spécifié.

QueryDeviceOriginalPropertyStatus

Interroge les instantanés de propriété d'origine transmis par un appareil spécifié. Cela inclut toutes les propriétés, qu'elles aient ou non passé la validation du modèle TSL.

QueryDeviceOriginalPropertyData

Interroge les enregistrements de propriété d'origine transmis par un appareil spécifié. Cela inclut toutes les propriétés, qu'elles aient ou non passé la validation du modèle TSL.

QueryDeviceOriginalEventData

Interroge les enregistrements d'événements d'origine transmis par un appareil spécifié. Cela inclut tous les événements, qu'ils aient ou non passé la validation du modèle TSL.

QueryDeviceOriginalServiceData

Interroge les enregistrements d'appels de service d'origine provenant d'un appareil spécifié. Cela inclut tous les services, qu'ils aient ou non passé la validation du modèle TSL.

QueryDeviceDesiredProperty

Interroge les valeurs de propriété souhaitées d'un appareil spécifié.

QueryDevicePropertyData

Interroge les données d'une seule propriété pour un appareil spécifié dans une plage de temps donnée.

QueryDevicePropertiesData

Interroge les données de plusieurs propriétés pour un appareil spécifié dans une plage de temps donnée.

QueryDeviceEventData

Interroge les enregistrements d'événements d'un appareil spécifié.

QueryDeviceServiceData

Interroge les enregistrements d'appels de service d'un appareil spécifié.

Absence des données du modèle TSL dans la console

Lorsqu'un appareil transmet des données de modèle TSL, IoT Platform valide ces données en fonction du modèle TSL défini et de la méthode de validation des données configurée. Les données qui échouent à la validation ou dont la validation est ignorée ne s'affichent pas dans l'onglet TSL Model Data de la page Device Details de l'appareil dans la console IoT Platform. Pour plus d'informations, consultez la rubrique Validation des données du modèle TSL.

Vous devez définir la méthode de validation des données lors de la création d'un produit. Pour plus d'informations, consultez la rubrique Création d'un produit.

État des données TSL non mis à jour après l'envoi de commandes

Pour résoudre ce problème, examinez les aspects suivants :

Côté appareil : assurez-vous que l'appareil est correctement connecté à IoT Platform. Pour savoir comment connecter un appareil, consultez la rubrique Téléchargement des SDK d'appareil.

Important
Une commande réussie depuis IoT Platform confirme uniquement que la requête « set » a été envoyée depuis le cloud ; elle ne garantit pas l'exécution par l'appareil. Pour que la propriété soit considérée comme correctement définie, l'appareil doit appliquer la nouvelle valeur, puis transmettre cette valeur à la plateforme.

Utilisez l'émulateur d'appareil ou l'outil MQTT.fx pour simuler un appareil en ligne, puis servez-vous de la fonctionnalité de débogage en ligne pour tester les capacités de communication de l'appareil. Pour plus d'informations, consultez :
Côté cloud IoT Platform :
- Assurez-vous que la propriété pour laquelle vous souhaitez set une valeur ou une desired value dispose d'un accès read/write.
- Assurez-vous que les messages du modèle TSL sont analysés correctement.
  
  Les données ne s'affichent dans l'état d'exécution du modèle TSL que si les messages du modèle TSL sont analysés correctement. Pour plus d'informations, consultez les rubriques Modèles TSL et Analyse des messages du modèle TSL.
Connectez-vous à la console IoT Platform. Dans l'instance, accédez à la page Maintenance > Device Log > Cloud run log pour afficher les journaux et vérifier si l'appareil a bien reçu le message. Pour plus d'informations, consultez la rubrique Cloud run log.

Absence des données de température dans la console

Les données du modèle TSL ne peuvent pas s'afficher si la propriété du modèle TSL n'est pas définie ou si le format des données transmises est incorrect.

Suivez ces étapes pour garantir un affichage correct des données :

Définissez une propriété de modèle TSL nommée Temperature pour le produit contenant l'appareil. Pour plus d'informations, consultez la rubrique Ajout de fonctionnalités au modèle TSL.
L'appareil doit transmettre les données de propriété en utilisant le topic de communication du modèle TSL et le format de données appropriés. Pour plus d'informations sur le développement côté appareil, consultez la rubrique Connexion de l'appareil.
- Si vous avez sélectionné ICA Standard Data Format (Alink JSON) comme format de données lors de la création du produit, l'appareil doit utiliser le topic /sys/${productKey}/${deviceName}/thing/event/property/post et transmettre les données au format suivant :
```
{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "temperature": {
            "value": 35,
            "time": 1524448722000
        }
    },
    "method": "thing.event.property.post"
}
```
  Pour plus d'informations sur les champs, consultez la rubrique Reporting des propriétés par l'appareil.
- Si vous avez sélectionné Passthrough/Custom comme format de données lors de la création du produit, vous devez configurer un script pour analyser les messages du modèle TSL.
  
  L'appareil doit utiliser le topic /sys/${productKey}/${deviceName}/thing/model/up_raw pour transmettre les données au format hexadécimal. Pour plus d'informations, consultez les rubriques Reporting des propriétés par l'appareil et Analyse des messages du modèle TSL.

Importation rapide des fonctionnalités du modèle TSL

Oui. IoT Platform propose les méthodes suivantes pour ajouter des fonctionnalités de modèle TSL par lots :

Ajout de modèles TSL par lots : dans la console IoT Platform, vous pouvez copier des fonctionnalités de modèle TSL depuis un autre produit par lots ou importer un fichier TSL.
CreateThingModel : utilisez un SDK côté serveur pour appeler cette API cloud et ajouter des fonctionnalités de modèle TSL à l'aide du paramètre ThingModelJson. Pour plus d'informations sur le format de données ThingModelJson, consultez la rubrique Format de données ThingModelJson.