기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 분석을 위한 API 사용
<a name="analytics-api"></a>

이 섹션에서는 봇에 대한 분석을 검색하는 데 사용하는 API 작업에 대해 설명합니다.

**참고**  
[ListSutteranceMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceMetrics.html) 및 [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html)를 사용하려면 IAM 역할에 발화 관련 분석에 대한 액세스를 제공하는 [ListAggregatedUtterances](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListAggregatedUtterances.html) 작업을 수행할 수 있는 권한이 있어야 합니다. IAM 역할에 적용되는 IAM 정책 및 세부 정보는 [Lex V2 대화에서 발화 통계 보기](#monitoring-utterances) 단원을 참조하세요.
+ 다음 API 작업은 봇에 대한 요약 지표를 검색합니다.
  + [ListSessionMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionMetrics.html)
  + [ListIntentMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentMetrics.html)
  + [ListIntentStageMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentStageMetrics.html)
  + [ListUtteranceMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceMetrics.html)
+ 다음 API 작업은 세션 및 발화에 대한 메타데이터 목록을 가져옵니다.
  + [ListSessionAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionAnalyticsData.html)
  + [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html)
+ [ListIntentPaths](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentPaths.html) 작업은 고객이 봇과 대화할 때 취하는 의도 순서에 대한 지표를 검색합니다.

## 결과 필터링
<a name="analytics-api-filters"></a>

Analytics API 요청에는 `startTime` 및 `endTime`을 지정해야 합니다. API는 `startTime` *이후*에 시작되어 `endTime` *이전*에 종료된 세션, 의도, 의도 단계 또는 발화를 반환합니다.

`filters`는 Analytics API 요청의 선택적 필드입니다. [AnalyticsSessionFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionFilter.html), [AnalyticsIntentFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentFilter.html), [AnalyticsIntentStageFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageFilter.html) 또는 [AnalyticsUtteranceFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceFilter.html) 객체의 목록에 매핑됩니다. 각 객체에서 필드를 사용하여 필터링 기준으로 사용할 식을 만드세요. 예를 들어 목록에 다음 필터를 추가하면 봇은 30초 이상의 대화를 검색합니다.

```
{
    "name": "Duration",
    "operator": "GT",
    "value": "30 sec",
}
```

## 봇에 대한 지표 검색
<a name="analytics-api-metrics"></a>

`ListSessionMetrics`, `ListIntentMetrics`, `ListIntentStageMetrics` 및 `ListUtteranceMetrics` 작업을 사용하여 *세션*, *의도*, *의도 단계* 및 *발화*에 대한 요약 지표를 검색할 수 있습니다.

이러한 작업의 경우 다음 필수 필드를 채우세요.
+ 결과를 검색하려는 시간 범위를 정의하려면 `startTime` 및 `endTime`을 입력합니다.
+ `metrics`에서 계산하려는 지표를 [AnalyticsSessionMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionMetric.html), [AnalyticsIntentMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentMetric.html), [AnalyticsIntentStageMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageMetric.html) 또는 [AnalyticsUtteranceMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceMetric.html) 객체 목록으로 지정합니다. 각 객체에서 `name` 필드를 사용하여 계산할 메트릭을 지정하고, `statistic` 필드를 사용하여 `Sum`, `Average` 또는 `Max` 수치를 계산할지 여부를 지정하고, `order` 필드를 사용하여 결과를 `Ascending` 또는 `Descending` 순서로 정렬할지 여부를 지정합니다.
**참고**  
`metrics`와 `binBy` 객체 모두 `order` 필드를 포함합니다. 두 객체 중 하나에만 정렬 `order`를 지정할 수 있습니다.

요청의 나머지 필드는 선택 사항입니다. 다음과 같은 방법으로 결과를 필터링하고 구성할 수 있습니다.
+ **결과 필터링** - `filters` 필드를 사용하여 결과를 필터링합니다. 자세한 내용은 [결과 필터링](#analytics-api-filters) 단원을 참조하세요.
+ **범주별 결과 그룹화** – `groupBy` 필드, 즉 단일 [AnalyticsSessionResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionResult.html), [AnalyticsIntentResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentResult.html), [AnalyticsIntentStageResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageResult.html) 또는 [AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html) 객체가 포함된 목록을 지정합니다. 객체에서 결과를 그룹화할 범주가 있는 `name` 필드를 지정합니다.

  요청에 `groupBy` 필드를 지정한 경우 응답의 `results` 객체에는 `groupByKeys`, 요청에 지정한 `name`과 `value` 필드에 해당 카테고리의 멤버가 각각 포함된 [AnalyticsSessionGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionGroupByKey.html), [AnalyticsIntentGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentGroupByKey.html), [AnalyticsIntentStageGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageGroupByKey.html) 또는 [AnalyticsUtteranceGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceGroupByKey.html) 객체 목록이 포함되어 있습니다.
+ **시간별 결과 이진화** – `binBy` 필드, 즉 단일 [AnalyticsBinBySpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinBySpecification.html) 객체가 포함된 목록을 지정합니다. 객체에서 대화가 시작된 시점을 기준으로 결과를 범주화하려면 `ConversationStartTime`을 사용하여 `name` 필드를 지정하고, 발화가 발생한 시점을 기준으로 결과를 범주화하려면 `UtteranceTimestamp`를 사용하여 이름 필드를 지정합니다. `interval` 필드에서 결과를 구간화할 시간 간격을 지정하고, `order` 필드에서 `Ascending` 또는 `Descending` 순서로 정렬할지 여부를 지정합니다.

  요청에서 `binBy` 필드를 지정하는 경우 응답의 `results` 객체에는 각각 요청에서 지정한 `name`과 `value` 필드에서 해당 구간을 정의하는 시간 간격을 가진 [AnalyticsBinKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinKey.html) 객체 목록인 `binKeys`가 포함됩니다.
**참고**  
`metrics`와 `binBy` 객체 모두 `order` 필드를 포함합니다. 두 객체 중 하나에만 정렬 `order`를 지정할 수 있습니다.

다음 필드를 사용하여 응답 표시를 처리하세요.
+ `maxResults` 필드에 1에서 1,000 사이의 숫자를 지정하여 단일 응답에서 반환되는 결과 수를 제한하세요.
+ 결과 수가 `maxResults` 필드에 지정한 수보다 많으면 응답에 `nextToken`이 포함됩니다. 요청을 다시 하되, `nextToken` 필드에서 이 값을 사용하면 다음 일괄 결과를 반환할 수 있습니다.

`ListUtteranceMetrics`를 사용하는 경우 `attributes` 필드에 반환할 속성을 지정할 수 있습니다. 이 필드는 단일 [AnalyticSutteranceAttribute](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceAttribute.html) 객체를 포함하는 목록에 매핑됩니다. 발화 당시 Amazon Lex V2가 사용 중인 의도를 반환하려면 `name` 필드에 `LastUsedIntent`를 지정하세요.

응답에서 `results` 필드는 [AnalyticsSessionResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionResult.html), [AnalyticsIntentResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentResult.html), [AnalyticsIntentStageResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageResult.html) 또는 [AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html) 객체의 목록에 매핑됩니다. 각 객체에는 지정한 메서드에서 만든 구간차원 또는 그룹 외에도 요청한 지표에 대한 요약 통계 값을 반환하는 `metrics` 필드가 포함되어 있습니다.

## 봇의 세션 및 발화에 대한 메타데이터 검색
<a name="analytics-api-metadata"></a>

[ListSessionAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionAnalyticsData.html) 및 [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html) 작업을 사용하여 개별 세션 및 발화에 대한 메타데이터를 검색할 수 있습니다.

필수 `startTime` 및 `endTime` 필드를 입력하여 결과를 검색할 시간 범위를 정의합니다.

요청의 나머지 필드는 선택 사항입니다. 결과를 필터링하고 정렬하는 방법:
+ **결과 필터링** - `filters` 필드를 사용하여 결과를 필터링합니다. 자세한 내용은 [결과 필터링](#analytics-api-filters) 단원을 참조하세요.
+ **결과 정렬** – [SessionDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionDataSortBy.html) 또는 [UtteranceDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceDataSortBy.html) 객체가 포함된 `sortBy` 필드를 사용하여 결과를 정렬합니다. `name` 필드에 정렬할 값을 지정하고 `order` 필드에 `Ascending` 또는 `Descending` 순서로 정렬할지 여부를 지정합니다.

다음 필드를 사용하여 응답 표시를 처리하세요.
+ `maxResults` 필드에 1에서 1,000 사이의 숫자를 지정하여 단일 응답에서 반환되는 결과 수를 제한하세요.
+ 결과 수가 `maxResults` 필드에 지정한 수보다 많으면 응답에 `nextToken`이 포함됩니다. 요청을 다시 하되, `nextToken` 필드에서 이 값을 사용하면 다음 일괄 결과를 반환할 수 있습니다.

응답에서 `sessions` 또는 `utterances` 필드는 [SessionSpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionSpecification.html) 또는 [UtteranceSpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceSpecification.html) 객체 목록에 매핑됩니다. 각 객체에는 단일 세션 또는 발화에 대한 메타데이터가 들어 있습니다.

## 의도 경로 분석 데이터 검색
<a name="analytics-api-paths"></a>

[ListIntentPaths](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentPaths.html) 작업을 사용하면 고객이 봇과 대화할 때 취하는 의도 순서에 대한 메트릭을 검색할 수 있습니다.

이 작업을 수행하려면 다음 필수 필드를 채우세요.
+ 결과를 검색하려는 시간 범위를 정의하려면 `startTime` 및 `endTime`을 입력합니다.
+ `intentPath`를 제공하여 지표를 검색할 의도의 순서를 정의합니다. 경로에 있는 의도를 슬래시로 구분합니다. 예를 들어 `intentPath` 필드에 **/BookCar/BookHotel**을 입력하면 사용자가 해당 순서로 `BookCar` 및 `BookHotel` 의도를 간접적으로 호출한 횟수에 대한 세부 정보가 표시됩니다.

선택적인 `filters` 필드를 사용하여 결과를 필터링할 수 있습니다. 자세한 내용은 [결과 필터링](#analytics-api-filters) 섹션을 참조하세요.

## Lex V2 대화에서 발화 통계 보기
<a name="monitoring-utterances"></a>



발화 통계를 사용하여 사용자가 봇에 보내는 발화를 확인할 수 있습니다. Amazon Lex V2에서 성공적으로 감지한 발화와 감지하지 못한 발화를 모두 볼 수 있습니다. 이 정보를 사용하여 봇을 조정하는 데 도움을 줄 수 있습니다.

예를 들어, 사용자가 Amazon Lex V2에서 놓친 내용을 보내는 것을 발견한 경우 해당 발화를 의도에 추가할 수 있습니다. 의도의 초안 버전이 새 말로 업데이트되므로 봇에 배포하기 전에 테스트할 수 있습니다.

Amazon Lex V2가 해당 발화를 봇용으로 구성된 의도를 간접적으로 호출하려는 시도로 인식하면 발화가 감지됩니다. Amazon Lex V2가 표현을 인식하지 못하고 대신 `AMAZON.FallbackIntent`를 간접적으로 호출하면 표현을 놓친 것입니다.

발화 통계는 `ListUtteranceMetrics` API와 `ListAggregatedUtterance` API를 사용하여 볼 수 있습니다.

다음 조건에서는 `ListUtteranceMetrics` API를 사용하여 발화 통계가 생성되지 않습니다.
+ 콘솔을 사용하여 봇을 만들 때는 Child Online Privacy Protection Act 설정이 **예**로 설정되었고, `CreateBot` 작업을 통해 봇을 만들 때는 `childDirected` 필드가 true로 설정되었습니다.

`ListUtteranceMetrics` API는 다음과 같은 추가 기능을 제공합니다.
+ 감지된 발화에 대한 매핑된 의도와 같은 추가 정보를 확인할 수 있습니다.
+ 더 많은 필터링 기능(채널 및 모드 포함).
+ 보존 날짜 범위 연장(30일).
+ 데이터 스토리지를 옵트아웃한 경우에도 API를 사용할 수 있습니다. 놓친 발화 및 감지된 발화에 대한 콘솔 기능은 `ListUtteranceMetrics` API에 따라 달라집니다.

다음 조건에서는 `ListAggregatedUtterance` API를 사용하여 발화 통계가 생성되지 않습니다.
+ 콘솔을 사용하여 봇을 만들 때는 Child Online Privacy Protection Act 설정이 **예**로 설정되었고, `CreateBot` 작업을 통해 봇을 만들 때는 `childDirected` 필드가 true로 설정되었습니다.
+ 하나 이상의 슬롯에서 슬롯 난독화 기능을 사용하고 있습니다.
+ Amazon Lex 개선에 참여하지 않기로 선택했습니다.

`ListAggregatedUtterance` API는 다음과 같은 기능을 제공합니다.
+ 사용 가능한 세부 정보가 적습니다(발화에 대해 매핑된 의도 없음).
+ 제한된 필터링 기능(채널 및 모드 제외).
+ 짧은 보존 날짜 범위(15일).

발화 통계를 사용하면 봇 상호 작용에서 해당 발화가 마지막으로 사용된 시간과 함께 특정 발화가 감지되었는지 또는 누락되었는지 확인할 수 있습니다.

Amazon Lex V2는 사용자가 봇과 상호 작용하는 동안 지속적으로 발화를 저장합니다. 콘솔 또는 `ListAggregatedUtterances` 작업을 사용하여 통계를 쿼리할 수 있습니다. 데이터 보존 기간은 15일이며, 사용자가 데이터 스토리지에서 옵트아웃한 경우에는 사용할 수 없습니다. `DeleteUtterances` 작업을 사용하거나 데이터 스토리지에서 옵트아웃하여 발화를 삭제할 수 있습니다. AWS 계정을 닫으면 모든 발화가 삭제됩니다. 저장된 발화는 서버에서 관리하는 키로 암호화됩니다.

봇 버전을 삭제하면 `ListUtteranceMetrics`를 사용하여 최대 30일 동안 버전에 대한 발화 통계를 사용할 수 있고 `ListAggregatedUtterances`를 사용하여 15일 동안 사용할 수 있습니다. Amazon Lex V2 콘솔에서는 삭제된 버전에 대한 통계를 볼 수 없습니다. 삭제된 버전의 통계를 보려면 `ListAggregatedUtterances` 및 `ListUtteranceMetrics` 작업을 모두 사용할 수 있습니다.

`ListAggregatedUtterances` 및 `ListUtteranceMetrics` API 모두에서 발화는 발화 텍스트를 기준으로 집계됩니다. 예를 들어 고객이 “피자를 주문하고 싶어요”라는 문구를 사용한 모든 인스턴스는 응답에서 동일한 행으로 집계됩니다. [RecognizEtterance](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeUtterance.html) 작업을 사용할 때 사용되는 텍스트는 입력 대화 기록입니다.

`ListAggregatedUtterances` 및 `ListUtteranceMetrics` API를 사용하려면 다음 정책을 역할에 적용하세요.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "ListAggregatedUtterancesPolicy",
            "Effect": "Allow",
            "Action": "lex:ListAggregatedUtterances",
            "Resource": "*"
        }
    ]
}
```

------