Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Interrogation des données agrégées
AWS IoT en fournit quatre APIs (`GetStatistics`, `GetCardinality``GetPercentiles`, et`GetBucketsAggregation`) 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égation APIs, consultez le [guide de résolution des problèmes liés à l'indexation de la flotte](fleet-indexing-troubleshooting.md).
## GetStatistics
L'[GetStatistics](https://docs.aws.amazon.com/iot/latest/apireference/API_GetStatistics.html)API 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'[GetCardinality](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCardinality.html)API 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'[GetPercentiles](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPercentiles.html)API 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'[GetBucketsAggregation](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API 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 de l'interface de ligne de commande get-buckets-aggregation.
```
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 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.
`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`). |