syntaxe de requête Azure Time Series Insights Gen1

Attention

Il s’agit d’un article Gen1.

Cet article décrit le format et la syntaxe de la requête de requête pour l’API de requête Azure Time Series Insights Gen1.

Résumé

Important

• Les requêtes doivent être au format JSON.
• Les charges utiles de requête HTTP effectuées pour l’API de requête doivent être conformes au format spécifié dans cet article.

Le langage est subdivisé en éléments suivants :

• Expressions scalaires, qui produisent des valeurs scalaires. Les expressions scalaires incluent les expressions de chaîne de prédicat, les expressions de comparaison et les expressions arithmétiques.
• Fonctions scalaires, qui retournent des valeurs scalaires.
• Expressions d’agrégation, qui sont utilisées pour partitionner des collections d’événements et des mesures de calcul sur les partitions.
• Clauses, qui forment les composants constitutifs des requêtes JSON ou d’une partie d’une expression.

Modèle de données

L’API de requête Azure Time Series Insights Gen1 fonctionne sur les données stockées en tant qu’événements individuels dans un environnement. Chaque événement est un ensemble de paires nom et valeur de propriété.

Propriétés d’événement

Les propriétés d’événement peuvent être de l’un des types primitifs suivants : Bool, DateTime, Double ou String. Tous les types primitifs sont nullables.

Remarque

Les formats de source d’événements personnalisés peuvent prendre en charge un ensemble plus important de types valeur. Azure Time Series Insights Gen1 déduit le type primitif le plus proche, puis lui caste les types personnalisés lors de l’entrée.

Tous les événements ont les propriétés intégrées suivantes avec un nom et un type prédéfinis :

Nom de la propriété	Type de propriété	Définition
$ts	DateTime	Horodatage d’événement
$esn	Chaîne	Nom de la source d’événement

• Horodatage d’événement

  Par défaut, une valeur d’horodatage d’événement est fournie par la source d’événement. Par exemple, les événements provenant d’un hub IoT ont leur heure en file d’attente en tant qu’horodatage.

  Les clients peuvent modifier ce comportement en configurant une autre propriété d’événement à la place. Les propriétés d’horodatage personnalisées peuvent être spécifiées dans les hubs d’événements et leshubs IoT.

• Nom de la source d’événement

  Le nom de la source d’événement est le nom affiché pour la source d’événement à partir de laquelle Azure Time Series Insights Gen1 a reçu l’événement. Les noms de source d’événements sont associés à un événement particulier au moment de l’entrée.

  Important

  • Les noms de source d’événements restent inchangés pendant toute la durée de vie de l’événement.
  • Si le nom d’une source d’événement est modifié, les événements existants portent l’ancien nom de source d’événement. Les nouveaux événements portent le nouveau nom de source d’événement.

Types d’événements

Les propriétés d’événement personnalisées sont identifiées et référencées de manière unique dans les expressions de requête par nom et type. Un événement peut avoir plusieurs propriétés portant le même nom et différents types. Les propriétés portant le même nom, mais des types différents peuvent résulter d’un fractionnement de type d’entrée.

Une valeur de propriété d’événement de type String peut être stockée en tant que propriété avec un type différent dans les cas suivants :

• Si une valeur String est une valeur Double valide, elle est stockée en tant que Double et String.
• Si une valeur String est une valeur DateTime valide, elle est stockée en tant que DateTime uniquement.

L’API de requête convertit les littéraux strings vides ("") en null dans la sortie.

Azure Time Series Insights Gen1 a une prise en charge limitée des valeurs suivantes dans le type Double : Double.NaN, Double.PositiveInfinityet Double.NegativeInfinity. Ces valeurs sont converties null en pendant l’entrée, mais si l’évaluation de requête produit l’une de ces valeurs, la valeur est évaluée et sérialisée en tant que chaîne en réponse.

Vous pouvez passer ces valeurs en tant que Chaînes pour l’entrée . Par conséquent, dans les expressions de requête, ces valeurs doivent également être passées en tant que Chaînes.

Les schémas d’événements décrivent les propriétés d’un événement. Un schéma d’événement contient le nom d’une source d’événement et l’ensemble ordonné de propriétés pour l’événement. Différents événements peuvent avoir des schémas différents ou partager le même schéma.

Expressions scalaires

Les expressions scalaires produisent des valeurs scalaires. Les expressions scalaires sont divisées en les types suivants :

• Expressions constantes
• Expressions de référence de propriété
• Expressions de comparaison
• Expressions arithmétiques
• Expressions de chaîne de prédicat

Expressions de constantes

Vous représentez des expressions constantes à l’aide des littéraux suivants pour chacun des types primitifs :

Type primitif	Représentation JSON	Exemple JSON	Notes
Bool	En tant que type booléen JSON	true, false
DateTime	En tant qu’objet imbriqué avec une propriété dateTime unique au format yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFKISO 8601 .	{"dateTime":"2016-08-01T00:00:00.000Z"}
Double	Nombre JSON casté dans la plage Double.	1.23e45, 123	Les doubles dépassements de capacité génèrent une erreur.
Chaîne	Type de chaîne JSON	"abc"
TimeSpan	En tant qu’objet imbriqué avec une propriété timeSpan unique au format ISO 8601 : P[n]Y[n]M[n]DT[n]H[n]M[n]S.	{"timeSpan":"P1Y2M3DT4M5.67S"}

Types primitifs nullables

Les types de données primitifs sont nullables. null les valeurs pour les types primitifs sont exprimées en JSON comme suit :

{ "string": null }

{ "double": null }

{ "bool": null }

{ "dateTime": null }

{ "timeSpan": null }

Expressions de référence de propriété

Vous utilisez une expression de référence de propriété pour accéder aux valeurs des propriétés non intégrées d’un événement. Les propriétés non intégrées incluent toutes les propriétés personnalisées au-delà des propriétés par défaut qui sont automatiquement contenues dans un schéma d’événements.

Le type de résultat d’une expression de référence de propriété est le type primitif de la propriété. Les propriétés du schéma d’événements sont identifiées de manière unique par nom et type, et l’expression de référence exige que les deux soient spécifiées.

• Exemples JSON :

  {
     "property": "p1",
     "type": "Bool"
  }
  

  {
     "property": "p1",
     "type": "DateTime"
  }
  

  {
     "property": "p1",
     "type": "Double"
  }
  

  {
     "property": "p1",
     "type": "String"
  }
  

  {
     "property": "p1",
     "type": "TimeSpan"
  }
  

Une expression de référence de propriété intégrée est utilisée pour accéder aux propriétés intégrées d’un événement. Les propriétés intégrées sont uniquement celles qui sont automatiquement définies dans un schéma d’événements.

Le type de résultat d’une expression de référence de propriété intégrée est le type primitif de la propriété. Les propriétés intégrées sont référencées uniquement par nom ; par conséquent, aucun type n’est nécessaire dans l’expression de référence :

{ "builtInProperty": "$esn" }

Expressions de comparaison

Les expressions de comparaison booléennes suivantes sont prises en charge :

Nom de la propriété dans JSON	Description
eq	Égal à
in	Dans (égal à n’importe quel)
phrase	Contient une expression
startsWith	Starts With (Commence par)
endsWith	Se termine par l’expression
regex	Correspond à l'expression régulière
lt	Inférieur à
lte	Inférieur ou égal à
gt	Supérieur à
Gte	Supérieur ou égal à

Important

• Toutes les expressions de comparaison prennent les types primitifs des arguments de gauche et de droite et retournent une valeur booléenne représentant le résultat de la comparaison.
• Les deux types d’arguments de gauche et de droite dans les comparaisons doivent correspondre.
• Tous les types sont implicitement convertis uniquement en eux-mêmes, et les casts explicites ne sont pas pris en charge.

{
  "eq": {
    "left": {
      "property": "p1",
      "type": "String"
     },
     "right": "abc"
  }
}

• Exemples JSON :

  {
     "startsWith": {
       "left": {
         "property": "p1",
         "type": "String"
        },
        "right": "abc"
     }
  }
  

  {
     "startsWith": {
       "left": {
         "property": "p1",
         "type": "String"
       },
       "right": "",
       "stringComparison": "Ordinal"
     }
  }
  

  {
     "endsWith": {
       "left": {
         "property": "p1",
         "type": "String"
       },
       "right": {
         "property": "p2",
         "type": "String"
       },
       "stringComparison": "Ordinal"
     }
  }
  

Le tableau suivant présente les types d’arguments pris en charge pour chacune des expressions de comparaison :

Type d’argument	Opération de comparaison prise en charge
Bool	eq, in
DateTime	eq, in, lt, lte, gte
Double	eq, in, lt, lte, gte
Chaîne	eq, in, expression, startsWith, endsWith, regex
TimeSpan	eq, in, lt, lte, gte

Le littéral NULL peut être utilisé uniquement avec les opérateurs de comparaison suivants : eq ou in.

• L’opérateur eq génère true si les deux côtés sont des null valeurs. Sinon, l’opérateur génère false.
• Pour les autres opérations, l’erreur est générée pour le littéral NULL , et le comportement n’est pas défini pour les propriétés de valeur null (toute opération de comparaison qui aboutit à false).
• Une null valeur précède les valeurs non null dans les classements de tri (par exemple, si le tri par une propriété est appliqué pour renvoyer une liste d’événements).

Azure Time Series Insights Gen1 prend en charge les expressions logiques booléennes suivantes :

Nom de la propriété dans JSON	Description
and	Prend un ensemble non vide d’arguments booléens et retourne true si tous ont la truevaleur .
or	Prend un ensemble non vide d’arguments booléens et retourne true si l’un d’eux prend la valeur true.
not	Prend un seul argument booléen et retourne sa valeur annulée.

{
  "and": [
    {
      "eq": {
        "left": {
          "property": "p1",
          "type": "String"
        },
        "right": "abc"
      }
    },
    {
      "not": {
        "lt": {
          "left": {
            "property": "p1",
            "type": "Double"
          },
          "right": 1
        }
      }
    }
  ]
}

La propriété stringComparison est facultative. Par défaut, sa valeur est OrdinalIgnoreCase, ce qui fait que la casse des phrases est ignorée dans les comparaisons.

{
  "regex": {
    "left": {
      "property": "p1",
      "type": "String"
    },
    "right": "^abc*"
  }
}

{
  "regex": {
      "left": "abc",
      "right": "^a*$"
  }
}

Expressions arithmétiques

Azure Time Series Insights Gen1 prend en charge les expressions arithmétiques suivantes :

Nom de la propriété dans JSON	Description
add	Addition
sub	Soustraction
Mult	Multiplication
div	Division

Toutes les expressions arithmétiques prennent les arguments de gauche et de droite des types primitifs et retournent une valeur qui représente le résultat de l’opération.

Tous les types sont implicitement convertis uniquement en eux-mêmes, et les casts explicites ne sont pas pris en charge.

{
  "add": {
    "left": {
      "property": "p1",
      "type": "Double"
     },
     "right": 1
  }
}

Le tableau suivant montre les types d’arguments pris en charge pour chacune des expressions arithmétiques :

Opération	Type gauche	Type droit	Type de résultat
add	Double	Double	Double
add	TimeSpan	TimeSpan	TimeSpan
add	DateTime	TimeSpan	DateTime
add	TimeSpan	DateTime	DateTime
sub	Double	Double	Double
sub	TimeSpan	TimeSpan	TimeSpan
sub	DateTime	DateTime	TimeSpan
sub	DateTime	TimeSpan	DateTime
mul	Double	Double	Double
div	Double	Double	Double

Expressions de chaîne de prédicat

Les expressions de chaîne de prédicat booléens contiennent des prédicats booléens qui sont représentés sous forme d’expressions lisibles par l’homme appelées chaînes de prédicat.

Exemples de chaînes de prédicat :

Chaîne de prédicat	Description
Description HAS 'hello world'	true pour les événements qui contiennent l’expression hello world dans la propriété Description dans toutes les sources d’événements
'hello world'	true pour les événements qui contiennent l’expression hello world
startsWith(Status, 'go')	true pour les événements dont l’état commence par go
endsWith(Status, 'oD')	true pour les événements dont l’état se termine par od
startsWith_cs(Status, 'Go')	true pour les événements dont l’état commence par Go
endsWith_cs(Status, 'od')	true pour les événements dont l’état commence par od
matchesRegex(s, '^G*')	true pour les événements dont l’état correspond à l’expression régulière ^G*
PointValue.Double = 3.14	true pour les événements avec la valeur double PointValue égale à 3.14
Status IN ('Good','Bad')	true pour les événements avec l’état qui contient Good ou Bad
PointValue > 3.14 AND Status.String = 'Good'	truepour les événements dont PointValue est supérieur 3.14 à et dont l’état de la chaîne est Good
[PointValue] > 3.14 AND ([Status] = 'Good' OR [Status] = 'Bad') AND NOT [Description] HAS 'hello world'	true pour les événements dont PointValue est supérieur 3.14 à et l’état de Good ou Bad et description ne contenant pas l’expression hello world

{ "predicateString": "PointValue.Double = 3.14" }

L’expression de la chaîne de prédicat est évaluée en une expression booléenne JSON. Il doit être conforme à la grammaire (simplifiée) suivante :

Expression booléenne JSON	Formulaire Backus-Naur
parse	orPredicate EOF | EOF;
orPredicate	andPredicate (Or andPredicate)*;
andPredicate	notPredicate (And notPredicate)*;
notPredicate	(Not)* predicate;
predicate	parenPredicate | comparisonPredicateExtended | hasPredicate | inPredicate;
parenPredicate	OpenParen orPredicate CloseParen;
parenExpression	OpenParen additiveExpression CloseParen;
comparisonPredicateExtended	(ComparisonOp literal) | comparisonPredicate;
comparisonPredicate	additiveExpression ComparisonOp additiveExpression;
additiveExpression	multiplicativeExpression ((Plus | Minus) multiplicativeExpression)*;
multiplicativeExpression	unaryExpression (MultiplicativeOp unaryExpression)*;
functionCallExpression	identifier OpenParen CloseParen;
unaryExpression	identifier | literal | functionCallExpression | parenPredicate | parenExpression;
hasPredicate	(identifier? Has)? StringLiteral;
inPredicate	identifier? In OpenParen literal (Comma literal)* CloseParen;
literal	StringLiteral | ((Minus)? NumericLiteral) | BooleanLiteral | DateTimeLiteral | TimeSpanLiteral | NullLiteral;
identifier	BuiltinIdentifier | (QuotedOrUnquotedIdentifier (Sep QuotedOrUnquotedIdentifier)?);

Azure Time Series Insights types de données primitives Gen1 sont pris en charge dans les expressions de chaîne de prédicat.

Contrairement aux expressions de référence de propriété JSON, un type pour une propriété peut être omis, auquel cas un type est automatiquement déduit.

Littéraux pris en charge

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

Types d’opérandes pris en charge

Opération	Types pris en charge	Notes
<, >, <, >	Double, DateTime, TimeSpan
=, =, <>	String, Bool, Double, DateTime, TimeSpan, NULL	<> est équivalent pour !=
+, -, *, /	Double, DateTime, TimeSpan
IN	String, Bool, Double, DateTime, TimeSpan, NULL	Tous les opérandes doivent être du même type ou être la constante NULL. Plusieurs valeurs NULLsont équivalentes à une seule valeur NULL.
HAS	Chaîne	Seuls les littéraux de chaîne constante sont autorisés à droite. Les chaînes vides et NULL ne sont pas autorisées.

Pour les prédicats de comparaison (<, , >=< , >=, =, !=) et l’opérande de prédicat IN peut être NULL ou avoir un type unique.

Pour les expressions avec un prédicat HAS , le littéral constant à droite de l’opérande HAS peut être développé en plusieurs types. En outre, le littéral constant à droite de l’opérande HAS est analysé en une valeur Bool, Double, DateTime ou TimeSpan . Pour chaque valeur analysée avec succès, un prédicat avec l’opérateur = est créé. Ces prédicats et le prédicat HAS d’origine sont joints dans un prédicat OR . Par exemple, une chaîne p1 HAS '1.0' de prédicat équivaut à p1.String HAS '1.0' OR p1.Double = 1.0, si des propriétés p1 avec des types String et Double existent.

Contrôle de type

Les expressions de prédicat sont vérifiées et validées pour s’assurer que les types de droite et de gauche qu’elles contiennent correspondent.

Important

• Lorsque les constantes à gauche et à droite d’un opérande ne correspondent pas, une erreur est générée.
• Une erreur est également générée si une opération n’est pas autorisée sur ou entre des types spécifiques.

• Si un type est spécifié pour la propriété, un type case activée est appliqué :

  • Tout type de propriété est accepté par rapport à un littéral NULL .

  • Sinon, les types de gauche et de droite doivent correspondre.

    Les exemples de propriétés p1 et p2 du type String et de la propriété p3 du type Double sont affichés dans le tableau suivant :

    Chaîne de prédicat	Est valide ?	Notes
    p1.String = 'abc'	Oui
    p1.String = p2.String	Oui
    p1.String = NULL	Oui	NULL correspond à n’importe quel type de côté gauche.
    p3.Double = 'abc'	Non	Incompatibilité de type.
    p3.Double = p1.String	Non	Incompatibilité de type.
    p1.String HAS 'abc'	Oui
    p3.Double HAS '1.0'	Oui	Le littéral de chaîne a été correctement analysé sur une valeur Double .

• Si un type est omis pour la propriété, mais qu’un nom est spécifié, les étapes suivantes sont effectuées :

  1. Toutes les propriétés avec un nom et des types spécifiés sont prises.
  2. Les opérandes de gauche et de droite sont regroupés par paires par type.
  3. Les paires sont concaténées à l’aide d’opérations AND .

  • Les exemples de propriétés p1 et p2 des types String et Double et certains de leurs équivalents sont affichés dans le tableau suivant :

    Chaîne de prédicat	Chaîne de prédicat de type fort équivalente	Notes
    p1 = 'abc'	p1.String = 'abc'
    p1 = true		Aucune propriété p1 de type Bool, donc une erreur de propriété manquante est émise.
    p1 = NULL	p1.String = NULL AND p1.Double = NULL	Pour NULL le côté droit, il est supposé que toutes les propriétés correspondantes doivent être NULL.
    p1 != NULL	p1.String != NULL OR p1.Double != NULL	Il s’agit d’une inversion de l’expression précédente.
    p1 = '1.0'	p1.String = '1.0'
    p1 IN (1.0, NULL)	p1.Double = 1.0 OR p1.Double = NULL
    p1 IN (NULL)	p1.String = NULL AND p1.Double = NULL	Il s’agit de l’équivalent de p1 = NULL.
    p1 HAS '1.0'	p1.String HAS '1.0' OR p1.Double = 1.0	Le littéral de chaîne a été correctement analysé sur une valeur Double valide.
    p1 HAS 'true'	p1.String HAS 'true'	Le littéral de chaîne a été correctement analysé sur Bool, mais pas p1. La propriété Bool existe.
    p1 = p2	p1.String = p2.String AND p1.Double = p2.Double
    p1 != p2	p1.String != p2.String OR p1.Double != p2.Double	Il s’agit d’une inversion de l’expression précédente.

• Le nom et le type de propriété peuvent être omis pour une propriété de gauche si le type de propriété de droite est bien défini. Cela est vrai chaque fois que le côté droit a des littéraux constants et qu’il ne contient pas seulement un NULL littéral.

  • Ce scénario est une généralisation de la recherche en texte intégral qui utilise l’opérande HAS .

  • Toutes les propriétés qui correspondent au type de droite sont prises et les expressions résultantes sont concaténées via une opération OR .

  • Les exemples de propriété p1 des types String et Double et de la propriété p2 des types String et DateTime sont affichés dans le tableau suivant :

    Chaîne de prédicat	Chaîne de prédicat de type fort équivalente	Notes
    = 'abc'	p1.String = 'abc' OR p2.String = 'abc'
    != 'abc'	p1.String != 'abc' AND p2.String != 'abc'	Inversion de l’expression précédente
    = 1.0	p1.Double = 1.0
    = dt'2000-01-02T03:04:05'	p2.DateTime = dt'2000-01-02T03:04:05'
    = true		Erreur. Aucune propriété Bool n’existe, donc une erreur de propriété manquante est émise.
    = NULL		Erreur. Omettre le nom de propriété pour NULL le côté droit n’est pas autorisé.
    IN (NULL)		Identique à l’erreur précédente.
    IN (1.0, NULL)	p1.Double = 1.0 OR p1.Double = NULL
    HAS '1.0'	p1.String HAS '1.0' OR p1.Double = 1.0 OR p2.String HAS '1.0'
    HAS 'true'	p1.String HAS 'true' OR p2.String HAS 'true'	Il n’existe aucune propriété de type Bool.

• Si l’opérateur est omis avec un nom de propriété, l’opération HAS est supposée.

Fonctions scalaires

Les fonctions scalaires retournent des valeurs scalaires.

Fonctions natives

Les fonctions scalaires prises en charge prêtes à l’emploi par Azure Time Series Insights Gen1 sont les suivantes :

Nom de la fonction	Valeur retournée	Arguments	Exemple	Notes
utcNow	DateTime	None	utcNow()	Retourne l’heure actuelle au format UTC. Le nom de la fonction respecte la casse.

La fonction UTC now retourne une valeur DateTime , qui contient l’heure actuelle au format UTC. Il n’accepte aucun argument.

Expressions d’agrégation

Les expressions agrégées sont utilisées pour partitionner des collections d’événements et des mesures de calcul sur les partitions. Les expressions d’agrégation sont divisées en deux catégories :

• Expressions de dimension
• Expressions de valeurs uniques
• Expressions d’histogramme de date
• Expressions de mesure

Expressions de dimension

Vous utilisez des expressions de dimension à l’intérieur d’une clause d’agrégation pour partitionner un ensemble d’événements et affecter une clé scalaire à chaque partition.

Types d’expressions de dimension :

Nom de propriété dans JSON	Description	Exemple
uniqueValues	Les valeurs de dimension dans le résultat sont les valeurs exactes d’une propriété donnée.
dateHistogram	Les valeurs de dimension dans le résultat sont des plages de temps d’une propriété donnée.	L’histogramme de date de l’horodatage peut entraîner des plages de 10 heures pour une durée de recherche de 10 heures.
numericHistogram	Les valeurs de dimension dans le résultat sont des plages de valeurs dans une propriété donnée.	L’histogramme numérique de la température peut entraîner un retour de 10 plages de degrés.

Azure Time Series Insights Gen1 limite la cardinalité maximale, ou la taille maximale du réseau, d’une requête d’agrégation d’entrée à 150 000 cellules. Pour calculer la cardinalité d’une requête d’agrégation, vous multipliez les tailles de toutes les dimensions de la requête. Tant que le produit est inférieur à 150 000, la requête est acceptée pour exécution. Si le produit est égal ou inférieur à 150 000, la requête est rejetée.

Vous spécifiez la taille maximale d’une dimension produite par uniqueValues et numericHistogram à l’aide de la clause take . Dans dateHistogram, la taille est calculée en divisant l’étendue de recherche par la taille de l’intervalle dateHistogram , que vous spécifiez à l’aide de la clause breaks .

Par exemple, une requête d’agrégation a l’étendue de recherche définie de « 2017-11-15T16:00:00.000Z » à « 2017-11-15T19:00:00.000Z » = 3 heures. Si la requête inclut dateHistogram avec la clause breaks , définie sur 1 minute (dimension 1) et uniqueValues sur la propriété XYZ, la taille de la dimension dateHistogram est 3x60=180. Ce résultat signifie que uniqueValues peut prendre jusqu’à 150 000/180 = 833 éléments au total.

Expressions de valeurs uniques

Vous utilisez une expression de valeurs unique pour regrouper un ensemble d’événements en fonction des valeurs d’une propriété d’événement spécifiée.

L’évaluation de cette expression JSON génère jusqu’à 100 enregistrements, qui sont regroupés par la sensorId propriété String.

{
  "uniqueValues": {
    "input": {
      "property": "sensorId",
      "type": "String"
    },
    "take": 100
  }
}

Expressions d’histogramme de date

Vous utilisez une expression d’histogramme de date pour regrouper les valeurs de propriété DateTime dans des compartiments d’une taille spécifiée.

L’évaluation de cette expression JSON aboutit à un ensemble d’enregistrements Timestamp arrondis à l’étage, de sorte que chaque valeur a une valeur nulle en secondes.

{
  "dateHistogram": {
    "input": {
      "builtInProperty": "$ts"
    },
    "breaks": {
      "size": "1m"
    }
  }
}

Expressions d’histogramme numérique

Vous utilisez une expression d’histogramme numérique pour regrouper les valeurs de propriété Double dans un nombre spécifié de compartiments.

Une évaluation de cette expression JSON aboutit à 10 enregistrements, de sorte que la plage entre les valeurs minimales et maximales de la propriété p1 est divisée en 10 compartiments.

{
  "numericHistogram": {
    "input": {
      "property": "p1",
      "type": "Double"
    },
    "breaks": {
      "count": 10
    }
  }
}

Expressions de mesure

Vous utilisez des expressions de mesure à l’intérieur de clauses d’agrégats pour calculer une valeur scalaire sur un ensemble d’événements. Par exemple, une expression de mesure est le calcul de la valeur maximale mesurée par un capteur de température au cours des dernières 24 heures.

Vous utilisez une expression count pour calculer le nombre d’événements dans un compartiment correspondant.

{ "count": {} }

Vous utilisez les expressions min, max, avg et sum pour calculer le minimum, le maximum, la moyenne et la somme des valeurs d’une propriété spécifiée dans un compartiment correspondant.

{
  "min": {
    "input": {
      "property": "temperature",
      "type": "Double"
    }
  }
}

Avec les expressions de première et de dernière mesure, vous pouvez obtenir la valeur d’une propriété A spécifiée qui correspond à la valeur minimale ou maximale de la propriété B.

{
  "first": {
    "input": {
      "property": "propertyA",
      "type": "String"
    },
    "orderBy": {
      "property": "propertyB",
      "type": "Double"
    }
  }
}

{
  "last": {
    "input": {
      "property": "propertyA",
      "type": "Double"
    },
    "orderBy": {
      "property": "propertyB",
      "type": "DateTime"
    }
  }
}

La clause orderBy est facultative et correspond par défaut à la propriété Timestamp$ts. L’entrée peut être de n’importe quel type. La clause orderBy prend uniquement en charge les types Double et DateTime .

Si la propriété B est un type DateTime , vous obtenez la valeur la plus récente ou la plus ancienne de la propriété A.

Vous pouvez utiliser la première et la dernière expressions pour vous aider à comprendre la valeur la plus ancienne ou la plus récente d’une propriété spécifique. Par exemple, si vous avez une propriété appelée deviceID et que vous souhaitez comprendre la dernière qui deviceID a envoyé un événement, last est l’opérateur d’expression le plus efficace à utiliser pour identifier ces informations.

{
  "last": {
    "input": {
      "property": "deviceID",
      "type": "String"
    }
  }
}

Un autre exemple consiste à utiliser last pour rechercher le dernier emplacement signalé d’un objet particulier, tel qu’un navire, un véhicule ou un autre objet en mouvement.

Pour illustrer une requête qui produit le dernier emplacement connu des navires dans une flotte, vous pouvez créer une requête semblable à ce qui suit :

{
  "searchSpan": {
    "from": "2018-05-05T12:00:00.000Z",
    "to": "2018-05-15T12:01:00.000Z"
  },
  "aggregates": [
     {
       "dimension": {
         "uniqueValues": {
           "input": {
             "property": "shipId",
             "type": "string"
            },
            "take": 150000
          }
        },
        "measures": [
          {
            "last": {
              "input": {
                "property": "Latitude",
                "type": "Double"
              }
           }
        },
        {
          "last": {
            "input": {
              "property": "Longitude",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Un autre exemple consiste à utiliser d’abord pour trouver un appareil qui signale la pression la plus faible pour chaque usine :

{
  "searchSpan": {
    "from": "2018-05-05T12:00:00.000Z",
    "to": "2018-05-15T12:01:00.000Z"
  },
  "aggregates": [
    {
      "dimension": {
        "uniqueValues": {
          "input": {
            "property": "plantId",
            "type": "String"
          },
          "take": 150000
        }
     },
     "measures": [
       {
         "first": {
           "input": {
             "property": "deviceId",
             "type": "String"
           },
           "orderBy": {
             "property": "pressure",
              "type": "Double"
            }
          }
        }
      ]
    }
  ]
}

Prise en charge des dimensions et des types de mesure

Voici les expressions de dimension et de mesure prises en charge, en fonction du type de propriété :

Type de propriété	Expressions de dimension prises en charge	Expressions de mesure prises en charge
Bool	"uniqueValues"	"first" (entrée), "last" (entrée)
DateTime	"uniqueValues", "dateHistogram"	"min", "max"( "first" orderBy, input), "last” (orderBy, input)
Double	"uniqueValues", "numericHistogram"	"sum", "avg", "min", "max"( "first" orderBy, input), "last” (orderBy, input)
Chaîne	"uniqueValues"	"first" (entrée), "last" (entrée)

Clauses

Les clauses forment des composants constitutifs de requêtes JSON ou d’une partie d’une expression. Les clauses sont divisées en deux catégories :

• Clauses d’étendue de recherche
• Clauses de prédicat
• Limiter les clauses supérieures
• Clauses limit take
• Limiter les exemples de clauses
• Clauses d’interruption
• Clauses d’agrégations

Clauses d’étendue de recherche

Vous utilisez une clause d’étendue de recherche pour filtrer une propriété Timestamp intégrée d’un événement à un intervalle donné. Le début de l’intervalle est inclusif. La fin de l’intervalle est exclusive.

{
  "searchSpan": {
    "from": {
      "dateTime": "2016-08-01T00:00:00.000Z"
    },
    "to": {
      "dateTime": "2016-08-31T00:00:00.000Z"
    }
  }
}

Les propriétés from et to de la clause d’étendue de recherche (searchSpan) doivent être des expressions valides du type de résultat DateTime . Ces expressions sont évaluées avant l’exécution de la requête, ce qui signifie qu’elles ne doivent contenir aucune référence de propriété.

Clauses de prédicat

Vous utilisez une clause de prédicat pour filtrer les événements qui satisfont le prédicat. Il doit être résolu en une expression booléenne .

{
  "predicate": {
    "eq": {
      "left": {
        "property": "p1",
        "type": "String"
       },
       "right": "abc"
     }
  }
}

Filtrer les événements signifie exécuter un prédicat qui est représenté par une expression booléenne sur chaque événement de l’environnement. L’exécution d’une expression sur un événement retourne true si l’événement doit être inclus dans d’autres opérations. Elle retourne false si l’événement doit être omis du traitement ultérieur.

Remarque

Les événements sont toujours filtrés par étendue de recherche, en plus de tout filtrage spécifié dans une expression de prédicat.

Limiter les clauses supérieures

Vous utilisez une clause *limit top pour obtenir un nombre spécifié de valeurs dans l’ordre croissant ou décroissant. Le nombre de valeurs est limité en fonction du nombre spécifié.

{
  "sort": [
    {
      "input": {
        "builtInProperty": "$ts"
      },
      "order": "Asc"
    }
  ],
  "count": 10
}

Clauses limit take

Vous pouvez utiliser une clause limit take comme un moyen rapide d’obtenir un ensemble de valeurs dans aucun ordre particulier. Le nombre de valeurs retournées est limité par l’entrée spécifiée.

{ "take": 10 }

Limiter les exemples de clauses

Vous utilisez une clause *limit sample pour obtenir un exemple statistiquement représentatif à partir d’un ensemble de valeurs. Le nombre de valeurs retournées est limité par l’entrée spécifiée.

{ "sample": 10 }

Clauses d’interruption

Vous utilisez une clause *breaks dans les expressions d’histogramme pour spécifier la façon dont une plage doit être divisée.

Pour les histogrammes de date, vous devez spécifier la taille de l’intervalle datetime et des limites d’intervalle. Vous le faites, sauf si l’histogramme est basé sur une propriété Timestamp intégrée où les limites sont déterminées en fonction de l’étendue de recherche :

• Les limites d’intervalle sont facultatives et peuvent être utilisées. Par exemple, vous pouvez les utiliser lorsqu’ils sont déterminés en fonction d’une étendue de recherche si les limites d’intervalle sont omises.
• Pour les histogrammes numériques, vous devez spécifier le nombre de sauts. Vous déterminez les limites d’intervalle en fonction des valeurs minimales et maximales d’une propriété.

{
  "breaks": {
    "size": "1d",
    "from": "2000-01-02T03:04:05.0000000",
    "to": "2000-01-02T03:04:05.0000000"
  }
}

{
  "breaks": {
    "count": 10
  }
}

Clauses d’agrégations

Vous utilisez une clause d’agrégations pour partitionner un ensemble d’événements par une propriété donnée pendant que vous mesurez les valeurs d’autres propriétés d’événement.

Les mesures sont évaluées sur chaque partition produite par l’expression de dimension.

• L’exemple JSON suivant calcule les températures moyennes, minimales et maximales par ID de capteur.

  {
    "aggregates": [
      {
        "dimension": {
          "uniqueValues": {
            "input": {
              "property": "sensorId",
              "type": "String"
            },
            "take": 100
          }
        },
        "measures": [
          {
            "avg": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          },
          {
            "min": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          },
          {
            "max": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          }
        ]
      }
    ]
  }
  

  Remarque

  Une clause d’agrégats est un tableau qui vous permet de spécifier plusieurs agrégations au niveau le plus élevé.

• L’exemple JSON suivant calcule la température moyenne par ville et par fabricant indépendamment :

  {
    "aggregates": [
      {
        "dimension": {
          "uniqueValues": {
            "input": {
              "property": "city",
              "type": "String"
            },
            "take": 100
          }
        },
        "measures": [
          {
            "avg": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          }
        ]
      },
      {
        "dimension": {
          "uniqueValues": {
            "input": {
              "property": "manufacturer",
              "type": "String"
            },
            "take": 100
          }
        },
        "measures": [
          {
            "avg": {
              "input": {
                "property": "temperature",
                "type": "Double"
              }
            }
          }
        ]
      }
    ]
  }
  

  Remarque

  • Le fait d’avoir plusieurs éléments dans un tableau d’agrégats n’est actuellement pas pris en charge.
  • Toutefois, une définition d’agrégation peut inclure un tableau imbriqué qui spécifie un réseau multidimensionnel plus flexible.

• L’exemple JSON suivant calcule la température moyenne par ID de capteur, par minute.

  {
    "aggregates": [
      {
        "dimension": {
          "uniqueValues": {
            "input": {
              "property": "sensorId",
              "type": "String"
            },
            "take": 100
          }
        },
        "aggregate": {
          "dimension": {
            "dateHistogram": {
              "input": {
                "builtInProperty": "$ts"
              },
              "breaks": {
                "size": "1m"
              }
            }
          },
          "measures": [
            {
              "avg": {
                "input": {
                  "property": "temperature",
                  "type": "Double"
                }
              }
            }
          ]
        }
      }
    ]
  }
  

Voir aussi

• Pour plus d’informations sur les API Azure Time Series Insights Gen1, consultez API Gen1.

• Pour en savoir plus sur les paramètres de requête et d’authentification, consultez Authentification et autorisation.

• Pour en savoir plus sur Azure Time Series Insights Gen1, consultez la documentation Gen1.