Lire en anglais

Partager via


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

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' truepour 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’évitenull 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’évitenull 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.