Azure 時間序列深入解析 Gen2 時間序列運算式語法
概觀
時間序列運算式 (TSX) 是以字串為基礎的運算式語言，具有強型別。 TSX 用來代表 時間序列查詢中的下列實體。
- 篩選
- 值
- 彙總
篩選運算式
篩選運算式 是用來表示布林子句。 下表列出篩選準則的範例：
| Tsx | Description |
|---|---|
$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 |
使用 . 存取巢狀屬性。 存取巢狀屬性時， 需要Type。 |
$event.Temperature['Celsius-C'].Double |
使用 [ 和 ] 來逸出存取巢狀屬性時具有特殊字元的權杖。 此外，請在括弧內使用 \ ，以逸出下列字元： \ 和 ' 。 存取巢狀屬性時， 需要Type。 |
$event['Temperature']['Celsius'].Double |
[允許在任何權杖上使用 和 ] 來逸出權杖。 |
數值變數種類
值運算式的結果應該是 Double 或 Long 類型。
匯總變數種類
值運算式的結果可以是任何支援的型別。
類別變數種類
值運算式的結果只能是 String 或 Long 類型。
彙總運算式
匯總運算式 是用來描述要用於查詢的匯總作業。 匯總運算式會產生每個間隔的單一值。 匯總運算式可以套用在數值和匯總變數上。
匯總運算式 - 數值變數種類
數值變數應該參考 $value 。
以下是支援的彙總函式。
| 彙總函式 | 範例 | 描述 |
|---|---|---|
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 回指定間隔右邊緣的 。 需要插補。 |
匯總運算式 - 匯總變數種類
匯總變數 應該參考事件承載中的屬性。
以下是支援的彙總函式。
| 彙總函式 | 範例 | 描述 |
|---|---|---|
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) |
計算間隔中所有事件 之 Temperature 屬性的平均值。 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)。
Syntax
本節描述串連至表單運算式的核心語法概念和查詢運算子。
支援的常值
注意
以下常值可用來形成運算式，請參閱 支援的資料類型 一文，以取得資料類型的完整清單。
| 基本型別 | 常值 |
|---|---|
| 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 |
支援的運算元類型
| 作業 | 支援的類型 | 備註 |
|---|---|---|
| <><=>= | 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 值。
未來，相同的行為將會在冷存放區上。
請勿相依于String資料行中的Null值，並將它們視為空字串。
- 套用類型檢查：
- 任何屬性類型都是針對
NULL常值接受。 - LHS 和 RHS 的類型應該相符。
- 任何屬性類型都是針對
以下是類型為 String的屬性p1和p2的範例、Double類型的屬性p3，以及儲存為Double類型的p4.p5巢狀屬性：
| 篩選 | 有效嗎？ | 附註 |
|---|---|---|
$event.p1.String = 'abc' |
是 | |
$event.p1.String = $event.p2.String |
Yes | |
$event.p1.String = NULL |
Yes | NULL 符合任何左側類型。 |
$event.p3.Double = 'abc' |
No | 型別不符。 |
$event.p3.Double = $event.p1.String |
No | 型別不符。 |
$event.p1 = 'abc' |
No | 型別不符。 |
$event.p1 = 1 |
No | 型別不符。 |
$event.p1 = true |
No | 型別不符。 |
$event.p1 = NULL |
Yes | p1 是唯一使用的權杖。 解譯為 $event.p1.Double = NULL |
$event['p1'] != NULL |
Yes | ['p1'] 是唯一使用的權杖。 解譯為 $event['p1'].Double != NULL |
$event.p4.p5 = 0.0 |
No | 不正確屬性參考語法。 必須在比較的 LHS 上指定類型。 |
$event.p4.p5.Double = 0.0 |
Yes |
支援的純量函式
以下是依類別排序的純量函式清單：
轉換函數
| 函式名稱 | 簽名 | 範例 | 注意 |
|---|---|---|---|
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) |
將引數轉換成 String。 |
數學函數
| 函式名稱 | 簽名 | 範例 | 注意 |
|---|---|---|---|
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 為底數的對數。 |
DateTime 函數
| 函式名稱 | 簽名 | 範例 | 注意 |
|---|---|---|---|
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 要求和回應的工具組括：
Fiddler。 這個免費的 Web 偵錯 Proxy 可以攔截您的 REST 要求，以便診斷 HTTP 要求和回應訊息。
JWT.io。 您可以使用此工具，快速傾印持有人權杖中的宣告，然後驗證其內容。
Postman。 這是免費的 HTTP 要求和回應測試控管來偵錯 REST API。
檢閱Gen2 檔，以深入瞭解 Azure 時間序列深入解析 Gen2。