기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 집계 데이터 쿼리
AWS IoT 는 디바이스 플릿에서 집계 데이터를 검색할 수 있는 4APIs(`GetStatistics`, `GetCardinality``GetPercentiles`, 및 `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
쿼리 문자열 기준과 일치하고 유효한 집계 필드 값을 포함하는 항목의 개수입니다.
평균
쿼리와 일치하는 숫자 값의 평균입니다.
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"에는 쿼리와 일치하는 값의 약 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`
수행할 응답 형태 및 버킷 집계 유형의 기본 제어입니다.
## 권한 부여
다음과 같이 AWS IoT 정책 작업에서 사물 그룹 인덱스를 리소스 ARN으로 지정할 수 있습니다.
| 작업 | Resource |
| --- | --- |
| `iot:GetStatistics` | 인덱스 ARN(예: `arn:aws:iot:your-aws-region:index/AWS_Things` 또는 `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`) |