syntax Azure Time Series Insights Gen2 Time Series Expression

Artikel
08/05/2023

Übersicht

Time Series Expression (TSX) ist eine Zeichenfolgenbasierte Ausdruckssprache mit starker Eingabe. TSX wird verwendet, um die folgenden Entitäten in einer Zeitreihenabfrage darzustellen.

Filtern
value
Aggregation

Filterausdrücke

Filterausdrücke werden verwendet, um boolesche Klauseln darzustellen. Die folgende Tabelle enthält Beispiele für Filter:

TSX	BESCHREIBUNG
`$event.PointValue.Double = 3.14`	`true` für Ereignisse mit doppeltem PointValue gleich `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true`für Ereignisse, bei denen PointValue größer als und `3.14` Zeichenfolgen status `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` für Ereignisse mit einem Zeitstempel größer als `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` für Ereignisse mit PointValue gleich `true`

Wertausdrücke

Wertausdrücke werden verwendet, um den Wert für numerische und kategorische Variablen darzustellen. Ein Wertausdruck kann ein Eigenschaftenverweisausdruck vom Typ Double oder Long sein.

Beispiel:

TSX	Notizen
`$event.Temperature.Double`	Das letzte Token in einem Wertausdruck (in diesem Fall `Double`) wird als Type der Eigenschaft gelesen.
`$event.Temperature`	Der Typ wird als Double für eine Eigenschaft angenommen, auf die über ein einzelnes Token zugegriffen wird.
`$event['Temperature-Celsius']`	Verwenden sie `[` und `]` zum Escapen von Token mit Sonderzeichen. Verwenden Sie `\` außerdem innerhalb der Klammern, um die folgenden Zeichen zu escapen: `\` und `'`.
`$event.Temperature.Celsius.Double`	Verwenden Sie `.` , um auf geschachtelte Eigenschaften zuzugreifen. Beim Zugriff auf geschachtelte Eigenschaften ist der Typ erforderlich.
`$event.Temperature['Celsius-C'].Double`	Verwenden sie `[` und `]` zum Escapen von Token, die Sonderzeichen beim Zugriff auf geschachtelte Eigenschaften aufweisen. Verwenden Sie `\` außerdem innerhalb der Klammern, um die folgenden Zeichen zu escapen: `\` und `'`. Beim Zugriff auf geschachtelte Eigenschaften ist der Typ erforderlich.
`$event['Temperature']['Celsius'].Double`	Die Verwendung von und `]` zum Escapen von `[` Token ist für jedes Token zulässig.

Numerische Variablenart

Das Ergebnis des Wertausdrucks sollte vom Typ Double oder Long sein.

Aggregatvariablentyp

Das Ergebnis des Wertausdrucks kann von allen unterstützten Typen sein.

Kategorische Variablenart

Das Ergebnis des Wertausdrucks kann nur der Typ String oder Long sein.

Aggregationsausdrücke

Aggregatausdrücke werden verwendet, um den Aggregationsvorgang darzustellen, der für die Abfrage verwendet werden soll. Ein Aggregatausdruck führt zu einem einzelnen Wert für jedes Intervall. Aggregatausdrücke können auf numerische und Aggregatvariablen angewendet werden.

Aggregationsausdrücke : Numerische Variablenart

Numerische Variablen sollten auf $valueverweisen.

Hier sind die unterstützten Aggregatfunktionen.

Aggregatfunktion	Beispiel	BESCHREIBUNG
`min`	`min($value)`	Berechnet das Minimum des `$value` Intervalls. Vermeidet `null` Werte. Kann nicht mit Interpolation verwendet werden.
`max`	`max($value)`	Berechnet das Maximum des `$value` Intervalls. Vermeidet `null` Werte. Kann nicht mit Interpolation verwendet werden.
`sum`	`sum($value)`	Berechnet die Summe aller `$value` Ereignisse im Intervall. Vermeidet `null` Werte. Kann nicht mit Interpolation verwendet werden.
`avg`	`avg($value)`	Berechnet den Durchschnitt aller `$value` Ereignisse im Intervall. Vermeidet `null` Werte. Kann nicht mit Interpolation verwendet werden.
`first`	`first($value)`	Gibt `$value` das erste auftretende Ereignis im Intervall nach Ereigniszeitstempel zurück. Vermeidet `null`Werte nicht. Kann nicht mit Interpolation verwendet werden.
`last`	`last($value)`	Gibt `$value` das letzte auftretende Ereignis im Intervall nach Ereigniszeitstempel zurück. Vermeidet `null`Werte nicht. Kann nicht mit Interpolation verwendet werden.
`median`	`median($value)`	Gibt `$value` das mittlere Ereignis im Intervall nach Ereigniszeitstempel zurück. Vermeidet `null`Werte nicht. Kann nicht mit Interpolation verwendet werden.
`stdev`	`stdev($value)`	Gibt `$value` die Standardabweichung der Ereignisse im Intervall zurück. Vermeidet `null` Werte. Kann nicht mit Interpolation verwendet werden.
`twsum`	`twsum($value)`	Gibt `$value` die zeitgewichtete Summe der Ereignisse im Intervall zurück. Erfordert Interpolation.
`twavg`	`twavg($value)`	Gibt `$value` den zeitgewichteten Durchschnitt der Ereignisse im Intervall zurück. Erfordert Interpolation.
`left`	`left($value)`	Gibt den `$value` am linken Rand des angegebenen Intervalls zurück. Erfordert Interpolation.
`right`	`right($value)`	Gibt den `$value` am rechten Rand des angegebenen Intervalls zurück. Erfordert Interpolation.

Aggregationsausdrücke : Aggregatvariablentyp

Aggregatvariablen sollten auf eine Eigenschaft in der Ereignisnutzlast verweisen.

Hier sind die unterstützten Aggregatfunktionen.

Aggregate-Funktion	Beispiel	BESCHREIBUNG
`count`	`count()`	Gibt die Anzahl der Ereignisse pro Intervall zurück.
`min`	`min($event.Temperature.Double)`	Berechnet das Minimum der Eigenschaft Temperature pro Intervall. Vermeidet `null` Werte.
`max`	`max($event.Temperature.Long)`	Berechnet das Maximum der Eigenschaft Temperature pro Intervall. Vermeidet `null` Werte.
`sum`	`sum($event.Temperature.Double)`	Berechnet die Summe der Eigenschaft Temperature für alle Ereignisse im Intervall. Vermeidet `null` Werte.
`avg`	`avg($event.Temperature.Long)`	Berechnet den Durchschnitt der Eigenschaft Temperature für alle Ereignisse im Intervall. Vermeidet `null` Werte.
`first`	`first($event.Temperature.String)`	Gibt den ersten auftretenden Wert (nach Ereigniszeitstempel) der Eigenschaft Temperature aus allen Ereignissen im Intervall zurück. Vermeidet `null`Werte nicht.
`last`	`last($event.Temperature.String)`	Gibt den letzten (nach Ereigniszeitstempel) auftretenden Wert der Eigenschaft Temperature aus allen Ereignissen im Intervall zurück. Vermeidet Werte nicht`null`.
`median`	`median($event.Temperature.String)`	Gibt den mittleren (nach Ereigniszeitstempel) Wert der Eigenschaft Temperature aus allen Ereignissen im Intervall zurück. Vermeidet Werte nicht`null`.
`stdev`	`stdev($event.Temperature.String)`	Berechnet die Standardabweichung der Eigenschaft Temperature pro Intervall. Vermeidet `null` Werte.

Für einen Aggregatvariablentyp können diese Funktionen im Aggregatausdruck kombiniert werden. Beispiel: max($event.Temperature.Long) - min($event.Temperature.Long)

Syntax

In diesem Abschnitt werden grundlegende Syntaxkonzepte und Abfrageoperatoren beschrieben, die mit Formularausdrücken verkettet sind.

Unterstützte Literale

Hinweis

Die folgenden Literale werden zum Bilden von Ausdrücken verwendet. Die vollständige Liste der Datentypen finden Sie im Artikel Unterstützte Datentypen .

Primitiver Typ	Literale
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`

Unterstützte Operandentypen

Vorgang	Unterstützte Typen	Notizen
<, >, <, >	Double, Long, DateTime, TimeSpan
=, =, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> entspricht !=
+, -, *, /	Double, Long, DateTime, TimeSpan

Für Vergleichsausdrücke (<, >, <=, >=, =, !=) können die Operanden NULL oder vom gleichen Typ sein. In jedem Prädikatausdruck werden typen von linksseitigen (LHS) und right hand side (RHS) operanden überprüft, damit sie übereinstimmen. Fehler treten auf, wenn die Typen von LHS und RHS nicht übereinstimmen oder ein Vorgang für bestimmte Typen nicht zulässig ist.

Hinweis

Der Zeichenfolgentyp kann im warmen Speicher nicht NULL-Werte zulassen:

Der Vergleich von String mit NULL und leerer Zeichenfolge ('') verhält sich genauso: $event.p1.String = NULL entspricht $event.p1.String = ''.
Die API gibt möglicherweise NULL-Werte zurück, auch wenn die ursprünglichen Ereignisse leere Zeichenfolgen enthalten.

In Zukunft wird das gleiche Verhalten im Cold Store auftreten.

Nehmen Sie keine Abhängigkeit von NULL-Werten in String-Spalten an, und behandeln Sie sie genauso wie leere Zeichenfolgen.

Es wird eine Typprüfung angewendet:
- Jeder Eigenschaftstyp wird für ein NULL Literal akzeptiert.
- Die Typen von LHS und RHS sollten übereinstimmen.

Hier sind Beispiele für die Eigenschaften p1 und p2 des Typs String, eigenschaft p3 vom Typ Double und eine geschachtelte Eigenschaft, die als p4.p5 des Typs Double gespeichert ist:

Filter	Ist gültig?	Notizen
`$event.p1.String = 'abc'`	Ja
`$event.p1.String = $event.p2.String`	Ja
`$event.p1.String = NULL`	Ja	`NULL` entspricht jedem linken Typ.
`$event.p3.Double = 'abc'`	Nein	Typenkonflikt.
`$event.p3.Double = $event.p1.String`	Nein	Typenkonflikt.
`$event.p1 = 'abc'`	Nein	Typenkonflikt.
`$event.p1 = 1`	Nein	Typenkonflikt.
`$event.p1 = true`	Nein	Typenkonflikt.
`$event.p1 = NULL`	Ja	`p1` ist das einzige verwendete Token. Interpretiert als `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Ja	`['p1']` ist das einzige verwendete Token. Interpretiert als `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	Nein	Ungültige Eigenschaftsverweissyntax. Ein Typ muss für LHS des Vergleichs angegeben werden.
`$event.p4.p5.Double = 0.0`	Ja

Unterstützte Skalarfunktionen

Im Folgenden finden Sie eine Liste der Skalarfunktionen nach Kategorien:

Konvertierungsfunktionen

Funktionsname	Signatur	Beispiel	Notizen
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Konvertiert die Argumente in Double.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Konvertiert die Argumente in Long.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Konvertiert Argumente in String.

Mathematische Funktionen

Funktionsname	Signatur	Beispiel	Notizen
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Rundet eine gleitende Zahl mit doppelter Genauigkeit auf das nächste Integral.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Gibt den kleinsten integralen Wert zurück, der größer oder gleich der Gleitkommazahl mit doppelter Genauigkeit ist.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Gibt den größten integralen Wert zurück, der kleiner oder gleich der Gleitkommazahl mit doppelter Genauigkeit ist.

Trigonometrische Funktionen

Funktionsname	Signatur	Beispiel	Notizen
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Gibt den Kosinus des angegebenen Winkels im Bogenmaß zurück.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Gibt den Sinus des angegebenen Winkels im Bogenmaß zurück.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Gibt den Tangens des angegebenen Winkels im Bogenmaß zurück.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Gibt den Winkel im Bogenmaß zurück, dessen Kosinus die angegebene Zahl ist.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Gibt den Winkel im Bogenmaß zurück, dessen Sinus die angegebene Zahl ist.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Gibt den Winkel im Bogenmaß zurück, dessen Tangens die angegebene Zahl ist.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Gibt den Winkel im Bogenmaß zurück, dessen Tangens der Quotient von zwei angegebenen Zahlen ist.

Logarithmische Funktionen

Funktionsname	Signatur	Beispiel	Notizen
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Gibt den natürlichen Logarithmus einer angegebenen Zahl zurück.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Gibt den Logarithmus einer angegebenen Zahl zur Basis 2 zurück.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Gibt den Logarithmus einer angegebenen Zahl zur Basis 10 zurück.

DateTime-Funktionen

Funktionsname	Signatur	Beispiel	Notizen
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Gibt den Monat des Jahres als numerischer Wert für die angegebene DateTime zurück.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Gibt den Tag des Monats als numerischer Wert für die angegebene DateTime zurück.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Gibt die Stunde des Tages als numerischer Wert für die angegebene DateTime zurück.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Gibt die aktuelle Uhrzeit im UTC-Format zurück.

Zeichenfolgenfunktionen

Funktionsname	Signatur	Beispiel	Notizen
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Gibt eine in Großbuchstaben konvertierte Eingabezeichenfolge zurück.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Gibt eine in Kleinbuchstaben konvertierte Eingabezeichenfolge zurück.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Gibt die Anzahl der Zeichen im Zeichenfolgenargument zurück.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Verkettet zwei angegebene Eingabezeichenfolgen.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Ruft eine Teilzeichenfolge dieser Instanz ab.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Gibt eine neue Zeichenfolge zurück, indem alle führenden und nachfolgenden Leerzeichen aus der Eingabezeichenfolge entfernt werden.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Gibt das erste Vorkommen der angegebenen Zeichenfolge innerhalb der ursprünglichen Zeichenfolge zurück, basierend auf der Nullindizierung.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Gibt eine Zeichenfolge zurück, bei der alle Vorkommen der Suchzeichenfolge durch die Ersetzungszeichenfolge ersetzt werden.

Weitere Funktionen

Funktionsname	Signatur	Beispiel	Notizen
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Gibt den ersten ungleich NULL-Wert in der Argumentliste zurück. Akzeptiert mindestens 2 und maximal 64 Argumente, aber sie müssen alle denselben Datentyp aufweisen.
`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')`	Gibt das zweite oder dritte Argument zurück, je nachdem, ob das Prädikat in TRUE (gibt das zweite Argument zurück) oder false (das dritte Argument zurückgibt) aufgelöst wurde. Das Prädikat muss ein boolescher Ausdruck sein, und das zweite und das dritte Argument müssen vom gleichen Typ sein.

Weitere Informationen

Weitere Informationen zur Anwendungsregistrierung und zum Azure Active Directory-Programmiermodell finden Sie unter Azure Active Directory für Entwickler.
Informationen zu Anforderungs- und Authentifizierungsparametern finden Sie unter Authentifizierung und Autorisierung.
Zu den Tools, die beim Testen von HTTP-Anforderungen und -Antworten helfen, gehören:
Fiddler. Dieser kostenlose Webdebugproxy kann Ihre REST-Anforderungen abfangen, sodass Sie die HTTP-Anforderung und -Antwortnachrichten diagnostizieren können.
JWT.io. Sie können dieses Tool verwenden, um die Ansprüche in Ihrem Bearertoken schnell abzuspeichern und dann deren Inhalt zu überprüfen.
Postman. Dies ist ein kostenloses HTTP-Anforderungs- und Antworttesttool zum Debuggen von REST-APIs.
Weitere Informationen zu Azure Time Series Insights Gen2 finden Sie in der Gen2-Dokumentation.