Azure Time Series Insights syntaxe d’expression de série chronologique Gen2

Article
08/05/2023

Vue d’ensemble

Time Series Expression (TSX) est un langage d’expression basé sur des chaînes avec un typage fort. TSX est utilisé pour représenter les entités suivantes dans une requête de série chronologique.

Filtrer
Valeur
Agrégation

Expressions de filtre

Les expressions de filtre sont utilisées pour représenter des clauses booléennes. Le tableau suivant répertorie des exemples de filtres :

TSX	Description
`$event.PointValue.Double = 3.14`	`true` pour les événements avec la valeur double PointValue égale à `3.14`
`$event.PointValue > 3.14 AND $event.Status.String = 'Good'`	`true`pour les événements dont PointValue est supérieur `3.14` à et status `Good`
`$event.$ts > dt'2018-11-01T02:03:45Z'`	`true` pour les événements dont l’horodatage est supérieur à `2018-11-01T02:03:45Z`
`$event.PointEval.Bool = true`	`true` pour les événements dont PointValue est égal à `true`

Expressions de valeur

Les expressions de valeur sont utilisées pour représenter la valeur des variables numériques et catégorielles. Une expression de valeur peut être une expression de référence de propriété de type Double ou Long.

Par exemple :

TSX	Notes
`$event.Temperature.Double`	Le dernier jeton d’une expression de valeur (dans ce cas `Double`) est lu en tant que Type de la propriété .
`$event.Temperature`	Le type est supposé être Double pour une propriété accessible par un jeton unique.
`$event['Temperature-Celsius']`	Utilisez `[` et `]` pour les jetons d’échappement qui ont des caractères spéciaux. En outre, utilisez `\` entre crochets pour échapper aux caractères suivants : `\` et `'`.
`$event.Temperature.Celsius.Double`	Utilisez `.` pour accéder aux propriétés imbriquées. Lors de l’accès aux propriétés imbriquées, le type est obligatoire.
`$event.Temperature['Celsius-C'].Double`	Utilisez `[` et `]` pour les jetons d’échappement qui ont des caractères spéciaux lors de l’accès aux propriétés imbriquées. En outre, utilisez `\` entre crochets pour échapper aux caractères suivants : `\` et `'`. Lors de l’accès aux propriétés imbriquées, le type est obligatoire.
`$event['Temperature']['Celsius'].Double`	L’utilisation de `[` et `]` pour les jetons d’échappement est autorisée sur n’importe quel jeton.

Type de variable numérique

Le résultat de l’expression de valeur doit être de type Double ou Long .

Type de variable d’agrégation

Le résultat de l’expression de valeur peut être de n’importe quel type pris en charge.

Type de variable de catégorie

Le résultat de l’expression de valeur ne peut être que de type String ou Long .

Expressions d’agrégation

Les expressions d’agrégation sont utilisées pour représenter l’opération d’agrégation à utiliser sur la requête. Une expression d’agrégation génère une valeur unique pour chaque intervalle. Les expressions d’agrégation peuvent être appliquées sur des variables numériques et d’agrégation.

Expressions d’agrégation - type de variable numérique

Les variables numériques doivent faire référence à $value.

Voici les fonctions d’agrégation prises en charge.

Fonction d'agrégation	Exemple	Description
`min`	`min($value)`	Calcule le minimum par `$value` intervalle. Évite les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`max`	`max($value)`	Calcule le maximum de par `$value` intervalle. Évite les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`sum`	`sum($value)`	Calcule la somme de `$value` sur tous les événements de l’intervalle. Évite les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`avg`	`avg($value)`	Calcule la moyenne de `$value` sur tous les événements de l’intervalle. Évite les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`first`	`first($value)`	Retourne `$value` le premier événement qui se produit dans l’intervalle par horodatage d’événement. N’évite pas les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`last`	`last($value)`	Retourne `$value` le dernier événement qui se produit dans l’intervalle par horodatage d’événement. N’évite pas les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`median`	`median($value)`	Retourne `$value` l’événement intermédiaire dans l’horodatage de l’intervalle par événement. N’évite pas les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`stdev`	`stdev($value)`	Retourne `$value` l’écart type des événements dans l’intervalle. Évite les `null` valeurs. Impossible d’utiliser avec l’interpolation.
`twsum`	`twsum($value)`	Retourne `$value` la somme pondérée dans le temps des événements dans l’intervalle. Nécessite une interpolation.
`twavg`	`twavg($value)`	Retourne `$value` la moyenne pondérée dans le temps des événements dans l’intervalle. Nécessite une interpolation.
`left`	`left($value)`	Retourne le `$value` au bord gauche de l’intervalle donné. Nécessite une interpolation.
`right`	`right($value)`	Retourne le `$value` au bord droit de l’intervalle donné. Nécessite une interpolation.

Expressions d’agrégation - type de variable d’agrégation

Les variables d’agrégation doivent faire référence à une propriété dans la charge utile de l’événement.

Voici les fonctions d’agrégation prises en charge.

Fonction d'agrégation	Exemple	Description
`count`	`count()`	Retourne le nombre d’événements par intervalle.
`min`	`min($event.Temperature.Double)`	Calcule le minimum de la propriété Temperature par intervalle. Évite les `null` valeurs.
`max`	`max($event.Temperature.Long)`	Calcule le maximum de la propriété Temperature par intervalle. Évite les `null` valeurs.
`sum`	`sum($event.Temperature.Double)`	Calcule la somme de la propriété Temperature sur tous les événements de l’intervalle. Évite les `null` valeurs.
`avg`	`avg($event.Temperature.Long)`	Calcule la moyenne de la propriété Temperature sur tous les événements de l’intervalle. Évite les `null` valeurs.
`first`	`first($event.Temperature.String)`	Retourne la première valeur qui se produit (par horodatage d’événement) de la propriété Temperature de tous les événements de l’intervalle. N’évite pas les `null` valeurs.
`last`	`last($event.Temperature.String)`	Retourne la dernière valeur qui se produit (par horodatage d’événement) de la propriété Temperature de tous les événements de l’intervalle. N’évite`null` pas les valeurs.
`median`	`median($event.Temperature.String)`	Retourne la valeur du milieu (par horodatage d’événement) de la propriété Temperature à partir de tous les événements de l’intervalle. N’évite`null` pas les valeurs.
`stdev`	`stdev($event.Temperature.String)`	Calcule l’écart type de la propriété Temperature par intervalle. Évite les `null` valeurs.

Pour un type de variable d’agrégation , ces fonctions peuvent être combinées dans l’expression d’agrégation. Par exemple : max($event.Temperature.Long) - min($event.Temperature.Long).

Syntaxe

Cette section décrit les principaux concepts de syntaxe et les opérateurs de requête concaténés pour former des expressions.

Littéraux pris en charge

Notes

Les littéraux ci-dessous sont utilisés pour former des expressions. Consultez l’article Types de données pris en charge pour obtenir la liste complète des types de données.

Type primitif	Littéraux
Bool	`TRUE`, `FALSE`
DateTime	`dt'2016-10-08T03:22:55.3031599Z'`
Double	`1.23`, `1.0`
Long	`1`, `6`
Chaîne	`'abc'`
TimeSpan	`ts'P1Y2M3DT4M5.67S'`
Null	`NULL`

Types d’opérandes pris en charge

Opération	Types pris en charge	Notes
<, >, <, >	Double, Long, DateTime, TimeSpan
=, =, <>	Double, Long, String, Bool, DateTime, TimeSpan, NULL	<> équivaut à !=
+, -, *, /	Double, Long, DateTime, TimeSpan

Pour les expressions de comparaison (<, >, <=, >=, =, !=), les opérandes peuvent être NULL ou être du même type. Dans chaque expression de prédicat, les types d’opérandes du côté gauche (LHS) et de droite (RHS) sont validés pour correspondre. Des erreurs se produisent lorsque les types LHS et RHS ne sont pas d’accord, ou lorsqu’une opération n’est pas autorisée sur des types particuliers.

Notes

Le type de chaîne ne peut pas avoir la valeur Null dans le magasin chaud :

La comparaison entre String et null et la chaîne vide ('') se comporte de la même façon : $event.p1.String = NULL équivaut à $event.p1.String = ''.
L’API peut retourner des valeurs NULL même si les événements d’origine contenaient des chaînes vides.

À l’avenir, le même comportement sera sur le magasin froid.

Ne dépendez pas des valeurs NULL dans les colonnes de chaîne et traitez-les de la même façon que des chaînes vides.

Un type case activée est appliqué :
- Tout type de propriété est accepté par rapport à un NULL littéral.
- Les types de LHS et RHS doivent correspondre.

Voici des exemples de propriétés p1 et p2 de type String, de propriété p3 de type Double et d’une propriété imbriquée stockée sous la forme p4.p5 de type Double :

Filtrer	Est valide ?	Notes
`$event.p1.String = 'abc'`	Oui
`$event.p1.String = $event.p2.String`	Oui
`$event.p1.String = NULL`	Oui	`NULL` correspond à n’importe quel type de gauche.
`$event.p3.Double = 'abc'`	Non	Incompatibilité de type.
`$event.p3.Double = $event.p1.String`	Non	Incompatibilité de type.
`$event.p1 = 'abc'`	Non	Incompatibilité de type.
`$event.p1 = 1`	Non	Incompatibilité de type.
`$event.p1 = true`	Non	Incompatibilité de type.
`$event.p1 = NULL`	Oui	`p1` est le seul jeton utilisé. Interprété comme `$event.p1.Double = NULL`
`$event['p1'] != NULL`	Oui	`['p1']` est le seul jeton utilisé. Interprété comme `$event['p1'].Double != NULL`
`$event.p4.p5 = 0.0`	Non	Syntaxe de référence de propriété non valide. Un type doit être spécifié sur LHS de comparaison.
`$event.p4.p5.Double = 0.0`	Oui

Fonctions scalaires prises en charge

Voici la liste des fonctions scalaires par catégories :

Fonctions de conversion

Nom de la fonction	Signature	Exemple	Notes
`toDouble`	`Double toDouble (value: String, Double, Long)`	`toDouble($event.value.Long)`	Convertit les arguments en Double.
`toLong`	`Long toLong (value: String, Double, Long)`	`toLong($event.value.Double + 1.0)`	Convertit les arguments en long.
`toString`	`String toString (value: String, Double, Long)`	`toString($event.value.Double)`	Convertit les arguments en Chaîne.

Fonctions mathématiques

Nom de la fonction	Signature	Exemple	Notes
`round`	`Double round(value:Double)`	`round($event.value.Double)`	Arrondit un nombre flottant double précision à l’intégrale la plus proche.
`ceiling`	`Double ceiling(value:Double)`	`ceiling($event.value.Double)`	Retourne la plus petite valeur intégrale supérieure ou égale à un nombre à virgule flottante double précision.
`floor`	`Double floor(value:Double)`	`floor($event.value.Double)`	Retourne la plus grande valeur intégrale inférieure ou égale au nombre à virgule flottante double précision.

Fonctions trigonométriques

Nom de la fonction	Signature	Exemple	Notes
`cos`	`Double cos(value:Double)`	`cos($event.value.Double)`	Retourne le cosinus de l’angle spécifié en radians.
`sin`	`Double sin(value:Double)`	`sin($event.value.Double)`	Retourne le sinus de l’angle spécifié en radians.
`tan`	`Double tan(value:Double)`	`tan($event.value.Double)`	Retourne la tangente de l’angle spécifié en radians.
`acos`	`Double acos(value:Double)`	`acos($event.value.Double)`	Retourne l’angle en radians dont le cosinus est le nombre spécifié.
`asin`	`Double asin(value:Double)`	`asin($event.value.Double)`	Retourne l’angle en radians dont le sinus est le nombre spécifié.
`atan`	`Double atan(value:Double)`	`atan($event.value.Double)`	Retourne l’angle en radians dont tangente est le nombre spécifié.
`atan2`	`Double atan2(value1:Double, value2:Double)`	`atan2($event.value1.Double, $event.value2.Double)`	Retourne l’angle en radians dont la tangente est le quotient de deux nombres spécifiés.

Fonctions logarithmiques

Nom de la fonction	Signature	Exemple	Notes
`log`	`Double log(value:Double)`	`log($event.value.Double)`	Retourne le logarithme naturel d’un nombre spécifié.
`log2`	`Double log2(value:Double)`	`log2($event.value.Double)`	Retourne le logarithme de base 2 d’un nombre spécifié.
`log10`	`Double log10(value:Double)`	`log10($event.value.Double)`	Retourne le logarithme de base 10 d'un nombre spécifié.

Fonctions de date/heure

Nom de la fonction	Signature	Exemple	Notes
`monthOfYear`	`Long monthOfYear(value:DateTime)`	`monthOfYear($event.$ts)`	Retourne le mois de l’année sous forme numérique pour le DateTime fourni.
`dayOfMonth`	`Long dayOfMonth(value:DateTime)`	`dayOfMonth($event.$ts)`	Retourne le jour du mois sous forme numérique pour le DateTime fourni.
`hourOfDay`	`Long hourOfDay(value:DateTime)`	`hourOfDay($event.$ts)`	Retourne l’heure de la journée sous forme numérique pour le DateTime fourni.
`utcNow`	`DateTime utcNow()`	`utcNow()`	Retourne l’heure actuelle au format UTC.

Fonctions de chaînes

Nom de la fonction	Signature	Exemple	Notes
`toUpper`	`String toUpper(value:String)`	`toUpper($event.value.String)`	Retourne la chaîne d’entrée convertie en majuscules.
`toLower`	`String toLower(value:String)`	`toLower($event.value.String)`	Retourne la chaîne d’entrée convertie en minuscules.
`strLen`	`Long strLen(value:String)`	`strLen($event.value.String)`	Retourne le nombre de caractères dans l’argument string.
`strCat`	`Long strCat(value1:String, value2:String)`	`strCat($event.value1.String, $event.value2.String)`	Concatène deux chaînes d’entrée spécifiées.
`subString`	`String subString(value:String, startIndex:Double, length:Double)`	`subString($event.value.String, 2.0, 4.0)`	Récupère une sous-chaîne de cette instance.
`trim`	`String trim(value:String)`	`trim($event.value.String)`	Retourne une nouvelle chaîne en supprimant tous les espaces blancs de début et de fin de la chaîne d’entrée.
`indexOf`	`Long indexOf(value:String, subString:String)`	`indexOf($event.value.String, 'abc')`	Retourne la première occurrence de la chaîne spécifiée dans la chaîne d’origine, en fonction de l’indexation zéro.
`replace`	`String replace(value:String, searchString:String, replaceString:String)`	`replace($event.value.String, 'abc', 'xyz')`	Retourne une chaîne dans laquelle toutes les occurrences de la chaîne de recherche sont remplacées par la chaîne de remplacement.

Autres fonctions

Nom de la fonction	Signature	Exemple	Notes
`coalesce`	`String, Long, Double, Bool coalesce (value: String, Long, Double, Bool)`	`coalesce(toLong($event.value.Double), $event.value.Long)`	Retourne la première valeur non null de la liste d’arguments. Accepte au minimum 2 arguments et au maximum 64 arguments, mais ils doivent tous être du même type de données.
`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')`	Retourne le deuxième ou le troisième argument selon que le prédicat a été résolu en true (retourne le deuxième argument) ou false (retourne le troisième argument). Le prédicat doit être une expression booléenne et les deuxième et troisième arguments doivent être du même type.

Voir aussi

Pour plus d’informations sur l’inscription des applications et le modèle de programmation Azure Active Directory, consultez Azure Active Directory pour les développeurs.
Pour en savoir plus sur les paramètres de requête et d’authentification, consultez Authentification et autorisation.
Les outils qui aident à tester les requêtes et réponses HTTP sont les suivants :
Fiddler. Ce proxy de débogage web gratuit peut intercepter vos requêtes REST, ce qui vous permet de diagnostiquer les messages de requête et de réponse HTTP.
JWT.io. Vous pouvez utiliser cet outil pour vider rapidement les revendications dans votre jeton du porteur, puis valider leur contenu.
Postman. Il s’agit d’un outil de test de requête et de réponse HTTP gratuit pour le débogage des API REST.
Pour en savoir plus sur Azure Time Series Insights Gen2, consultez la documentation Gen2.