Preguntas frecuentes sobre modelos TSL - IoT Platform - Centro de documentación de Alibaba Cloud

Este tema responde a las preguntas frecuentes (FAQ) sobre el uso de modelos TSL para la comunicación de dispositivos y proporciona soluciones.

Agregar funciones del modelo TSL

Las propiedades, eventos y servicios de un modelo TSL deben agregarse y configurarse en el producto que contiene el dispositivo. Puede definir un modelo TSL de las siguientes maneras:

Llame a la API CreateThingModel para agregar funciones del modelo TSL a un producto específico.
Agregue funciones del modelo TSL en la consola de IoT Platform. Para obtener más información, consulte Add a single TSL model y Add TSL models in batches.

Error de verificación de TSL durante la importación masiva

Síntomas

Al importar un modelo TSL para un producto en la consola de IoT Platform, pueden ocurrir dos tipos de errores de verificación en el cuadro de diálogo Import TSL Model: un mensaje de error inmediato que indica The file content is not in a valid JSON format, o una excepción de verificación con un enlace Download and View para recuperar información detallada del error.

Soluciones

Las siguientes soluciones corresponden a los dos tipos de errores de verificación:

Revise el archivo del modelo TSL, corrija cualquier error de formato JSON y vuelva a cargar el archivo.

Haga clic en Download and View para obtener el archivo errors.txt. Utilice este archivo para identificar y resolver el problema.

Para obtener más información sobre el archivo errors.txt, consulte el siguiente ejemplo.

Archivo de muestra del modelo 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"
}

Archivo errors.txt descargado:

[
  {
    "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}$\""
  }
]

Parámetro	Descripción
path	La ruta al elemento que causó el error de verificación. En este ejemplo, se encontraron dos errores: `// The properties parameter is incorrectly configured. It is not an array. "path": [ "properties" ] // The value of functionBlockId contains a hyphen, which is invalid. "path": [ "functionBlockId" ]`
property	El objeto específico bajo la ruta que infringe la regla. Por ejemplo, la propiedad para `"path": ["functionBlockId" ]` es `instance.functionBlockId`.
message	El mensaje de error específico. Por ejemplo, para `"path": ["functionBlockId" ]`, el mensaje de error de la propiedad es `does not match pattern \"^[_a-zA-Z0-9]{1,30}$\"`.
schema	El nombre y contenido de la regla de verificación. Por ejemplo, para `"path": ["functionBlockId" ]`, las reglas son `type` y `pattern`. Para obtener más información sobre las definiciones de reglas, consulte JSON Schema.
instance	El objeto específico que se está verificando. Por ejemplo, para `"path": ["functionBlockId" ]`, se verifica el contenido de `"functionBlockId": "module-test"` en el archivo del modelo TSL.
name	El nombre de la regla que falló en la verificación. Por ejemplo, para `"path": ["functionBlockId" ]`, el objeto `module-test` no cumple con la regla `pattern`.
argument	La definición de la regla que se infringió. Por ejemplo, para `"path": ["functionBlockId" ]`, la regla `pattern` no cumplida se define como `^[_a-zA-Z0-9]{1,30}$`.
stack	Un mensaje de error completo que combina los campos property y message.

Para obtener más información, consulte jsonschema documentation.

Diferencias en los métodos de reporte de datos

Diferencias funcionales

Función	Diferencia
Reporte de propiedades	Reporta una instantánea de los datos de propiedad del dispositivo. La marca de tiempo es opcional: Si se incluye una marca de tiempo, IoT Platform la guarda como la hora en que se reportó la propiedad. Un solo reporte de datos puede contener información de un único punto en el tiempo. Si no se incluye ninguna marca de tiempo, IoT Platform genera automáticamente una basada en la hora actual y la guarda como la hora de reporte de la propiedad.
Reporte de datos históricos	Reporta valores de diferentes propiedades en el mismo punto temporal. Esta función se basa en el tiempo, por lo que requiere una marca de tiempo. Un solo reporte de datos puede incluir información de varios puntos temporales.
Reporte masivo de propiedades	Reporta valores de la misma propiedad en diferentes puntos temporales. Esta función se basa en la propiedad y requiere una marca de tiempo. Un solo reporte de datos puede incluir información de varias propiedades en múltiples puntos temporales.

Una vez que los datos de propiedad, los datos históricos o los datos masivos de propiedades se reportan a IoT Platform, la plataforma genera registros de datos históricos basados en las marcas de tiempo.

Diferencias en temas de comunicación y formatos de datos

El tema y el formato de datos difieren según el método utilizado. Para obtener más información, consulte Device reports properties, Report historical TSL model data y Device reports properties in batches.

Ejemplo

Este ejemplo utiliza un dispositivo que reporta datos de temperatura.

Reporte de propiedades:
1. El dispositivo reporta datos de instantáneas con marcas de tiempo secuencialmente de izquierda a derecha, como se muestra en la siguiente tabla.
  
  13:00
  
  14:00
  
  15:00
  
  15:10
  
  60
  
  70
  
  80
  
  90
2. Posteriormente, el dispositivo reporta otro valor de instantánea de 100. Los datos se actualizan de manera diferente dependiendo de si se incluye una marca de tiempo:
  - Sin marca de tiempo: La hora predeterminada es la hora actual (por ejemplo, 15:30). En este caso, el valor de instantánea mostrado en la consola de IoT Platform es 100 a las 15:30, y la última entrada en la lista de datos históricos también es 100 a las 15:30.
  - Con marca de tiempo: Si la marca de tiempo es 15:00, los datos de las 15:00 se actualizan a 100. El valor de instantánea mostrado en la consola de IoT Platform cambia a 100 a las 15:00, pero la última entrada en la lista de datos históricos permanece en 90 a las 15:10.
Reporte de datos históricos:
1. El dispositivo reporta los siguientes datos históricos simultáneamente.
  
  13:00
  
  14:00
  
  15:00
  
  15:10
  
  60
  
  70
  
  80
  
  90
2. Después, el dispositivo reporta los siguientes datos históricos al mismo tiempo.
  
  13:10
  
  14:10
  
  100
  
  200
  
  En este caso, el valor de instantánea mostrado en la consola de IoT Platform será 100 a las 13:10 o 200 a las 14:10, dependiendo de qué valor se escribió por último en la base de datos. La última entrada en la lista de datos históricos permanece en 90 a las 15:10.

Datos TSL no actualizados con tema personalizado

Debe reportar los datos del modelo TSL del dispositivo mediante un tema de comunicación del modelo TSL. Para obtener más información, consulte Topic categories and communication.

Recuperar datos del modelo TSL

Puede recuperar los datos del modelo TSL del dispositivo de las siguientes maneras:

Suscripción del lado del servidor: Utilice la función de suscripción del lado del servidor de IoT Platform para suscribirse a los mensajes de Device Upstream Notification. IoT Platform reenvía estos mensajes de todos los dispositivos del producto a su servidor según su configuración de suscripción. Se admiten los siguientes dos métodos para la suscripción del lado del servidor:
- AMQP server-side subscription: Utilice un SDK de AMQP para recibir los mensajes del dispositivo reenviados por IoT Platform.
- Message Service (MNS) server-side subscription: Utilice el SDK de Simple Message Queue (formerly MNS) para recibir los mensajes del dispositivo que IoT Platform reenvía a Simple Message Queue (formerly MNS).
Reenvío de datos: Utilice la función Data Forwarding del motor de reglas para crear reglas que reenvíen datos específicos del dispositivo a otros servicios en la nube, como Simple Message Queue (formerly MNS), ApsaraDB for RDS, Tablestore, Function Compute, Time Series Database (TSDB), Lindorm, DataHub y Message Queue for Apache RocketMQ. Para obtener más información, consulte Data Forwarding (Legacy) y Data Forwarding (New).

API de la nube:

API	Descripción
QueryDevicePropertyStatus	Queries all property snapshots of a specified device.
QueryDeviceOriginalPropertyStatus	Queries the original property snapshots reported by a specified device. This includes all properties, regardless of whether they passed TSL model verification.
QueryDeviceOriginalPropertyData	Queries the original property records reported by a specified device. This includes all properties, regardless of whether they passed TSL model verification.
QueryDeviceOriginalEventData	Queries the original event records reported by a specified device. This includes all events, regardless of whether they passed TSL model verification.
QueryDeviceOriginalServiceData	Queries the original service call records from a specified device. This includes all services, regardless of whether they passed TSL model verification.
QueryDeviceDesiredProperty	Queries the desired property values of a specified device.
QueryDevicePropertyData	Queries the data of a single property for a specified device within a specified time range.
QueryDevicePropertiesData	Queries the data of multiple properties for a specified device within a specified time range.
QueryDeviceEventData	Queries the event records of a specified device.
QueryDeviceServiceData	Queries the service call records of a specified device.

Datos del modelo TSL ausentes en la consola

Cuando un dispositivo reporta datos del modelo TSL, IoT Platform verifica la información basándose en el modelo TSL definido y en el método de validación de datos configurado. Los datos que fallan en la verificación o cuya validación se omite no se muestran en la pestaña TSL Model Data de la página Device Details del dispositivo en la consola de IoT Platform. Para obtener más información, consulte Validate TSL model data.

Debe establecer el método de validación de datos al crear un producto. Para obtener más información, consulte Create a product.

Estado de datos TSL no actualizado tras ejecutar comandos

Para solucionar el problema, investigue los siguientes aspectos:

Lado del dispositivo: Asegúrese de que el dispositivo esté conectado correctamente a IoT Platform. Para obtener información sobre cómo conectar un dispositivo, consulte Download device SDKs.

Importante
Un comando exitoso desde IoT Platform solo confirma que la solicitud 'set' se envió desde la nube; esto no garantiza la ejecución en el dispositivo. Para considerar que la propiedad se estableció correctamente, el dispositivo debe aplicar el nuevo valor y luego reportar ese valor de vuelta a la plataforma.

Puede usar el emulador de dispositivos o la herramienta MQTT.fx para simular un dispositivo en línea y luego utilizar la función de depuración en línea para probar las capacidades de comunicación del dispositivo. Para obtener más información, consulte:
Lado de la nube de IoT Platform:
- Asegúrese de que la propiedad a la que desea set un valor o un desired value tenga acceso de lectura/escritura.
- Asegúrese de que los mensajes del modelo TSL se analicen sintácticamente de forma correcta.
  
  Los datos se muestran en el estado de ejecución del modelo TSL solo si los mensajes del modelo TSL se analizan correctamente. Para obtener más información, consulte TSL models y Parse TSL model messages.
Inicie sesión en la consola de IoT Platform. En la instancia, vaya a la página Maintenance > Device Log > Cloud run log para consultar los registros y comprobar si el dispositivo recibió el mensaje correctamente. Para obtener más información, consulte Cloud run log.

Datos de temperatura ausentes en la consola

Los datos del modelo TSL no pueden mostrarse si la propiedad del modelo TSL no está definida o si el formato de los datos reportados es incorrecto.

Siga estos pasos para asegurar que los datos se muestren correctamente:

Defina una propiedad del modelo TSL llamada Temperature para el producto que contiene el dispositivo. Para obtener más información, consulte Add TSL model features.
El dispositivo debe reportar los datos de propiedad utilizando el tema de comunicación del modelo TSL y el formato de datos correctos. Para obtener más información sobre el desarrollo del lado del dispositivo, consulte Device connection.
- Si seleccionó ICA Standard Data Format (Alink JSON) como formato de datos al crear el producto, el dispositivo debe usar el tema /sys/${productKey}/${deviceName}/thing/event/property/post y reportar datos en el siguiente formato:
```
{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "temperature": {
            "value": 35,
            "time": 1524448722000
        }
    },
    "method": "thing.event.property.post"
}
```
  Para obtener más información sobre los campos, consulte Device reports properties.
- Si seleccionó Passthrough/Custom como formato de datos al crear el producto, debe configurar un script para analizar sintácticamente los mensajes del modelo TSL.
  
  El dispositivo debe usar el tema /sys/${productKey}/${deviceName}/thing/model/up_raw para transmitir datos en formato hexadecimal. Para obtener más información, consulte Device reports properties y Parse TSL model messages.

Importar rápidamente funciones del modelo TSL

Sí. IoT Platform proporciona los siguientes métodos para agregar funciones del modelo TSL en lotes:

Add TSL models in batches: En la consola de IoT Platform, puede copiar funciones del modelo TSL de otro producto en lotes o importar un archivo TSL.
CreateThingModel: Utilice un SDK del lado del servidor para llamar a esta API de la nube y agregar funciones del modelo TSL mediante el parámetro ThingModelJson. Para obtener más información sobre el formato de datos ThingModelJson, consulte ThingModelJson data format.

13:00	14:00	15:00	15:10
60	70	80	90

13:00	14:00	15:00	15:10
60	70	80	90

13:10	14:10
100	200