你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 时序见解 Gen2 时序表达式语法

2023-08-05

概述

时序表达式 (TSX) 是基于字符串的表达式语言，具有强类型。 TSX 用于表示时序查询中的以下实体。

“筛选器”
值
聚合

筛选表达式

筛选器表达式 用于表示布尔子句。下表列出了筛选器的示例：

Tsx	说明
`$event.PointValue.Double = 3.14`	`true` 对于双 PointValue 等于的事件 `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true` 对于 PointValue 大于 `3.14` 且字符串状态的事件 `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` 对于时间戳大于的事件 `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` 对于 PointValue 等于的事件 `true`

值表达式

值表达式 用于描述数值和分类变量的值。值表达式可以是 Double 或 Long 类型的属性引用表达式。

例如：

Tsx	说明
`$event.Temperature.Double`	在本例 `Double` 中，任何值表达式 (的最后一个标记) 将作为属性的 Type 读取。
`$event.Temperature`	假定单个令牌访问的属性的类型为 Double 。
`$event['Temperature-Celsius']`	使用 `[` 和 `]` 对具有特殊字符的令牌进行转义。此外，在括号内使用 `\` 来转义以下字符： `\` 和 `'`。
`$event.Temperature.Celsius.Double`	使用 `.` 访问嵌套属性。访问嵌套属性时，类型是必需的。
`$event.Temperature['Celsius-C'].Double`	使用 `[` 和 `]` 在访问嵌套属性时转义具有特殊字符的令牌。此外，在括号内使用 `\` 来转义以下字符： `\` 和 `'`。访问嵌套属性时，类型是必需的。
`$event['Temperature']['Celsius'].Double`	`[`允许在任何令牌上使用和 `]` 进行转义令牌。

数值变量类型

值表达式的结果应为 Double 或 Long 类型。

聚合变量类型

值表达式的结果可以是任何受支持的类型。

分类变量类型

值表达式的结果只能是 String 或 Long 类型。

聚合表达式

聚合表达式 用于描述要用于查询的聚合操作。聚合表达式为每个间隔生成一个值。聚合表达式可以应用于数值变量和聚合变量。

聚合表达式 - 数值变量类型

数值变量应引用 $value。

下面是支持的聚合函数。

Aggregate 函数	示例	说明
`min`	`min($value)`	计算每个间隔的 `$value` 最小值。避免值 `null` 。不能与内插一起使用。
`max`	`max($value)`	计算每个间隔的 `$value` 最大值。避免值 `null` 。不能与内插一起使用。
`sum`	`sum($value)`	计算间隔内所有事件的总和 `$value` 。避免值 `null` 。不能与内插一起使用。
`avg`	`avg($value)`	计算间隔内所有事件的平均值 `$value` 。避免值 `null` 。不能与内插一起使用。
`first`	`first($value)`	`$value`按事件时间戳返回间隔内发生的第一个事件。不避免`null`值。不能与内插一起使用。
`last`	`last($value)`	`$value`按事件时间戳返回间隔内最后一个发生的事件。不避免`null`值。不能与内插一起使用。
`median`	`median($value)`	`$value`按事件时间戳返回间隔中的中间事件。不避免`null`值。不能与内插一起使用。
`stdev`	`stdev($value)`	返回 `$value` 间隔中事件的标准偏差。避免值 `null` 。不能与内插一起使用。
`twsum`	`twsum($value)`	返回 `$value` 间隔中事件的时间加权总和。需要内插。
`twavg`	`twavg($value)`	返回 `$value` 间隔中事件的时间加权平均值。需要内插。
`left`	`left($value)`	返回 `$value` 给定间隔左边缘的。需要内插。
`right`	`right($value)`	返回 `$value` 给定间隔右边缘的。需要内插。

聚合表达式 - 聚合变量类型

聚合变量 应引用事件有效负载中的 Property。

下面是支持的聚合函数。

聚合函数	示例	说明
`count`	`count()`	返回每个间隔的事件数。
`min`	`min($event.Temperature.Double)`	计算每个间隔的 “温度 ”属性的最小值。避免值 `null` 。
`max`	`max($event.Temperature.Long)`	计算每个间隔的 “温度 ”属性的最大值。避免值 `null` 。
`sum`	`sum($event.Temperature.Double)`	计算间隔中所有事件属性 Temperature 的总和。避免值 `null` 。
`avg`	`avg($event.Temperature.Long)`	计算间隔内所有事件的 “温度 ”属性的平均值。避免值 `null` 。
`first`	`first($event.Temperature.String)`	从间隔内的所有事件中，按事件时间戳返回第一个 (，) 属性 Temperature 的值。不避免`null`值。
`last`	`last($event.Temperature.String)`	从间隔内的所有事件返回最后一个 (事件时间戳) 属性 Temperature 的值。不避免`null`值。
`median`	`median($event.Temperature.String)`	从间隔内的所有事件返回 (中间发生的事件时间戳) 属性 Temperature 的值。不避免`null`值。
`stdev`	`stdev($event.Temperature.String)`	计算每个间隔的 “温度 ”属性的标准偏差。避免值 `null` 。

对于 聚合变量 类型，可以在 聚合表达式中组合这些函数。例如：max($event.Temperature.Long) - min($event.Temperature.Long)。

语法

本节介绍连接到表单表达式的核心语法概念和查询运算符。

支持的文本

注意

下面的文本用于形成表达式，有关数据类型的完整列表，请参阅支持的数据类型一文。

基元类型	文本
Bool	`TRUE`, `FALSE`
DateTime	`dt'2016-10-08T03:22:55.3031599Z'`
双精度	`1.23`, `1.0`
Long	`1`, `6`
字符串	`'abc'`
TimeSpan	`ts'P1Y2M3DT4M5.67S'`
Null	`NULL`

支持的操作数类型

操作	支持的类型	注释
<、>、<、>	Double、 Long、 DateTime、 TimeSpan
=、=、<>	Double、 Long、 String、 Bool、 DateTime、 TimeSpan、 NULL	<> 等效于！=
+, -, *, /	Double、 Long、 DateTime、 TimeSpan

对于 (<、、>=<、=、>=！=) 的比较表达式，操作数可以为 NULL 或属于同一类型。在每个谓词表达式中，将验证左侧 (LHS) 和右侧 (RHS) 操作数的类型是否匹配。如果 LHS 和 RHS 类型不一致，或者不允许对特定类型执行操作，则会发生错误。

注意

字符串 类型在暖存储中不可为 null：

字符串与 NULL 和空字符串 (“”) 的比较行为方式相同： $event.p1.String = NULL 等效于 $event.p1.String = ''。
即使原始事件包含空字符串，API 也可能返回 NULL 值。

将来，冷存储上将发生相同的行为。

不要依赖字符串列中的 NULL 值，并像对待空字符串一样对待它们。

应用类型检查：
- 接受针对 NULL 文本的任何属性类型。
- LHS 和 RHS 的类型应匹配。

下面是 String 类型的属性 p1 和 p2、Double 类型的属性 p3 以及存储为 Double 类型的 p4.p5 的嵌套属性的示例：

筛选器	是否有效？	说明
`$event.p1.String = 'abc'`	是
`$event.p1.String = $event.p2.String`	是
`$event.p1.String = NULL`	是	`NULL` 匹配任何左侧类型。
`$event.p3.Double = 'abc'`	否	类型不匹配。
`$event.p3.Double = $event.p1.String`	否	类型不匹配。
`$event.p1 = 'abc'`	否	类型不匹配。
`$event.p1 = 1`	否	类型不匹配。
`$event.p1 = true`	否	类型不匹配。
`$event.p1 = NULL`	是	`p1` 是唯一使用的标记。解释为 `$event.p1.Double = NULL`
`$event['p1'] != NULL`	是	`['p1']` 是唯一使用的标记。解释为 `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	否	无效的属性引用语法。必须在比较的 LHS 上指定类型。
`$event.p4.p5.Double = 0.0`	是

支持的标量函数

下面是按类别列出的标量函数列表：

转换函数

函数名称	签名	示例	说明
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	将参数转换为 Double。
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	将参数转换为 Long。
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	将参数转换为字符串。

数学函数

函数名称	签名	示例	说明
`round`	`Double round(value:Double)`	`round($event.value.Double)`	将双精度浮点数舍入到最接近的整数。
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	返回大于或等于双精度浮点数的最小整数值。
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	返回小于或等于双精度浮点数的最大整数值。

三角函数

函数名称	签名	示例	说明
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	以弧度为单位返回指定角度的余弦值。
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	以弧度为单位返回指定角度的正弦值。
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	以弧度为单位返回指定角度的正切值。
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	以弧度为单位返回其余弦为指定数的角度。
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	以弧度为单位返回角度，其正弦值是指定数字。
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	以弧度为单位返回其正切数为指定数字的角度。
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	返回以弧度为单位的角度，其正切是两个指定数字的商。

对数函数

函数名称	签名	示例	说明
`log`	`Double log(value:Double)`	`log($event.value.Double)`	返回指定数字的自然对数。
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	返回指定数字以 2 为底的对数。
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	返回指定数字以 10 为底的对数。

日期时间函数

函数名称	签名	示例	说明
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	返回一年中的月份作为提供的 DateTime 的数值。
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	返回一个月中的某一天作为提供的 DateTime 的数值。
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	返回一天中的小时作为提供的 DateTime 的数值。
`utcNow`	`DateTime utcNow()`	`utcNow()`	返回 UTC 格式的当前时间。

字符串函数

函数名称	签名	示例	说明
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	返回转换为大写的输入字符串。
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	返回转换为小写的输入字符串。
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	返回字符串参数中的字符数。
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	连接两个指定的输入字符串。
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	从此实例检索子字符串。
`trim`	`String trim(value:String)`	`trim($event.value.String)`	通过从输入字符串中删除所有前导空格和尾随空格字符来返回新字符串。
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	基于零索引返回原始字符串中指定字符串的第一个匹配项。
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	返回一个字符串，其中搜索字符串的所有匹配项都替换为替换字符串。

其他函数

函数名称	签名	示例	说明
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	返回参数列表中的第一个非 null 值。至少接受 2 个参数，最多接受 64 个参数，但它们必须全部属于同一数据类型。
`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')`	返回第二个或第三个参数，具体取决于解析为 true 的谓词是 (返回第二个参数) 还是 false (返回第三个参数) 。谓词必须是布尔表达式，第二个和第三个参数的类型必须相同。

另请参阅

有关应用程序注册和 Azure Active Directory 编程模型的详细信息，请参阅面向开发人员的 Azure Active Directory。
若要了解请求和身份验证参数，请阅读身份验证和授权。
帮助测试 HTTP 请求和响应的工具包括：
菲德勒此免费的 Web 调试代理可以截获 REST 请求，因此你可以诊断 HTTP 请求和响应消息。
JWT.io。可以使用此工具在持有者令牌中快速转储声明，然后验证其内容。
Postman。这是一个免费的 HTTP 请求和响应测试工具，用于调试 REST API。
查看 Gen2 文档，详细了解 Azure 时序见解 Gen2。

通过