Interrogation des données agrégées

AWS IoT en fournit quatre APIs (GetStatistics, GetCardinalityGetPercentiles, etGetBucketsAggregation) qui vous permettent de rechercher des données agrégées dans votre parc d'appareils.

Note

Pour les problèmes liés à des valeurs manquantes ou inattendues pour l'agrégationAPIs, consultez le guide de résolution des problèmes liés à l'indexation de la flotte.

GetStatistics

La get-statistics CLI commande GetStatisticsAPIet renvoie le nombre, la moyenne, la somme, le minimum, le maximum, la somme des carrés, la variance et l'écart type pour le champ agrégé spécifié.

La commande CLI d'get-statistics utilise les paramètres suivants :

index-name

Nom de l'index dans lequel effectuer la recherche. La valeur par défaut est AWS_Things.

query-string

Nom de la requête utilisée pour recherche dans l'index. Vous pouvez spécifier "*" d'obtenir le nombre de tous les éléments indexés dans votre Compte AWS.

aggregationField

(Facultatif) Le champ à agréger. Ce champ doit être un champ géré ou personnalisé défini lorsque vous appelez update-indexing-configuration. Si vous ne spécifiez pas de champ d'agrégation, registry.version est utilisé comme le champ d'agrégation.

query-version

Version de la requête à utiliser. La valeur par défaut est 2017-09-30.

Le type de champ d'agrégation peut affecter les statistiques renvoyées.

GetStatistics avec des valeurs de chaîne

Si vous regroupez les données en fonction d'un champ de chaîne, l'appel à GetStatistics renvoie un nombre d'appareils dont les attributs correspondent à la requête. Par exemple :

aws iot get-statistics --aggregation-field 'attributes.stringAttribute'
            --query-string '*'

Cette commande renvoie le nombre d'appareils qui contiennent un attribut nommé stringAttribute :

{
  "statistics": {
    "count": 3
  }
}

GetStatistics avec des valeurs booléennes

Lorsque vous appelez GetStatistics avec un champ d'agrégation Booléen :

• AVERAGEest le pourcentage d'appareils qui répondent à la requête.

• MINIMUMest égal à 0 ou 1 selon les règles suivantes :

  • Si toutes les valeurs du champ d'agrégation MINIMUM sont false égales à 0.

  • Si toutes les valeurs du champ d'agrégation MINIMUM sont true égales à 1.

  • Si les valeurs du champ d'agrégation sont une combinaison de false ettrue, MINIMUM est égale à 0.

• MAXIMUMest égal à 0 ou 1 selon les règles suivantes :

  • Si toutes les valeurs du champ d'agrégation MAXIMUM sont false égales à 0.

  • Si toutes les valeurs du champ d'agrégation MAXIMUM sont true égales à 1.

  • Si les valeurs du champ d'agrégation sont une combinaison de false ettrue, MAXIMUM vaut 1.

• SUMest la somme de l'équivalent entier des valeurs booléennes.

• COUNTest le nombre d'éléments qui correspondent aux critères de chaîne de requête et contiennent une valeur de champ d'agrégation valide.

GetStatistics avec des valeurs numériques

Lorsque vous appelez GetStatistics et spécifiez un champ d'agrégation de type Number, GetStatistics renvoie les valeurs suivantes :

count

Nombre d'éléments qui correspondent aux critères de la chaîne de requête et contiennent une valeur de champ d'agrégation valide.

average

Moyenne des valeurs numériques qui correspondent à la requête.

sum

Somme des valeurs numériques qui correspondent à la requête.

minimum

La plus petite des valeurs numériques qui correspondent à la requête.

maximum

La plus grande des valeurs numériques qui correspondent à la requête.

sumOfSquares

Somme des carrés des valeurs numériques qui correspondent à la requête.

variance

Variance des valeurs numériques qui correspondent à la requête. La variance d'un ensemble de valeurs est la moyenne des carrés des différences de chaque valeur par rapport à la valeur moyenne de l'ensemble.

stdDeviation

Écart type des valeurs numériques qui correspondent à la requête. L'écart type d'un ensemble de valeurs est une mesure de la répartition des valeurs.

L'exemple suivant montre comment appeler get-statistics avec un champ numérique personnalisé.

aws iot get-statistics --aggregation-field 'attributes.numericAttribute2'
            --query-string '*'

{
  "statistics": {
    "count": 3,
    "average": 33.333333333333336,
    "sum": 100.0,
    "minimum": -125.0,
    "maximum": 150.0,
    "sumOfSquares": 43750.0,
    "variance": 13472.22222222222,
    "stdDeviation": 116.06990230986766
  }
}

crée votre index la première fois que vous indexez.​

GetCardinality

La get-cardinality CLI commande GetCardinalityAPIet renvoie le nombre approximatif de valeurs uniques correspondant à la requête. Par exemple, vous pouvez trouver le nombre d'appareils dont le niveau de batterie est inférieur à 50 % :

aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel
          > 50" --aggregation-field "shadow.reported.batterylevel"

Cette commande renvoie le nombre d'objets dont le niveau de batterie est supérieur à 50 % :

{
    "cardinality": 100
}

cardinality est toujours renvoyé par get-cardinality, même s'il n'y a pas de champs correspondants. Par exemple :

aws iot get-cardinality --query-string "thingName:Non-existent*"
          --aggregation-field "attributes.customField_STR"

{
    "cardinality": 0
}

La commande CLI d'get-cardinality utilise les paramètres suivants :

index-name

Nom de l'index dans lequel effectuer la recherche. La valeur par défaut est AWS_Things.

query-string

Nom de la requête utilisée pour recherche dans l'index. Vous pouvez spécifier "*" d'obtenir le nombre de tous les éléments indexés dans votre Compte AWS.

aggregationField

Champ à agréger.

query-version

Version de la requête à utiliser. La valeur par défaut est 2017-09-30.

GetPercentiles

La get-percentiles CLI commande GetPercentilesAPIet regroupe les valeurs agrégées correspondant à la requête en groupes percentiles. Les groupes de centiles par défaut sont : 1,5,25,50,75,95,99, bien que vous puissiez spécifier les vôtres lorsque vous appelez GetPercentiles. Cette fonction renvoie une valeur pour chaque groupe de centiles spécifié (ou les groupes de centiles par défaut). Le groupe de centiles « 1 » contient la valeur de champ agrégée qui se produit dans environ 1 % des valeurs qui correspondent à la requête. Le groupe de centiles « 5 » contient la valeur de champ agrégée qui se produit dans environ 5 % des valeurs qui correspondent à la requête, etc. Le résultat est une approximation. Plus les valeurs correspondent à la requête, plus les valeurs de centile sont précises.

L'exemple suivant montre comment appeler la get-percentiles CLI commande.

aws iot get-percentiles --query-string "thingName:*" --aggregation-field
          "attributes.customField_NUM" --percents 10 20 30 40 50 60 70 80 90 99

{
    "percentiles": [
        {
            "value": 3.0,
            "percent": 80.0
        },
        {
            "value": 2.5999999999999996,
            "percent": 70.0
        },
        {
            "value": 3.0,
            "percent": 90.0
        },
        {
            "value": 2.0,
            "percent": 50.0
        },
        {
            "value": 2.0,
            "percent": 60.0
        },
        {
            "value": 1.0,
            "percent": 10.0
        },
        {
            "value": 2.0,
            "percent": 40.0
        },
        {
            "value": 1.0,
            "percent": 20.0
        },
        {
            "value": 1.4,
            "percent": 30.0
        },
        {
            "value": 3.0,
            "percent": 99.0
        }
    ]
}

La commande suivante affiche la sortie renvoyée par get-percentiles lorsqu'il n'y a pas de documents correspondants.

aws iot get-percentiles --query-string "thingName:Non-existent*"
          --aggregation-field "attributes.customField_NUM"

{
    "percentiles": []
}

La commande CLI d'get-percentile utilise les paramètres suivants :

index-name

Nom de l'index dans lequel effectuer la recherche. La valeur par défaut est AWS_Things.

query-string

Nom de la requête utilisée pour recherche dans l'index. Vous pouvez spécifier "*" d'obtenir le nombre de tous les éléments indexés dans votre Compte AWS.

aggregationField

Champ à agréger, dont le type doit être Number.

query-version

Version de la requête à utiliser. La valeur par défaut est 2017-09-30.

percents

(Facultatif) Vous pouvez utiliser ce paramètre pour spécifier des regroupements de centiles personnalisés.

GetBucketsAggregation

La GetBucketsAggregationAPIget-buckets-aggregationCLIcommande and renvoie une liste de compartiments et le nombre total d'éléments correspondant aux critères de chaîne de requête.

L'exemple suivant montre comment appeler la get-buckets-aggregation CLI commande.

aws iot get-buckets-aggregation --query-string '*' --index-name AWS_Things --aggregation-field 'shadow.reported.batterylevelpercent' --buckets-aggregation-type 'termsAggregation={maxBuckets=5}'

Cette commande renvoie ce qui suit :

{
    "totalCount": 20,
    "buckets": [
        {
            "keyValue": "100",
            "count": 12
        },
        {
            "keyValue": "90",
            "count": 5
        },
        {
            "keyValue": "75",
            "count": 3
        }
    ]
}

La get-buckets-aggregation CLI commande prend les paramètres suivants :

index-name

Nom de l'index dans lequel effectuer la recherche. La valeur par défaut est AWS_Things.

query-string

Nom de la requête utilisée pour recherche dans l'index. Vous pouvez spécifier "*" d'obtenir le nombre de tous les éléments indexés dans votre Compte AWS.

aggregation-field

Champ à agréger.

buckets-aggregation-type

Contrôle de base de la forme de réponse et du type d'agrégation de compartiments à effectuer.

Autorisation

Vous pouvez spécifier l'index des groupes d'objets en tant que ressource ARN dans le cadre d'une action AWS IoT politique, comme suit.

Action	Ressource
iot:GetStatistics	Un index ARN (par exemple, arn:aws:iot:your-aws-region:index/AWS_Things ouarn:aws:iot:your-aws-region:index/AWS_ThingGroups).