As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Consulta de dados agregados
AWS IoT fornece quatro APIs (`GetStatistics`,`GetCardinality`,`GetPercentiles`, e`GetBucketsAggregation`) que permitem pesquisar dados agregados em sua frota de dispositivos.
**nota**
Para problemas com valores ausentes ou inesperados para a agregação APIs, leia o guia de solução de [problemas de indexação de frotas](fleet-indexing-troubleshooting.md).
## GetStatistics
A [GetStatistics](https://docs.aws.amazon.com/iot/latest/apireference/API_GetStatistics.html)API e o comando **get-statistics** CLI retornam a contagem, a média, a soma, o mínimo, o máximo, a soma dos quadrados, a variância e o desvio padrão para o campo agregado especificado.
O comando da CLI **get-statistics** usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregationField`
(Opcional) O campo a ser agregado. Esse campo deve ser um campo gerenciado ou personalizado definido ao chamar **update-indexing-configuration**. Se você não especificar um campo de agregação, `registry.version` será usado como o campo de agregação.
`query-version`
A versão da consulta a ser usada. O valor padrão é `2017-09-30`.
O tipo de campo de agregação pode afetar as estatísticas retornadas.
### GetStatistics com valores de string
Se você agregar em um campo de string, chamar `GetStatistics` retornará uma contagem de dispositivos que têm atributos que correspondem à consulta. Por exemplo:
```
aws iot get-statistics --aggregation-field 'attributes.stringAttribute'
--query-string '*'
```
Esse comando retorna o número de dispositivos que contêm um atributo chamado `stringAttribute`:
```
{
"statistics": {
"count": 3
}
}
```
### GetStatistics com valores booleanos
Quando você chama `GetStatistics` com um campo de agregação booliano:
+ AVERAGE é a porcentagem de dispositivos que correspondem à consulta.
+ MINIMUM é 0 ou 1 conforme as seguintes regras:
+ Se todos os valores do campo de agregação forem `false`, MINIMUM será 0.
+ Se todos os valores do campo de agregação forem `true`, MINIMUM será 1.
+ Se os valores do campo de agregação forem uma mistura de `false` e `true`, MINIMUM será 0.
+ MAXIMUM é 0 ou 1 conforme as seguintes regras:
+ Se todos os valores do campo de agregação forem `false`, MAXIMUM será 0.
+ Se todos os valores do campo de agregação forem `true`, MAXIMUM será 1.
+ Se os valores do campo de agregação forem uma mistura de `false` e `true`, MAXIMUM será 1.
+ SUM é a soma do equivalente inteiro dos valores boolianos.
+ COUNT é a contagem de objetos que correspondem aos critérios da string de consulta e contêm um valor de campo de agregação válido.
### GetStatistics com valores numéricos
Quando você chama `GetStatistics` e especifica um campo de agregação do tipo `Number`, `GetStatistics` retorna os seguintes valores:
contagem
A contagem de objetos que correspondem aos critérios da string de consulta e contêm um valor de campo de agregação válido.
média
A média dos valores numéricos que correspondem à consulta.
soma
A soma dos valores numéricos que correspondem à consulta.
mínimo
O menor dos valores numéricos que correspondem à consulta.
máximo
O maior dos valores numéricos que correspondem à consulta.
sumOfSquares
A soma dos quadrados dos valores numéricos que correspondem à consulta.
variância
A variação dos valores numéricos que correspondem à consulta. A variância de um conjunto de valores é a média dos quadrados das diferenças de cada valor em relação ao valor médio do conjunto.
stdDeviation
O desvio padrão dos valores numéricos que correspondem à consulta. O desvio padrão de um conjunto de valores é uma medida de como os valores estão distribuídos.
O exemplo a seguir mostra como chamar **get-statistics** com um campo personalizado numérico.
```
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
}
}
```
Para campos de agregação numéricos, se os valores de campo excederem o valor duplo máximo, os valores estatísticos estarão vazios.
## GetCardinality
A [GetCardinality](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCardinality.html)API e o comando **get-cardinality** CLI retornam a contagem aproximada de valores exclusivos que correspondem à consulta. Por exemplo, você pode querer encontrar o número de dispositivos com níveis de bateria inferiores a 50%:
```
aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel
> 50" --aggregation-field "shadow.reported.batterylevel"
```
Este comando retorna o número de itens com níveis de bateria superiores a 50%:
```
{
"cardinality": 100
}
```
`cardinality` é sempre retornado por **get-cardinality** mesmo se não houver campos correspondentes. Por exemplo:
```
aws iot get-cardinality --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_STR"
```
```
{
"cardinality": 0
}
```
O comando da CLI **get-cardinality** usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregationField`
O campo a ser agregado.
`query-version`
A versão da consulta a ser usada. O valor padrão é `2017-09-30`.
## GetPercentiles
A [GetPercentiles](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPercentiles.html)API e o comando **get-percentiles** CLI agrupam os valores agregados que correspondem à consulta em agrupamentos de percentis. Os agrupamentos de percentil padrão são: 1, 5, 25, 50, 75, 95, 99, embora você possa especificar o seu próprio quando chamar `GetPercentiles`. Esta função retorna um valor para cada grupo de percentis especificado (ou os agrupamentos de percentil padrão). O grupo de percentis “1” contém o valor de campo agregado que ocorre em aproximadamente um por cento dos valores que correspondem à consulta. O grupo de percentil “5” contém o valor de campo agregado que ocorre em aproximadamente cinco por cento dos valores que correspondem à consulta, e assim por diante. O resultado é uma aproximação. Quanto mais valores correspondem à consulta, mais precisos os valores do percentil.
O exemplo a seguir mostra como chamar o comando **get-percentiles** da CLI.
```
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
}
]
}
```
O comando a seguir mostra a saída retornada de **get-percentiles** quando não há documentos correspondentes.
```
aws iot get-percentiles --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_NUM"
```
```
{
"percentiles": []
}
```
O comando da CLI **get-percentile** usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregationField`
O campo a ser agregado, que deve ser do tipo `Number`.
`query-version`
A versão da consulta a ser usada. O valor padrão é `2017-09-30`.
`percents`
(Opcional) você pode usar esse parâmetro para especificar agrupamentos de percentil personalizados.
## GetBucketsAggregation
A [GetBucketsAggregation](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API e o comando **get-buckets-aggregation** CLI retornam uma lista de buckets e o número total de itens que se encaixam nos critérios da sequência de caracteres de consulta.
O exemplo a seguir mostra como chamar o comando get-buckets-aggregation da CLI.
```
aws iot get-buckets-aggregation --query-string '*' --index-name AWS_Things --aggregation-field 'shadow.reported.batterylevelpercent' --buckets-aggregation-type 'termsAggregation={maxBuckets=5}'
```
O comando retorna os seguintes:
```
{
"totalCount": 20,
"buckets": [
{
"keyValue": "100",
"count": 12
},
{
"keyValue": "90",
"count": 5
},
{
"keyValue": "75",
"count": 3
}
]
}
```
O comando da CLI get-buckets-aggregation usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregation-field`
O campo a ser agregado.
`buckets-aggregation-type`
O controle básico da forma de resposta e do tipo de agregação do bucket a ser executado.
## Autorização
Você pode especificar o índice de grupos de coisas como um ARN de recurso em uma ação de AWS IoT política, da seguinte maneira.
| Ação | Recurso |
| --- | --- |
| `iot:GetStatistics` | O ARN de um índice (por exemplo, `arn:aws:iot:your-aws-region:index/AWS_Things` ou `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`). |