翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 集計データのクエリ
AWS IoT には`GetStatistics`、デバイスフリートで集計データを検索`GetBucketsAggregation`できる 4 つの APIs (`GetCardinality`、`GetPercentiles`、、) が用意されています。
**注記**
集約 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` は次の値を返します。
数
クエリ文字列条件に一致し、有効な集計フィールドの値を含むモモノの数。
平均
クエリに一致する数値の平均。
sum
クエリに一致する数値の合計。
minimum
クエリに一致する数値のうち最小の値。
maximum
クエリに一致する数値のうち最大値。
sumOfSquares
クエリに一致する数値の二乗の合計。
分散
クエリに一致する数値の分散。値の集合の分散は、集合の平均値からの各値の差の二乗の平均です。
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」には、クエリに一致する値の約 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`)。 |