Lenguaje de expresión de correlación

Lenguaje de expresión y reglas de notificación

El lenguaje de expresiones de mapeo se ha ampliado para su uso con la gestión de datos. Uso de reglas de notificación y acciones mediante la introducción de $state variables $instance y que se definen para su uso en expresiones.

• La variable $state se utiliza para hacer referencia a las propiedades del estado del dispositivo en una expresión, por ejemplo, $state.temperature.
• La variable $instance se utiliza para hacer referencia a atributos y metadatos en la instancia de dispositivo en una expresión, por ejemplo, $instance.metadata.tempThresholdMax.

Es posible que desee utilizar estas variables para que no sea necesario codificar valores en las expresiones de condición de notificación de reglas, y puede establecer un valor de umbral distinto para cada instancia de dispositivo..

Operadores de JSONata

Se admiten todos los operadores JSONata, excepto los que se indican en la lista:

• Operadores de vía de acceso
  No soportado:
  • ^(…) (ordenado por)
• Operadores numéricos
• Operadores de comparación
• Operadores booleanos
• Otros operadores
  No soportado:
  • ~> (Cadena)
  • := (Enlace de variable)
  • ... ~> | ... | ... | (Transformar)

• Utilice paréntesis ( ) para agrupar expresiones y para modificar la prioridad de operadores.
• Utilice comillas simples o dobles para series y nombres de propiedad, por ejemplo $event.object.'ab'.
• Utilice comillas invertidas para rodear nombres de propiedad que contienen caracteres especiales, incluidos espacios, por ejemplo:

  {"x y":22}.`x y`

• Utilice comillas invertidas para rodear nombres de propiedad que comienzan con un número, por ejemplo

  `7emperature`

Funciones de JSONata

• Todas las funciones de serie
• Todas las funciones numéricas
• Todas las funciones de agregación numérica
• Todas las funciones booleanas
• Las siguientes Funciones de matriz:
  • $count
  • $append

Ampliación del lenguaje de expresión de correspondencia

El lenguaje de expresión de correlación se ha ampliado para utilizarlo con la característica de gestión de datos a través de la introducción de las variables $event, $state e $instance. El JSON se limita a estas variables antes de evaluar la expresión. La siguiente tabla proporciona una visión general de estas variables, definidas para utilizarlas en expresiones:

En el ejemplo siguiente se utiliza el objeto siguiente como entrada a un suceso:

{
    "temperature": 35,
    "humidity": 72,
    "pressure": 1024
}

El objeto se convierte en una matriz utilizando la expresión siguiente:

[$event.temperature, $event.humidity, $event.pressure]

La expresión da como resultado la generación de la salida siguiente:

 [
    35,
    72,
    1024
  ]

Puede invertir este ejemplo y convertir una matriz de la entrada en un objeto. En el ejemplo siguiente se utiliza la matriz siguiente como entrada a un suceso:

{
    "readings": [
      35,
      72,
      1024
    ]
  }

La matriz se convierte en un objeto utilizando la expresión siguiente:

 {"temperature": $event.readings[0], "humidity": $event.readings[1], "pressure": $event.readings[2]}

La expresión da como resultado la generación de la salida siguiente:

{
  "temperature": 35,
  "humidity": 72,
  "pressure": 1024
}

También puede definir una expresión que combine el uso de estas variables. En el ejemplo siguiente, se define una propiedad temp_adjustment en los metadatos del dispositivo y se utiliza para calibrar la lectura de sucesos. La propiedad se define en una correlación pero se puede asignar a muchos dispositivos.

"propertyMappings" : {
        "tevt" : {
           "temperature" : "$event.t + $instance.metadata.temp_adjustment"
        }
     },

El operador punto "." se utiliza para el acceso a objetos con una clave literal, por ejemplo $event.object.hh. La primera expresión, que en el ejemplo es $event.t, está restringida a una propiedad específica, ya sea en el suceso ($event) o el estado ($state) o los metadatos ($instance). La segunda expresión, que en el ejemplo es $instance.metadata.temp_adjustment, contiene la información a la que desea acceder.

Guía lingüística

• Se da soporte a todas las Consultas simples .
• Las consultas de predicado están soportadas, excepto para los comodines.
• Las expresiones entre paréntesis están soportadas, excepto para bloques de código.
• Se da soporte a las Expresiones condicionales siguientes:
  • Lógica condicional
  • Variables
    Las variables están soportadas mediante el uso de las variables $instance, $statey $event como parte del lenguaje de correlación ampliado que es específico de esta característica de gestión de datos.
    Nota: Las variables $ y $$ que se utilizan en JSONata no están soportadas actualmente.
  • Invocación de la mayoría de funciones predefinidas.
    
    Nota: No puede definir sus propias funciones.

Construcción de la salida

Puede especificar cómo se presentan los datos procesados en la salida utilizando constructores de matrices o constructores de objetos.

Constructores de matrices soportados

Las matrices se pueden construir delimitando una lista separada por comas de literales o expresiones en un par de corchetes. Las comas se utilizan para separar varias expresiones dentro de la generación de secuencia inlcuding del constructor de matrices, por ejemplo, [1, 3-1] = [1,2], [1..3] -> [1,2,3] y [1..3, 7..9] -> [1,2,3,7,8,9].

Constructores de objetos soportados

Puede construir objetos JSON en la salida utilizando un par de llaves {} que contienen valores de clave o pares separados por comas, con cada clave y valor separados por dos puntos, por ejemplo, {key1 : value1, key2:value2} o {"hello" : "world"}. La clave de objeto debe ser una serie.

Manejo de discrepancias entre la expresión de correlación y los datos de entrada

Una actualización de estado puede fallar cuando una de las expresiones de correlación contiene una referencia a datos de entrada que no se han especificado en el suceso publicado.

Por ejemplo, puede configurar las expresiones siguientes:

temperature = $event.t
humidity = $event.hum

donde t es una propiedad opcional para el suceso.

Si se recibe un suceso que contiene sólo datos de humedad, por ejemplo, {"humidity":22}, la expresión temperature = $event.t no se puede evaluar, porque la propiedad t opcional no se especifica en el suceso de dispositivo publicado.

La actualización de estado falla. La propiedad de estado de humedad no se actualiza, y se publica un mensaje de error en el tema de error de MQTT para el dispositivo:

iot-2/type/${typeId}/id/${deviceId}/err/data

Para evitar anomalías de actualización de estado debido a datos opcionales no especificados, puede utilizar la función $exists en combinación con un condicional ternario para especificar un valor predeterminado para las propiedades opcionales. El ejemplo siguiente define un valor predeterminado de 0 para la propiedad t :

"tempEvent:
    {
      "temperature": "$exists($event.t)?$event.t:0",
      "humidity": "$event.hum"
    }

Al definir un valor predeterminado para la propiedad opcional de esta forma, la expresión se evalúa correctamente, incluso cuando la propiedad t no se especifica en el suceso de dispositivo publicado.

Por lo tanto, si se recibe el suceso {"humidity":22} , la actualización de estado se completa correctamente y el estado del dispositivo se establece en {"humidity":22, "temperature":0}.