składnia wyrażeń szeregów czasowych Azure Time Series Insights Gen2

Omówienie

Time Series Expression (TSX) to język wyrażeń oparty na ciągach z silnym wpisywaniem. Język TSX służy do reprezentowania następujących jednostek w zapytaniu szeregów czasowych.

• Filtr
• Wartość
• Agregacja

Wyrażenia filtru

Wyrażenia filtru są używane do reprezentowania klauzul logicznych. W poniższej tabeli wymieniono przykłady filtrów:

TSX	Opis
$event.PointValue.Double = 3.14	true dla zdarzeń o podwójnej wartości PointValue równej 3.14
$event.PointValue > 3.14 AND $event.Status.String = 'Good'	true dla zdarzeń o wartości PointValue większej niż 3.14 i stanu ciągu Good
$event.$ts > dt'2018-11-01T02:03:45Z'	true dla zdarzeń z sygnaturą czasową większą niż 2018-11-01T02:03:45Z
$event.PointEval.Bool = true	true dla zdarzeń o wartości PointValue równej true

Wyrażenia wartości

Wyrażenia wartości są używane do przedstawiania wartości zmiennych liczbowych i kategorii. Wyrażenie wartości może być wyrażeniem odwołania do właściwości typu Double lub Long.

Przykład:

TSX	Uwagi
$event.Temperature.Double	Ostatni token w dowolnym wyrażeniu wartości (w tym przypadku Double) jest odczytywany jako typ właściwości.
$event.Temperature	Przyjmuje się, że typ ma wartość Podwójna dla właściwości dostępnej przez pojedynczy token.
$event['Temperature-Celsius']	Użyj znaków [ i ] do ucieczki tokenów, które mają znaki specjalne. Ponadto użyj \ w nawiasach kwadratowych znaków ucieczki od następujących znaków: \ i '.
$event.Temperature.Celsius.Double	Użyj polecenia . , aby uzyskać dostęp do właściwości zagnieżdżonych. Podczas uzyskiwania dostępu do właściwości zagnieżdżonych wymagany jest typ.
$event.Temperature['Celsius-C'].Double	Użyj poleceń [ i ] do ucieczki tokenów, które mają znaki specjalne podczas uzyskiwania dostępu do właściwości zagnieżdżonych. Ponadto użyj \ w nawiasach kwadratowych znaków ucieczki od następujących znaków: \ i '. Podczas uzyskiwania dostępu do właściwości zagnieżdżonych wymagany jest typ.
$event['Temperature']['Celsius'].Double	Korzystanie z tokenów [ i ] na potrzeby ucieczki tokenów jest dozwolone na dowolnym tokenie.

Rodzaj zmiennej liczbowej

Wynik wyrażenia wartości powinien mieć typ Double lub Long .

Rodzaj zmiennej agregacji

Wynik wyrażenia wartości może być dowolnego obsługiwanego typu.

Rodzaj zmiennej podzielonej na kategorie

Wynikiem wyrażenia wartości może być tylko ciąg lub typ Długi .

Wyrażenia agregacji

Wyrażenia agregujące służą do przedstawiania operacji agregacji, która ma być używana w zapytaniu. Wyrażenie agregacji powoduje pojedynczą wartość dla każdego interwału. Wyrażenia agregacji można stosować w zmiennych liczbowych i agregowanych.

Wyrażenia agregacji — rodzaj zmiennej liczbowej

Zmienne liczbowe powinny odwoływać się do $value.

Oto obsługiwane funkcje agregujące.

Funkcja agregacji	Przykład	Opis
min	min($value)	Oblicza minimalną wartość interwału $value . null Unika wartości. Nie można używać z interpolacją.
max	max($value)	Oblicza maksymalną wartość interwału $value . null Unika wartości. Nie można używać z interpolacją.
sum	sum($value)	Oblicza sumę $value wszystkich zdarzeń w interwale. null Unika wartości. Nie można używać z interpolacją.
avg	avg($value)	Oblicza średnią $value dla wszystkich zdarzeń w interwale. null Unika wartości. Nie można używać z interpolacją.
first	first($value)	Zwraca $value pierwsze zdarzenie występujące w interwale według sygnatury czasowej zdarzenia. Nie pozwala uniknąć null wartości. Nie można używać z interpolacją.
last	last($value)	Zwraca $value ostatnie zdarzenie występujące w interwale według sygnatury czasowej zdarzenia. Nie pozwala uniknąć null wartości. Nie można używać z interpolacją.
median	median($value)	Zwraca $value średnie zdarzenie w interwale według sygnatury czasowej zdarzenia. Nie pozwala uniknąć null wartości. Nie można używać z interpolacją.
stdev	stdev($value)	Zwraca $value odchylenie standardowe zdarzeń w interwale. null Unika wartości. Nie można używać z interpolacją.
twsum	twsum($value)	Zwraca $value sumę ważoną czasu zdarzeń w interwale. Wymaga interpolacji.
twavg	twavg($value)	Zwraca $value średnią ważoną czasu zdarzeń w interwale. Wymaga interpolacji.
left	left($value)	Zwraca wartość z $value lewej krawędzi danego interwału. Wymaga interpolacji.
right	right($value)	Zwraca wartość z $value prawej krawędzi danego interwału. Wymaga interpolacji.

Wyrażenia agregacji — rodzaj zmiennej agregacji

Zmienne zagregowane powinny odwoływać się do właściwości w ładunku zdarzenia.

Oto obsługiwane funkcje agregujące.

Funkcja agregacji	Przykład	Opis
count	count()	Zwraca liczbę zdarzeń na interwał.
min	min($event.Temperature.Double)	Oblicza minimalną wartość właściwości Temperature na interwał. null Unika wartości.
max	max($event.Temperature.Long)	Oblicza maksymalną wartość właściwości Temperature na interwał. null Unika wartości.
sum	sum($event.Temperature.Double)	Oblicza sumę właściwości Temperature dla wszystkich zdarzeń w interwale. null Unika wartości.
avg	avg($event.Temperature.Long)	Oblicza średnią właściwości Temperature dla wszystkich zdarzeń w interwale. null Unika wartości.
first	first($event.Temperature.String)	Zwraca wartość pierwszego wystąpienia (według sygnatury czasowej zdarzenia) właściwości Temperature ze wszystkich zdarzeń w interwale. Nie pozwala uniknąć null wartości.
last	last($event.Temperature.String)	Zwraca ostatnią wartość (według sygnatury czasowej zdarzenia) właściwości Temperature ze wszystkich zdarzeń w interwale. Nie pozwala uniknąć null wartości.
median	median($event.Temperature.String)	Zwraca wartość średniej wartości (według sygnatury czasowej zdarzenia) właściwości Temperature ze wszystkich zdarzeń w interwale. Nie pozwala uniknąć null wartości.
stdev	stdev($event.Temperature.String)	Oblicza odchylenie standardowe właściwości Temperature na interwał. null Unika wartości.

W przypadku rodzaju zmiennej agregującej te funkcje można połączyć w wyrażeniu agregacji. Na przykład: max($event.Temperature.Long) - min($event.Temperature.Long).

Składnia

W tej sekcji opisano podstawowe pojęcia składni i operatory zapytań, które są łączone z wyrażeniami formularzy.

Obsługiwane literały

Uwaga

Literały poniżej są używane do tworzenia wyrażeń. Zobacz artykuł Obsługiwane typy danych , aby uzyskać pełną listę typów danych.

Typ pierwotny	Literały
Bool	TRUE, FALSE
Data/godzina	dt'2016-10-08T03:22:55.3031599Z'
Double	1.23, 1.0
Długi	1, 6
Ciąg	'abc'
przedział_czasu	ts'P1Y2M3DT4M5.67S'
Null	NULL

Obsługiwane typy operandów

Operacja	Obsługiwane typy	Uwagi
<, >, <=, >=	Double, Long, DateTime, TimeSpan
=, !=, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> jest odpowiednikiem !=
+, -, *, /	Double, Long, DateTime, TimeSpan

W przypadku wyrażeń porównania (<, >=<, =, >=, ! =) operandy mogą mieć wartość NULL lub mieć ten sam typ. W każdym wyrażeniu predykatu typy operandów po lewej stronie (LHS) i prawej stronie (RHS) są weryfikowane w celu dopasowania. Błędy występują, gdy typy LHS i RHS nie zgadzają się lub operacja nie jest dozwolona dla określonych typów.

Uwaga

Typ ciągu nie może zawierać wartości null w ciepłym magazynie:

• Porównanie ciągu względem wartości NULL i pustego ciągu ("") zachowuje się w taki sam sposób: $event.p1.String = NULL jest równoważne .$event.p1.String = ''
• Interfejs API może zwracać wartości NULL , nawet jeśli oryginalne zdarzenia zawierały puste ciągi.

W przyszłości to samo zachowanie będzie w zimnym sklepie.

Nie należy przyjmować zależności od wartości NULL w kolumnach Ciąg i traktować je tak samo jak puste ciągi.

• Zastosowano sprawdzanie typu:
  • Każdy typ właściwości jest akceptowany NULL względem literału.
  • Typy LHS i RHS powinny być zgodne.

Oto przykłady właściwości p1 i p2 typu String, właściwość p3 typu Double i zagnieżdżona właściwość przechowywana jako p4.p5 typu Double:

Filtr	Czy jest prawidłowy?	Uwagi
$event.p1.String = 'abc'	Tak
$event.p1.String = $event.p2.String	Tak
$event.p1.String = NULL	Tak	NULL pasuje do dowolnego typu po lewej stronie.
$event.p3.Double = 'abc'	Nie	Niezgodność.
$event.p3.Double = $event.p1.String	Nie	Niezgodność.
$event.p1 = 'abc'	Nie	Niezgodność.
$event.p1 = 1	Nie	Niezgodność.
$event.p1 = true	Nie	Niezgodność.
$event.p1 = NULL	Tak	p1 jest jedynym używanym tokenem. Interpretowane jako $event.p1.Double = NULL
$event['p1'] != NULL	Tak	['p1'] jest jedynym używanym tokenem. Interpretowane jako $event['p1'].Double != NULL
$event.p4.p5 = 0.0	Nie	Nieprawidłowa składnia odwołania do właściwości. Typ musi być określony na LHS porównania.
$event.p4.p5.Double = 0.0	Tak

Obsługiwane funkcje skalarne

Poniżej znajduje się lista funkcji skalarnych według kategorii:

Funkcje konwersji

Nazwa funkcji	Podpis	Przykład	Uwagi
toDouble	Double toDouble (value: String, Double, Long)	toDouble($event.value.Long)	Konwertuje argumenty na double.
toLong	Long toLong (value: String, Double, Long)	toLong($event.value.Double + 1.0)	Konwertuje argumenty na long.
toString	String toString (value: String, Double, Long)	toString($event.value.Double)	Konwertuje argumenty na ciąg.

Funkcje matematyczne

Nazwa funkcji	Podpis	Przykład	Uwagi
round	Double round(value:Double)	round($event.value.Double)	Zaokrągla liczbę zmiennoprzecinkową o podwójnej precyzji do najbliższej liczby całkowitej.
ceiling	Double ceiling(value:Double)	ceiling($event.value.Double)	Zwraca najmniejszą wartość całkowitą, która jest większa lub równa liczbie zmiennoprzecinkowej o podwójnej precyzji.
floor	Double floor(value:Double)	floor($event.value.Double)	Zwraca największą wartość całkowitą mniejszą lub równą liczbie zmiennoprzecinkowej o podwójnej precyzji.

Trygonometrycznych

Nazwa funkcji	Podpis	Przykład	Uwagi
cos	Double cos(value:Double)	cos($event.value.Double)	Zwraca cosinus określonego kąta w radianach.
sin	Double sin(value:Double)	sin($event.value.Double)	Zwraca sinus określonego kąta w radianach.
tan	Double tan(value:Double)	tan($event.value.Double)	Zwraca tangens określonego kąta w radianach.
acos	Double acos(value:Double)	acos($event.value.Double)	Zwraca kąt w radianach, którego Cosine jest określoną liczbą.
asin	Double asin(value:Double)	asin($event.value.Double)	Zwraca kąt w radianach, którego sinus jest określoną liczbą.
atan	Double atan(value:Double)	atan($event.value.Double)	Zwraca kąt w radianach, którego tangens jest określoną liczbą.
atan2	Double atan2(value1:Double, value2:Double)	atan2($event.value1.Double, $event.value2.Double)	Zwraca kąt w radianach, którego tangens jest ilorazem dwóch określonych liczb.

Funkcje logarytmyczne

Nazwa funkcji	Podpis	Przykład	Uwagi
log	Double log(value:Double)	log($event.value.Double)	Zwraca logarytm naturalny określonej liczby.
log2	Double log2(value:Double)	log2($event.value.Double)	Zwraca logarytm podstawowy 2 określonej liczby.
log10	Double log10(value:Double)	log10($event.value.Double)	Zwraca logarytm podstawowy 10 określonej liczby.

Funkcje datetime

Nazwa funkcji	Podpis	Przykład	Uwagi
monthOfYear	Long monthOfYear(value:DateTime)	monthOfYear($event.$ts)	Zwraca miesiąc roku jako wartość liczbową dla podanej wartości DateTime.
dayOfMonth	Long dayOfMonth(value:DateTime)	dayOfMonth($event.$ts)	Zwraca dzień miesiąca jako wartość liczbową dla podanej wartości DateTime.
hourOfDay	Long hourOfDay(value:DateTime)	hourOfDay($event.$ts)	Zwraca godzinę dnia jako wartość liczbową dla podanej wartości DateTime.
utcNow	DateTime utcNow()	utcNow()	Zwraca bieżący czas w formacie UTC.

Funkcje ciągów

Nazwa funkcji	Podpis	Przykład	Uwagi
toUpper	String toUpper(value:String)	toUpper($event.value.String)	Zwraca ciąg wejściowy przekonwertowany na wielkie litery.
toLower	String toLower(value:String)	toLower($event.value.String)	Zwraca ciąg wejściowy przekonwertowany na małe litery.
strLen	Long strLen(value:String)	strLen($event.value.String)	Zwraca liczbę znaków w argumencie ciągu.
strCat	Long strCat(value1:String, value2:String)	strCat($event.value1.String, $event.value2.String)	Łączy dwa określone ciągi wejściowe.
subString	String subString(value:String, startIndex:Double, length:Double)	subString($event.value.String, 2.0, 4.0)	Pobiera podciąg z tego wystąpienia.
trim	String trim(value:String)	trim($event.value.String)	Zwraca nowy ciąg, usuwając wszystkie wiodące i końcowe znaki odstępu z ciągu wejściowego.
indexOf	Long indexOf(value:String, subString:String)	indexOf($event.value.String, 'abc')	Zwraca pierwsze wystąpienie określonego ciągu w oryginalnym ciągu na podstawie indeksowania zerowego.
replace	String replace(value:String, searchString:String, replaceString:String)	replace($event.value.String, 'abc', 'xyz')	Zwraca ciąg, w którym wszystkie wystąpienia ciągu wyszukiwania są zastępowane ciągiem zastępczym.

Inne funkcje

Nazwa funkcji	Podpis	Przykład	Uwagi
coalesce	String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)	coalesce(toLong($event.value.Double), $event.value.Long)	Zwraca pierwszą wartość inną niż null na liście argumentów. Akceptuje co najmniej 2 i maksymalnie 64 argumenty, ale wszystkie muszą być tego samego typu danych.
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')	Zwraca drugi lub trzeci argument w zależności od tego, czy predykat został rozpoznany na wartość true (zwraca drugi argument) lub false (zwraca trzeci argument). Predykat musi być wyrażeniem logicznym, a drugi i trzeci argument musi być tego samego typu.

Zobacz też

• Aby uzyskać więcej informacji na temat rejestracji aplikacji i modelu programowania usługi Azure Active Directory, zobacz Azure Active Directory dla deweloperów.

• Aby dowiedzieć się więcej o parametrach żądania i uwierzytelniania, przeczytaj Uwierzytelnianie i autoryzacja.

• Narzędzia, które ułatwiają testowanie żądań i odpowiedzi HTTP, obejmują:

• Fiddler. Ten bezpłatny internetowy serwer proxy debugowania może przechwytywać żądania REST, dzięki czemu można zdiagnozować żądania HTTP i komunikaty odpowiedzi.

• JWT.io. Za pomocą tego narzędzia można szybko zrzucić oświadczenia w tokenie elementu nośnego, a następnie zweryfikować ich zawartość.

• Postman. Jest to bezpłatne narzędzie do testowania żądań HTTP i odpowiedzi na potrzeby debugowania interfejsów API REST.

• Dowiedz się więcej o usłudze Azure Time Series Insights Gen2, przeglądając dokumentację usługi Gen2.