sintaxe da Expressão da Série Temporal Azure Time Series Insights Gen2
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 evitanull 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 evitanull 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 evitanull 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 evitanull 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 evitanull 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 evitanull 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
NULLliteral. - Os tipos de LHS e RHS devem corresponder.
- Qualquer tipo de propriedade é aceite num
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.