Sintaxis de expresión de serie temporal de Azure Time Series Insights Gen2
Información general
Expresión de serie temporal (TSX) es un lenguaje de expresiones basado en cadenas con escritura segura. TSX se usa para representar las siguientes entidades en una consulta de serie temporal.
- Filter
- Value
- Agregación
Expresiones de filtro
Las expresiones de filtro se usan para representar cláusulas booleanas. En la tabla siguiente se enumeran ejemplos de filtros:
| TSX | Descripción |
|---|---|
$event.PointValue.Double = 3.14 |
true para eventos con double PointValue igual a 3.14 |
$event.PointValue > 3.14 AND $event.Status.String = 'Good' |
true para eventos con PointValue mayor que 3.14 y estado de cadena Good |
$event.$ts > dt'2018-11-01T02:03:45Z' |
true para eventos con una marca de tiempo mayor que 2018-11-01T02:03:45Z |
$event.PointEval.Bool = true |
true para eventos con PointValue igual a true |
Expresiones de valor
Las expresiones de valor se usan para representar el valor de las variables numéricas y categóricas. Una expresión de valor puede ser una expresión de referencia de propiedad de tipo Double o Long.
Por ejemplo:
| TSX | Notas |
|---|---|
$event.Temperature.Double |
El último token de cualquier expresión de valor (en este caso Double) se lee como tipo de la propiedad . |
$event.Temperature |
Se supone que el tipo es Double para una propiedad a la que accede un único token. |
$event['Temperature-Celsius'] |
Use [ y ] para los tokens de escape que tengan caracteres especiales. Además, use \ entre corchetes para escapar los siguientes caracteres: \ y '. |
$event.Temperature.Celsius.Double |
Use . para acceder a las propiedades anidadas. Al acceder a las propiedades anidadas, se requiere el tipo. |
$event.Temperature['Celsius-C'].Double |
Use [ y ] para los tokens de escape que tengan caracteres especiales al acceder a propiedades anidadas. Además, use \ entre corchetes para escapar los siguientes caracteres: \ y '. Al acceder a las propiedades anidadas, se requiere el tipo. |
$event['Temperature']['Celsius'].Double |
El uso de [ y ] para los tokens de escape se permite en cualquier token. |
Tipo de variable numérica
El resultado de la expresión de valor debe ser de tipo Double o Long .
Tipo de variable de agregado
El resultado de la expresión de valor puede ser de cualquier tipo admitido.
Tipo de variable categórica
El resultado de la expresión de valor solo puede ser de tipo String o Long .
Expresiones de agregación
Las expresiones de agregado se usan para representar la operación de agregación que se usará en la consulta. Una expresión de agregado da como resultado un valor único para cada intervalo. Las expresiones de agregado se pueden aplicar en variables numéricas y de agregado.
Expresiones de agregación: tipo de variable numérica
Las variables numéricas deben hacer referencia a $value.
Estas son las funciones de agregado admitidas.
| Función de agregado | Ejemplo | Descripción |
|---|---|---|
min |
min($value) |
Calcula el mínimo de por $value intervalo. Evita valores null . No se puede usar con interpolación. |
max |
max($value) |
Calcula el máximo de por $value intervalo. Evita valores null . No se puede usar con interpolación. |
sum |
sum($value) |
Calcula la suma de $value todos los eventos del intervalo. Evita valores null . No se puede usar con interpolación. |
avg |
avg($value) |
Calcula el promedio de $value todos los eventos del intervalo. Evita valores null . No se puede usar con interpolación. |
first |
first($value) |
Devuelve $value el primer evento que se produce en el intervalo por marca de tiempo de evento.
No evitanull valores. No se puede usar con interpolación. |
last |
last($value) |
Devuelve $value el último evento que se produjo en el intervalo por marca de tiempo de evento.
No evitanull valores. No se puede usar con interpolación. |
median |
median($value) |
Devuelve $value el evento intermedio en el intervalo por marca de tiempo del evento.
No evitanull valores. No se puede usar con interpolación. |
stdev |
stdev($value) |
Devuelve $value la desviación estándar de los eventos en el intervalo. Evita valores null . No se puede usar con interpolación. |
twsum |
twsum($value) |
Devuelve $value la suma ponderada de tiempo de los eventos en el intervalo. Requiere interpolación. |
twavg |
twavg($value) |
Devuelve $value el promedio ponderado de tiempo de los eventos en el intervalo. Requiere interpolación. |
left |
left($value) |
Devuelve en $value el borde izquierdo del intervalo especificado. Requiere interpolación. |
right |
right($value) |
Devuelve en $value el borde derecho del intervalo especificado. Requiere interpolación. |
Expresiones de agregación: tipo de variable de agregado
Las variables de agregado deben hacer referencia a una propiedad en la carga del evento.
Estas son las funciones de agregado admitidas.
| Aggregate, función | Ejemplo | Descripción |
|---|---|---|
count |
count() |
Devuelve el número de eventos por intervalo. |
min |
min($event.Temperature.Double) |
Calcula el mínimo de la propiedad Temperature por intervalo. Evita valores null . |
max |
max($event.Temperature.Long) |
Calcula el máximo de la propiedad Temperature por intervalo. Evita valores null . |
sum |
sum($event.Temperature.Double) |
Calcula la suma de la propiedad Temperature en todos los eventos del intervalo. Evita valores null . |
avg |
avg($event.Temperature.Long) |
Calcula el promedio de la propiedad Temperature en todos los eventos del intervalo. Evita valores null . |
first |
first($event.Temperature.String) |
Devuelve el primer valor (por marca de tiempo de evento) de la propiedad Temperature de todos los eventos del intervalo.
No evitanull valores. |
last |
last($event.Temperature.String) |
Devuelve el último valor (por marca de tiempo de evento) de la propiedad Temperature de todos los eventos del intervalo.
No evitanull valores. |
median |
median($event.Temperature.String) |
Devuelve el valor intermedio (por marca de tiempo de evento) de la propiedad Temperature de todos los eventos del intervalo.
No evitanull valores. |
stdev |
stdev($event.Temperature.String) |
Calcula la desviación estándar de la propiedad Temperature por intervalo. Evita valores null . |
Para un tipo de variable de agregado , estas funciones se pueden combinar en la expresión de agregado. Por ejemplo: max($event.Temperature.Long) - min($event.Temperature.Long).
Sintaxis
En esta sección se describen los conceptos básicos de sintaxis y los operadores de consulta que se concatenan para formar expresiones.
Literales admitidos
Nota
Los literales siguientes se usan para formar expresiones, consulte el artículo Tipos de datos admitidos para obtener la lista completa de tipos de datos.
| Tipo primitivo | Literales |
|---|---|
| Bool |
TRUE, FALSE |
| DateTime | dt'2016-10-08T03:22:55.3031599Z' |
| Double |
1.23, 1.0 |
| Long |
1, 6 |
| String | 'abc' |
| TimeSpan | ts'P1Y2M3DT4M5.67S' |
| Null | NULL |
Tipos de operando admitidos
| Operación | Tipos admitidos | Notas |
|---|---|---|
| <, >, <, > | Double, Long, DateTime, TimeSpan | |
| =, =, <> | Double, Long, String, Bool, DateTime, TimeSpan, NULL | <> es equivalente a != |
| +, -, *, / | Double, Long, DateTime, TimeSpan |
Para las expresiones de comparación (<, , ><=, >=, =, !=), los operandos pueden ser NULL o ser del mismo tipo. En cada expresión de predicado, se validan los tipos de operandos de lado izquierdo (LHS) y del lado derecho (RHS) para que coincidan. Los errores se producen cuando los tipos de LHS y RHS no están de acuerdo o no se permite una operación en tipos concretos.
Nota
El tipo de cadena no acepta valores NULL en el almacenamiento intermedio:
- La comparación de String con NULL y la cadena vacía ("") se comporta de la misma manera:
$event.p1.String = NULLes equivalente a$event.p1.String = ''. - La API puede devolver valores NULL incluso si los eventos originales contenían cadenas vacías.
En el futuro, el mismo comportamiento estará en almacenamiento en frío.
No dependa de los valores NULL de las columnas String y las trate de la misma manera que las cadenas vacías.
- Se aplica una comprobación de tipos:
- Cualquier tipo de propiedad se acepta en un
NULLliteral. - Los tipos de LHS y RHS deben coincidir.
- Cualquier tipo de propiedad se acepta en un
Estos son ejemplos de propiedades p1 y p2 de tipo String, propiedad p3 de tipo Double y una propiedad anidada almacenada como p4.p5 de tipo Double:
| Filtrar | ¿Es válido? | Notas |
|---|---|---|
$event.p1.String = 'abc' |
Sí | |
$event.p1.String = $event.p2.String |
Sí | |
$event.p1.String = NULL |
Sí |
NULL coincide con cualquier tipo de lado izquierdo. |
$event.p3.Double = 'abc' |
No | No coinciden los tipos. |
$event.p3.Double = $event.p1.String |
No | No coinciden los tipos. |
$event.p1 = 'abc' |
No | No coinciden los tipos. |
$event.p1 = 1 |
No | No coinciden los tipos. |
$event.p1 = true |
No | No coinciden los tipos. |
$event.p1 = NULL |
Sí |
p1 es el único token usado. Interpretado como $event.p1.Double = NULL |
$event['p1'] != NULL |
Sí |
['p1'] es el único token usado. Interpretado como $event['p1'].Double != NULL |
$event.p4.p5 = 0.0 |
No | Sintaxis de referencia de propiedad no válida. Se debe especificar un tipo en LHS de comparación. |
$event.p4.p5.Double = 0.0 |
Sí |
Funciones escalares admitidas
A continuación se muestra la lista de funciones escalares por categorías:
Funciones de conversión
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
toDouble |
Double toDouble (value: String, Double, Long) |
toDouble($event.value.Long) |
Convierte los argumentos en Double. |
toLong |
Long toLong (value: String, Double, Long) |
toLong($event.value.Double + 1.0) |
Convierte los argumentos en Long. |
toString |
String toString (value: String, Double, Long) |
toString($event.value.Double) |
Convierte argumentos en String. |
Funciones matemáticas
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
round |
Double round(value:Double) |
round($event.value.Double) |
Redondea un número flotante de doble precisión a la integral más cercana. |
ceiling |
Double ceiling(value:Double) |
ceiling($event.value.Double) |
Devuelve el valor entero más pequeño que es mayor o igual que el número de punto flotante de precisión doble. |
floor |
Double floor(value:Double) |
floor($event.value.Double) |
Devuelve el valor entero más grande que es menor o igual que el número de punto flotante de precisión doble. |
Funciones trigonométricas
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
cos |
Double cos(value:Double) |
cos($event.value.Double) |
Devuelve el coseno del ángulo especificado en radianes. |
sin |
Double sin(value:Double) |
sin($event.value.Double) |
Devuelve el seno del ángulo especificado en radianes. |
tan |
Double tan(value:Double) |
tan($event.value.Double) |
Devuelve la tangente del ángulo especificado en radianes. |
acos |
Double acos(value:Double) |
acos($event.value.Double) |
Devuelve el ángulo en radianes cuyo coseno es el número especificado. |
asin |
Double asin(value:Double) |
asin($event.value.Double) |
Devuelve el ángulo en radianes cuyo seno es el número especificado. |
atan |
Double atan(value:Double) |
atan($event.value.Double) |
Devuelve el ángulo en radianes cuya tangente es el número especificado. |
atan2 |
Double atan2(value1:Double, value2:Double) |
atan2($event.value1.Double, $event.value2.Double) |
Devuelve el ángulo en radianes cuya tangente es el cociente de dos números especificados. |
Funciones logarítmicas
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
log |
Double log(value:Double) |
log($event.value.Double) |
Devuelve el logaritmo natural de un número especificado. |
log2 |
Double log2(value:Double) |
log2($event.value.Double) |
Devuelve el logaritmo en base 2 de un número especificado. |
log10 |
Double log10(value:Double) |
log10($event.value.Double) |
Devuelve el logaritmo en base 10 de un número especificado. |
Funciones de fecha y hora
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
monthOfYear |
Long monthOfYear(value:DateTime) |
monthOfYear($event.$ts) |
Devuelve el mes del año como un valor numérico para la fecha y hora proporcionada. |
dayOfMonth |
Long dayOfMonth(value:DateTime) |
dayOfMonth($event.$ts) |
Devuelve el día del mes como un valor numérico para la fecha y hora proporcionada. |
hourOfDay |
Long hourOfDay(value:DateTime) |
hourOfDay($event.$ts) |
Devuelve la hora del día como un valor numérico para la fecha y hora proporcionada. |
utcNow |
DateTime utcNow() |
utcNow() |
Devuelve la hora actual en formato UTC. |
Funciones de cadena
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
toUpper |
String toUpper(value:String) |
toUpper($event.value.String) |
Devuelve la cadena de entrada convertida en mayúsculas. |
toLower |
String toLower(value:String) |
toLower($event.value.String) |
Devuelve la cadena de entrada convertida en minúsculas. |
strLen |
Long strLen(value:String) |
strLen($event.value.String) |
Devuelve el número de caracteres del argumento string. |
strCat |
Long strCat(value1:String, value2:String) |
strCat($event.value1.String, $event.value2.String) |
Concatena dos cadenas de entrada especificadas. |
subString |
String subString(value:String, startIndex:Double, length:Double) |
subString($event.value.String, 2.0, 4.0) |
Recupera una subcadena de la instancia. |
trim |
String trim(value:String) |
trim($event.value.String) |
Devuelve una nueva cadena quitando todos los caracteres de espacio en blanco iniciales y finales de la cadena de entrada. |
indexOf |
Long indexOf(value:String, subString:String) |
indexOf($event.value.String, 'abc') |
Devuelve la primera aparición de la cadena especificada dentro de la cadena original, en función de la indexación cero. |
replace |
String replace(value:String, searchString:String, replaceString:String) |
replace($event.value.String, 'abc', 'xyz') |
Devuelve una cadena en la que todas las apariciones de la cadena de búsqueda se reemplazan por la cadena de reemplazo. |
Otras funciones
| Nombre de función | Firma | Ejemplo | Notas |
|---|---|---|---|
coalesce |
String, Long, Double, Bool coalesce (value: String, Long, Double, Bool) |
coalesce(toLong($event.value.Double), $event.value.Long) |
Devuelve el primer valor distinto de NULL de la lista de argumentos. Acepta al menos 2 y al máximo 64 argumentos, pero todos deben ser del mismo tipo de datos. |
iff |
String, Long, Double, Bool iff (predicate: bool, ifTrue: String, Long, Double, Bool, ifFalse: String, Long, Double, Bool) |
iff ($event.value.Double > 100, 'Good', 'Bad') |
Devuelve el segundo o tercer argumento en función de si el predicado resuelto en true (devuelve el segundo argumento) o false (devuelve el tercer argumento). El predicado debe ser una expresión booleana y los argumentos segundo y tercero deben ser del mismo tipo. |
Consulte también
Para más información sobre el registro de aplicaciones y el modelo de programación de Azure Active Directory, consulte Azure Active Directory para desarrolladores.
Para obtener información sobre los parámetros de solicitud y autenticación, lea Autenticación y autorización.
Entre las herramientas que ayudan a probar las solicitudes HTTP y las respuestas se incluyen:
Fiddler. Este proxy de depuración web gratuito puede interceptar las solicitudes REST, por lo que puede diagnosticar los mensajes de solicitud y respuesta HTTP.
JWT.io. Puede usar esta herramienta para volcar rápidamente las notificaciones en el token de portador y, a continuación, validar su contenido.
Postman. Se trata de una herramienta gratuita de prueba de solicitudes y respuestas HTTP para depurar las API REST.
Para más información sobre Azure Time Series Insights Gen2, revise la documentación de Gen2.