Interrogation des données agrégées

AWS IoT fournit quatre API (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 les API d'agrégation, consultez le guide de résolution des problèmes liés à l'indexation des flottes.

GetStatistics

L'GetStatisticsAPI et la commande get-statistics CLI renvoient 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 get-statistics de l'interface de ligne de commande (CLI) 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 :

• AVERAGE est le pourcentage d'appareils qui correspondent à la requête.

• MINIMUM est 0 ou 1, d'après les règles suivantes :

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

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

  • Si des valeurs du champ d'agrégation sont false et d'autres true, MINIMUM est 0.

• MAXIMUM est 0 ou 1, d'après les règles suivantes :

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

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

  • Si des valeurs du champ d'agrégation sont false et d'autres true, MAXIMUM est 1.

• SUM est la somme de l'équivalent entier des valeurs Booléennes.

• COUNT est 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

L'GetCardinalityAPI et la commande get-cardinality CLI renvoient 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 get-cardinality de l'interface de ligne de commande (CLI) 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

L'GetPercentilesAPI et la commande get-percentiles CLI regroupent 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 commande de l'interface de ligne de commande get-percentiles.

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 get-percentile de l'interface de ligne de commande (CLI) 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

L'GetBucketsAggregationAPI et la commande get-buckets-aggregation CLI renvoient 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 commande get-buckets-aggregation CLI.

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 commande get-buckets-aggregation CLI 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 qu'ARN de ressource dans le cadre d'une action de AWS IoT politique, comme suit.

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