本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 查询聚合数据
AWS IoT 提供了四个 APIs （`GetStatistics``GetCardinality`、`GetPercentiles`、和`GetBucketsAggregation`），允许您在设备群中搜索聚合数据。
**注意**
有关聚合值缺失或意外的问题 APIs，请阅读[舰队索引疑难解答指南](fleet-indexing-troubleshooting.md)。
## GetStatistics
[GetStatistics](https://docs.aws.amazon.com/iot/latest/apireference/API_GetStatistics.html)API 和 **get-statistics** CLI 命令返回指定聚合字段的计数、平均值、总和、最小值、最大值、平方和、方差和标准差。
**get-statistics** CLI 命令使用以下参数：
`index-name`
要搜索的索引的名称。默认值为 `AWS_Things`。
`query-string`
用于搜索索引的查询。您可以指定`"*"`获取您 AWS 账户中所有已编入索引的内容的数量。
`aggregationField`
（可选）要聚合的字段。此字段必须是在调用 **update-indexing-configuration** 时定义的托管字段或自定义字段。如果不指定聚合字段，则 `registry.version` 用作聚合字段。
`query-version`
要使用的查询的版本。默认值为 `2017-09-30`。
聚合字段的类型可能会影响返回的统计信息。
### GetStatistics 使用字符串值
如果在字符串字段上进行聚合，则调用 `GetStatistics` 会返回具有与查询匹配的属性的设备计数。例如：
```
aws iot get-statistics --aggregation-field 'attributes.stringAttribute'
--query-string '*'
```
此命令会返回包含 `stringAttribute` 属性的设备数量：
```
{
"statistics": {
"count": 3
}
}
```
### GetStatistics 使用布尔值
当您使用布尔聚合字段调用 `GetStatistics` 时：
+ AVERAGE 是匹配查询的设备的百分比。
+ 根据以下规则，MINIMUM 为 0 或 1：
+ 如果聚合字段的所有值均为 `false`，则 MINIMUM 为 0。
+ 如果聚合字段的所有值均为 `true`，则 MINIMUM 为 1。
+ 如果聚合字段的值既有 `false` 又有 `true`，则 MINIMUM 为 0。
+ 根据以下规则，MAXIMUM 为 0 或 1：
+ 如果聚合字段的所有值均为 `false`，则 MAXIMUM 为 0。
+ 如果聚合字段的所有值均为 `true`，则 MAXIMUM 为 1。
+ 如果聚合字段的值既有 `false` 又有 `true`，则 MAXIMUM 为 1。
+ SUM 是等效于布尔值的整数的总和。
+ COUNT 是符合查询字符串条件且包含有效聚合字段值的内容计数。
### GetStatistics 用数值
调用 `GetStatistics` 并指定 `Number` 类型的聚合字段时，`GetStatistics` 返回以下值：
count
与查询字符串条件匹配并包含有效聚合字段值的事物的计数。
average
与查询匹配的数值的平均值。
sum
与查询匹配的数值的总和。
minimum
与查询匹配的数值中的最小值。
maximum
与查询匹配的数值中的最大值。
sumOfSquares
与查询匹配的数值的平方和。
variance
与查询匹配的数值的方差。一组值的方差是每个值与该组值平均值之间差值的平方的平均值。
stdDeviation
与查询匹配的数值的标准差。一组值的标准差用于衡量值的分布程度。
以下示例演示了如何使用数值自定义字段调用 **get-statistics**。
```
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
}
}
```
对于数值聚合字段，如果字段值超过最大双精度值，则统计值为空。
## GetCardinality
[GetCardinality](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCardinality.html)API 和 **get-cardinality** CLI 命令返回与查询相匹配的唯一值的大致数量。例如，您可能需要查找电池电量低于 50% 的设备数量：
```
aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel
> 50" --aggregation-field "shadow.reported.batterylevel"
```
此命令返回电池电量超过 50% 的事物数量：
```
{
"cardinality": 100
}
```
即使没有匹配字段，**get-cardinality** 也始终返回 `cardinality`。例如：
```
aws iot get-cardinality --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_STR"
```
```
{
"cardinality": 0
}
```
**get-cardinality** CLI 命令使用以下参数：
`index-name`
要搜索的索引的名称。默认值为 `AWS_Things`。
`query-string`
用于搜索索引的查询。您可以指定`"*"`获取您 AWS 账户中所有已编入索引的内容的数量。
`aggregationField`
要聚合的字段。
`query-version`
要使用的查询的版本。默认值为 `2017-09-30`。
## GetPercentiles
[GetPercentiles](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPercentiles.html)API 和 **get-percentiles** CLI 命令将与查询匹配的聚合值分组为百分位分组。默认百分位数分组为：1,5,25,50,75,95,99，不过您可以在调用 `GetPercentiles` 时指定自己的百分位数分组。此函数为指定的每个百分位数组（或默认百分位数分组）返回一个值。百分位数组“1”包含在与查询匹配的值的大约 1% 中出现的聚合字段值。百分位数组“5”包含在与查询匹配的值的大约 5% 中出现的聚合字段值，以此类推。结果是近似值，与查询匹配的值越多，百分位数值就越准确。
以下示例演示了如何调用 **get-percentiles** 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
}
]
}
```
以下命令显示没有匹配文档时从 **get-percentiles** 返回的输出。
```
aws iot get-percentiles --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_NUM"
```
```
{
"percentiles": []
}
```
**get-percentile** CLI 命令使用以下参数：
`index-name`
要搜索的索引的名称。默认值为 `AWS_Things`。
`query-string`
用于搜索索引的查询。您可以指定`"*"`获取您 AWS 账户中所有已编入索引的内容的数量。
`aggregationField`
要聚合的字段，必须为 `Number` 类型。
`query-version`
要使用的查询的版本。默认值为 `2017-09-30`。
`percents`
（可选）您可以使用此参数指定自定义百分位数分组。
## GetBucketsAggregation
[GetBucketsAggregation](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API 和 **get-buckets-aggregation** CLI 命令会返回存储桶列表以及符合查询字符串条件的内容总数。
以下示例演示了如何调用 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}'
```
此命令将返回以下：
```
{
"totalCount": 20,
"buckets": [
{
"keyValue": "100",
"count": 12
},
{
"keyValue": "90",
"count": 5
},
{
"keyValue": "75",
"count": 3
}
]
}
```
get-buckets-aggregation CLI 命令使用以下参数：
`index-name`
要搜索的索引的名称。默认值为 `AWS_Things`。
`query-string`
用于搜索索引的查询。您可以指定`"*"`获取您 AWS 账户中所有已编入索引的内容的数量。
`aggregation-field`
要聚合的字段。
`buckets-aggregation-type`
对响应形状和要执行的存储桶聚合类型的基本控制。
## Authorization
您可以在 AWS IoT 策略操作中将事物组索引指定为资源 ARN，如下所示。
| Action | 资源 |
| --- | --- |
| `iot:GetStatistics` | 索引 ARN（例如，`arn:aws:iot:your-aws-region:index/AWS_Things` 或 `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`）。 |