sintaxe da Expressão da Série Temporal Azure Time Series Insights Gen2

Artigo
08/05/2023

Descrição Geral

O Time Series Expression (TSX) é uma linguagem de expressão baseada em cadeias com escrita forte. O TSX é utilizado para representar as seguintes entidades numa Consulta de Série Temporal.

Filtro
Valor
Agregação

Filtrar expressões

As expressões de filtro são utilizadas para representar cláusulas booleanas. A tabela seguinte lista exemplos de filtros:

TSX	Description
`$event.PointValue.Double = 3.14`	`true` para eventos com PointValue duplo igual a `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true` para eventos com PointValue maior do que `3.14` e estado da cadeia `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` para eventos com um carimbo de data/hora superior a `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` para eventos com PointValue igual a `true`

Expressões de valor

As expressões de valor são utilizadas para ilustrar o valor das variáveis numéricas e categóricas. Uma expressão de valor pode ser uma expressão de referência de propriedade do tipo Duplo ou Longo.

Por exemplo:

TSX	Notas
`$event.Temperature.Double`	O último token em qualquer expressão de valor (neste caso `Double`) é lido como o Tipo da propriedade.
`$event.Temperature`	Presume-se que o tipo é Duplo para uma propriedade acedida por um único token.
`$event['Temperature-Celsius']`	Utilize `[` e `]` para escapar a tokens com carateres especiais. Além disso, utilize `\` entre parênteses para escapar aos seguintes carateres: `\` e `'`.
`$event.Temperature.Celsius.Double`	Utilizado `.` para aceder a propriedades aninhadas. Ao aceder a propriedades aninhadas, é necessário o Tipo.
`$event.Temperature['Celsius-C'].Double`	Utilize `[` e `]` para escapar a tokens com carateres especiais ao aceder a propriedades aninhadas. Além disso, utilize `\` entre parênteses para escapar aos seguintes carateres: `\` e `'`. Ao aceder a propriedades aninhadas, é necessário o Tipo.
`$event['Temperature']['Celsius'].Double`	A utilização de `[` e `]` para escapar a tokens é permitida em qualquer token.

Tipo de variável numérica

O resultado da expressão de valor deve ser do tipo Duplo ou Longo .

Tipo de variável de agregação

O resultado da expressão de valor pode ser de todos os tipos suportados.

Tipo de variável categórica

O resultado da expressão de valor só pode ser Cadeia ou Tipo longo .

Expressões de agregação

As expressões de agregação são utilizadas para ilustrar a operação de agregação a utilizar na consulta. Uma expressão agregada resulta num único valor para cada intervalo. As expressões de agregação podem ser aplicadas em variáveis numéricas e agregadas.

Expressões de agregação – tipo de variável numérica

As variáveis numéricas devem referir-se a $value.

Eis as funções de agregação suportadas.

Função agregar	Exemplo	Descrição
`min`	`min($value)`	Calcula o mínimo do `$value` por intervalo. `null` Evita valores. Não é possível utilizar com a interpolação.
`max`	`max($value)`	Calcula o máximo de `$value` por intervalo. `null` Evita valores. Não é possível utilizar com a interpolação.
`sum`	`sum($value)`	Calcula a soma de `$value` todos os eventos no intervalo. `null` Evita valores. Não é possível utilizar com a interpolação.
`avg`	`avg($value)`	Calcula a média de mais de `$value` todos os eventos no intervalo. `null` Evita valores. Não é possível utilizar com a interpolação.
`first`	`first($value)`	Devolve `$value` o primeiro evento que ocorre no intervalo por carimbo de data/hora do evento. Não evita`null` valores. Não é possível utilizar com a interpolação.
`last`	`last($value)`	Devolve `$value` o último evento que ocorre no intervalo por carimbo de data/hora do evento. Não evita`null` valores. Não é possível utilizar com a interpolação.
`median`	`median($value)`	Devolve `$value` o evento intermédio no intervalo por carimbo de data/hora do evento. Não evita`null` valores. Não é possível utilizar com a interpolação.
`stdev`	`stdev($value)`	Devolve `$value` o desvio padrão dos eventos no intervalo. `null` Evita valores. Não é possível utilizar com a interpolação.
`twsum`	`twsum($value)`	Devolve `$value` a soma ponderada do tempo dos eventos no intervalo. Requer interpolação.
`twavg`	`twavg($value)`	Devolve `$value` a média ponderada do tempo dos eventos no intervalo. Requer interpolação.
`left`	`left($value)`	Devolve o `$value` no limite esquerdo do intervalo especificado. Requer interpolação.
`right`	`right($value)`	Devolve o `$value` no limite direito do intervalo especificado. Requer interpolação.

Expressões de agregação – tipo de variável de agregação

As variáveis de agregação devem referir-se a uma Propriedade no payload de eventos.

Eis as funções de agregação suportadas.

Função agregar	Exemplo	Descrição
`count`	`count()`	Devolve o número de eventos por intervalo.
`min`	`min($event.Temperature.Double)`	Calcula o mínimo da propriedade Temperatura por intervalo. `null` Evita valores.
`max`	`max($event.Temperature.Long)`	Calcula o máximo da propriedade Temperatura por intervalo. `null` Evita valores.
`sum`	`sum($event.Temperature.Double)`	Calcula a soma da propriedade Temperatura em todos os eventos no intervalo. `null` Evita valores.
`avg`	`avg($event.Temperature.Long)`	Calcula a média da propriedade Temperatura em todos os eventos no intervalo. `null` Evita valores.
`first`	`first($event.Temperature.String)`	Devolve o primeiro valor que ocorre (por carimbo de data/hora do evento) da propriedade Temperatura de todos os eventos no intervalo. Não evita`null` valores.
`last`	`last($event.Temperature.String)`	Devolve o último valor (por carimbo de data/hora do evento) da propriedade Temperatura de todos os eventos no intervalo. Não evita`null` valores.
`median`	`median($event.Temperature.String)`	Devolve o valor médio (por carimbo de data/hora do evento) da propriedade Temperatura de todos os eventos no intervalo. Não evita`null` valores.
`stdev`	`stdev($event.Temperature.String)`	Calcula o desvio padrão da propriedade Temperatura por intervalo. `null` Evita valores.

Para um tipo de variável de agregação , estas funções podem ser combinadas na expressão agregada. Por exemplo: max($event.Temperature.Long) - min($event.Temperature.Long).

Syntax

Esta secção descreve os principais conceitos de sintaxe e operadores de consulta que são concatenados para expressões de formulário.

Literais suportados

Nota

Os literais abaixo são utilizados para formar expressões. Veja o artigo Tipos de dados suportados para obter a lista completa de tipos de dados.

Tipo primitivo	Literais
Bool	`TRUE`, `FALSE`
DateTime	`dt'2016-10-08T03:22:55.3031599Z'`
Duplo	`1.23`, `1.0`
Longo	`1`, `6`
String	`'abc'`
TimeSpan	`ts'P1Y2M3DT4M5.67S'`
Null	`NULL`

Tipos de operando suportados

Operação	Tipos suportados	Notas
<, >, <=, >=	Duplo, Longo, DateTime, TimeSpan
=, !=, <>	Duplo, Longo, Cadeia, Bool, DateTime, TimeSpan, NULL	<> é equivalente a !=
+, -, *, /	Duplo, Longo, DateTime, TimeSpan

Para expressões de comparação (<, >, <=, >=, =, !=), os operandos podem ser NULL ou ser do mesmo tipo. Em cada expressão de predicado, os tipos de operandos do lado esquerdo (LHS) e do lado direito (RHS) são validados para corresponder. Os erros ocorrem quando os tipos de LHS e RHS não concordam ou não é permitida uma operação em determinados tipos.

Nota

O tipo de cadeia não é anulável no Arquivo Quente:

A comparação da Cadeia com NULL e da cadeia vazia ('') comporta-se da mesma forma: $event.p1.String = NULL é equivalente a $event.p1.String = ''.
A API pode devolver valores NULL , mesmo que os eventos originais contenham cadeias vazias.

No futuro, o mesmo comportamento será na Cold Store.

Não assuma a dependência dos valores NULL nas colunas Cadeia e trate-os da mesma forma que as cadeias vazias.

É aplicada uma verificação de tipo:
- Qualquer tipo de propriedade é aceite num NULL literal.
- Os tipos de LHS e RHS devem corresponder.

Eis exemplos de propriedades p1 e p2 do tipo Cadeia, propriedade p3 do tipo Duplo e uma propriedade aninhada armazenada como p4.p5 do tipo Duplo:

Filtro	É válido?	Notas
`$event.p1.String = 'abc'`	Yes
`$event.p1.String = $event.p2.String`	Yes
`$event.p1.String = NULL`	Yes	`NULL` corresponde a qualquer tipo do lado esquerdo.
`$event.p3.Double = 'abc'`	No	Erro de correspondência do tipo.
`$event.p3.Double = $event.p1.String`	No	Erro de correspondência do tipo.
`$event.p1 = 'abc'`	No	Erro de correspondência do tipo.
`$event.p1 = 1`	No	Erro de correspondência do tipo.
`$event.p1 = true`	No	Erro de correspondência do tipo.
`$event.p1 = NULL`	Yes	`p1` é o único token utilizado. Interpretado como `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Yes	`['p1']` é o único token utilizado. Interpretado como `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	No	Sintaxe de referência de propriedade inválida. Tem de ser especificado um tipo em LHS de comparação.
`$event.p4.p5.Double = 0.0`	Yes

Funções escalares suportadas

Segue-se a lista de funções escalares por categorias:

Funções de conversão

Nome da função	Assinatura	Exemplo	Notas
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Converte os argumentos em Duplo.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Converte os argumentos em Longo.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Converte argumentos em Cadeia.

Funções matemáticas

Nome da função	Assinatura	Exemplo	Notas
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Arredonda um número flutuante de precisão dupla para o integral mais próximo.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Devolve o menor valor integral maior ou igual a número de vírgula flutuante de precisão dupla.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Devolve o maior valor integral que é menor ou igual a número de vírgula flutuante de precisão dupla.

Funções trigonométricas

Nome da função	Assinatura	Exemplo	Notas
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Devolve o Cosseno do ângulo especificado em radianos.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Devolve o Seno do ângulo especificado em radianos.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Devolve a Tangente do ângulo especificado em radianos.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Devolve o ângulo em radianos cujo Cosseno é o número especificado.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Devolve o ângulo em radianos cujo Seno é o número especificado.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Devolve o ângulo em radianos cuja Tangente é o número especificado.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Devolve o ângulo em radianos cuja Tangente é o quociente de dois números especificados.

Funções logarítmicas

Nome da função	Assinatura	Exemplo	Notas
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Devolve o logaritmo natural de um número especificado.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Devolve o logaritmo base 2 de um número especificado.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Devolve o logaritmo base 10 de um número especificado.

Funções DateTime

Nome da função	Assinatura	Exemplo	Notas
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Devolve o mês do ano como numérico para o DateTime fornecido.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Devolve o dia do mês como numérico para o DateTime fornecido.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Devolve a hora do dia como numérica para o DateTime fornecido.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Devolve a hora atual no formato UTC.

Funções de cadeia

Nome da função	Assinatura	Exemplo	Notas
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Devolve a cadeia de entrada convertida em maiúsculas.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Devolve a cadeia de entrada convertida em minúsculas.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Devolve o número de carateres no argumento de cadeia.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Concatena duas cadeias de entrada especificadas.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Obtém uma subcadeia desta instância.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Devolve uma nova cadeia ao remover todos os carateres de espaço em branco à esquerda e à direita da cadeia de entrada.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Devolve a primeira ocorrência da cadeia especificada na cadeia original, com base na indexação zero.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Devolve uma cadeia onde todas as ocorrências da cadeia de pesquisa são substituídas pela cadeia de substituição.

Outras Funções

Nome da função	Assinatura	Exemplo	Notas
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Devolve o primeiro valor não nulo na lista de argumentos. Aceita no mínimo 2 e no máximo 64 argumentos, mas têm de ser todos do mesmo tipo de dados.
`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')`	Devolve o segundo ou terceiro argumento consoante o predicado seja resolvido como verdadeiro (devolve o segundo argumento) ou falso (devolve o terceiro argumento). O predicado tem de ser uma expressão booleana e o segundo e terceiro argumentos têm de ser do mesmo tipo.

Ver também

Para obter mais informações sobre o registo de aplicações e o modelo de programação do Azure Active Directory, veja Azure Active Directory para programadores.
Para saber mais sobre os parâmetros de pedido e autenticação, leia Autenticação e autorização.
As ferramentas que ajudam a testar pedidos e respostas HTTP incluem:
Fiddler. Este proxy de depuração Web gratuito pode intercetar os seus pedidos REST, para que possa diagnosticar as mensagens de pedido e resposta HTTP.
JWT.io. Pode utilizar esta ferramenta para capturar rapidamente as afirmações no token de portador e, em seguida, validar os respetivos conteúdos.
Postman. Esta é uma ferramenta de teste de resposta e pedido HTTP gratuita para depurar APIs REST.
Saiba mais sobre Azure Time Series Insights Gen2 ao rever a documentação do Gen2.

Partilhar via