Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Interrogazione di dati aggregati
AWS IoT fornisce quattro APIs (`GetStatistics`, `GetCardinality``GetPercentiles`, e`GetBucketsAggregation`) che consentono di cercare dati aggregati nel parco dispositivi.
**Nota**
Per problemi relativi ai valori mancanti o imprevisti per l'aggregazione APIs, leggi la guida alla risoluzione dei problemi di [indicizzazione del parco veicoli](fleet-indexing-troubleshooting.md).
## GetStatistics
L'[GetStatistics](https://docs.aws.amazon.com/iot/latest/apireference/API_GetStatistics.html)API e il comando **get-statistics** CLI restituiscono il conteggio, la media, la somma, il minimo, il massimo, la somma dei quadrati, la varianza e la deviazione standard per il campo aggregato specificato.
Il comando CLI **get-statistics** accetta i parametri seguenti:
`index-name`
Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è `AWS_Things`.
`query-string`
La query usata per eseguire la ricerca nell'indice. Puoi specificare di ottenere il conteggio `"*"` di tutte le cose indicizzate nel tuo. Account AWS
`aggregationField`
(Facoltativo) Il campo da aggregare. Questo campo deve essere un campo gestito o personalizzato definito quando si chiama **update-indexing-configuration**. Se non specifichi un campo di aggregazione, viene utilizzato `registry.version` come campo di aggregazione.
`query-version`
La versione della query da usare. Il valore predefinito è `2017-09-30`.
Il tipo di campo di aggregazione può influenzare le statistiche restituite.
### GetStatistics con valori di stringa
Se si aggrega in un campo stringa, la chiamata `GetStatistics` restituisce un conteggio di dispositivi con attributi che corrispondono alla query. Ad esempio:
```
aws iot get-statistics --aggregation-field 'attributes.stringAttribute'
--query-string '*'
```
Questo comando restituisce il numero di dispositivi che contengono un attributo denominato `stringAttribute`:
```
{
"statistics": {
"count": 3
}
}
```
### GetStatistics con valori booleani
Quando chiami `GetStatistics` con un campo di aggregazione booleano:
+ AVERAGE è la percentuale di dispositivi che corrispondono alla query.
+ MINIMUM è 0 o 1 secondo le seguenti regole:
+ Se tutti i valori per il campo di aggregazione sono `false`, MINIMUM è 0.
+ Se tutti i valori per il campo di aggregazione sono `true`, MINIMUM è 1.
+ Se i valori per il campo di aggregazione sono una miscela di `false` e `true`, MINIMUM è 0.
+ MAXIMUM è 0 o 1 secondo le seguenti regole:
+ Se tutti i valori per il campo di aggregazione sono `false`, MAXIMUM è 0.
+ Se tutti i valori per il campo di aggregazione sono `true`, MAXIMUM è 1.
+ Se i valori per il campo di aggregazione sono una miscela di `false` e `true`, MAXIMUM è 1.
+ SUM è la somma dell'equivalente intero dei valori booleani.
+ COUNT è il numero di oggetti che corrispondono ai criteri della stringa di query e contengono un valore di campo di aggregazione valido.
### GetStatistics con valori numerici
Quando si chiama `GetStatistics` e si specifica un campo di aggregazione di tipo `Number`, `GetStatistics` restituisce i seguenti valori:
count
Numero di oggetti che corrispondono ai criteri della stringa di query e contengono un valore di campo di aggregazione valido.
average
La media dei valori numerici che corrispondono alla query.
sum
La somma dei valori numerici che corrispondono alla query.
minimum
Il più piccolo dei valori numerici che corrisponde alla query.
maximum
Il più grande dei valori numerici che corrisponde alla query.
sumOfSquares
La somma dei quadrati dei valori numerici che corrispondono alla query.
variance
La varianza dei valori numerici che corrispondono alla query. La varianza di un insieme di valori è la media dei quadrati delle differenze di ciascun valore rispetto al valore medio del set.
stdDeviation
La deviazione standard dei valori numerici che corrispondono alla query. La deviazione standard di un insieme di valori è una misura di quanto sono distribuiti i valori.
Nell'esempio seguente viene illustrato come chiamare **get-statistics** con un campo personalizzato numerico.
```
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
}
}
```
Per i campi di aggregazione numerica, se i valori dei campi superano il valore doppio massimo, i valori delle statistiche sono vuoti.
## GetCardinality
L'[GetCardinality](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCardinality.html)API e il comando **get-cardinality** CLI restituiscono il conteggio approssimativo di valori univoci che corrispondono alla query. Ad esempio, potresti cercare il numero di dispositivi con livelli di batteria inferiori al 50%:
```
aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel
> 50" --aggregation-field "shadow.reported.batterylevel"
```
Questo comando restituisce il numero di elementi con livelli di batteria oltre il 50%:
```
{
"cardinality": 100
}
```
`cardinality` viene sempre restituito da **get-cardinality** anche se non ci sono campi corrispondenti. Ad esempio:
```
aws iot get-cardinality --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_STR"
```
```
{
"cardinality": 0
}
```
Il comando CLI **get-cardinality** accetta i parametri seguenti:
`index-name`
Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è `AWS_Things`.
`query-string`
La query usata per eseguire la ricerca nell'indice. Puoi specificare di `"*"` ottenere il conteggio di tutte le cose indicizzate nel tuo. Account AWS
`aggregationField`
Il campo da aggregare.
`query-version`
La versione della query da usare. Il valore predefinito è `2017-09-30`.
## GetPercentiles
L'[GetPercentiles](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPercentiles.html)API e il comando **get-percentiles** CLI raggruppano i valori aggregati che corrispondono alla query in raggruppamenti percentili. I raggruppamenti percentili predefiniti sono: 1, 5, 25, 50, 75, 95, 99, anche se è possibile specificare il proprio quando si chiama `GetPercentiles`. Questa funzione restituisce un valore per ogni gruppo percentile specificato (o i raggruppamenti percentili predefiniti). Il gruppo percentile "1" contiene il valore del campo aggregato che si verifica in circa l'1% dei valori corrispondenti alla query. Il gruppo percentile "5" contiene il valore del campo aggregato che si verifica in circa il cinque percento dei valori corrispondenti alla query e così via. Il risultato è un'approssimazione, più valori corrispondono alla query, più precisi sono i valori percentili.
Nell'esempio seguente viene illustrato come chiamare il comando CLI **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
}
]
}
```
Il comando seguente mostra l'output restituito da **get-percentiles** quando non ci sono documenti corrispondenti.
```
aws iot get-percentiles --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_NUM"
```
```
{
"percentiles": []
}
```
Il comando CLI **get-percentile** accetta i parametri seguenti:
`index-name`
Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è `AWS_Things`.
`query-string`
La query usata per eseguire la ricerca nell'indice. Puoi specificare di `"*"` ottenere il conteggio di tutte le cose indicizzate nel tuo. Account AWS
`aggregationField`
Il campo da aggregare, che deve essere di tipo `Number`.
`query-version`
La versione della query da usare. Il valore predefinito è `2017-09-30`.
`percents`
(Facoltativo) È possibile utilizzare questo parametro per specificare raggruppamenti percentili personalizzati.
## GetBucketsAggregation
L'[GetBucketsAggregation](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API e il comando **get-buckets-aggregation** CLI restituiscono un elenco di bucket e il numero totale di elementi che soddisfano i criteri della stringa di query.
Nell'esempio seguente viene illustrato come chiamare il comando CLI 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}'
```
Questo comando restituisce quanto segue:
```
{
"totalCount": 20,
"buckets": [
{
"keyValue": "100",
"count": 12
},
{
"keyValue": "90",
"count": 5
},
{
"keyValue": "75",
"count": 3
}
]
}
```
Il comando CLI get-buckets-aggregation accetta i parametri seguenti:
`index-name`
Nome dell'indice su cui eseguire una ricerca. Il valore predefinito è `AWS_Things`.
`query-string`
La query usata per eseguire la ricerca nell'indice. Puoi specificare di `"*"` ottenere il conteggio di tutte le cose indicizzate nel tuo. Account AWS
`aggregation-field`
Il campo da aggregare.
`buckets-aggregation-type`
Il controllo di base della forma di risposta e il tipo di aggregazione del bucket da eseguire.
## Autorizzazione
È possibile specificare l'indice dei gruppi di oggetti come ARN di risorse in un'azione AWS IoT politica, come segue.
| Azione | Risorsa |
| --- | --- |
| `iot:GetStatistics` | Un indice ARN (ad esempio `arn:aws:iot:your-aws-region:index/AWS_Things` o `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`). |