本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 查詢彙總資料
AWS IoT 提供四個 APIs (`GetStatistics`、`GetPercentiles`、 `GetCardinality`和 `GetBucketsAggregation`)，可讓您搜尋裝置機群以取得彙總資料。
**注意**
如需彙總 API 遺失或未預期值的問題，請閱讀[機群索引故障診斷指南](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
}
```
`cardinality` 一律由 **get-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" 包含的彙總欄位值，大約發生在符合查詢的百分之一值。百分位數群組 "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`)。 |