本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# APIs 用于分析
本节介绍用于检索机器人分析的 API 操作。
**注意**
要使用[ListUtteranceMetrics](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)操作会检索有关客户在与机器人对话时所采用的意图顺序的指标。
## 筛选结果
您需要针对 Analytics API 请求来指定 `startTime` 和 `endTime`。API 将返回在 `startTime` *之后*开始并在 `endTime` *之前*结束的会话、意图、意图阶段或言语。
`filters` 是 Analytics API 请求中的可选字段。它映射到[AnalyticsSessionFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionFilter.html)、[AnalyticsIntentFilter[AnalyticsIntentStageFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageFilter.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentFilter.html)、或[AnalyticsUtteranceFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceFilter.html)对象的列表。在每个对象中，使用字段创建表达式以作为筛选条件。例如，如果您将以下筛选条件添加到列表中，则机器人将搜索时长超过 30 秒的对话。
```
{
"name": "Duration",
"operator": "GT",
"value": "30 sec",
}
```
## 检索机器人的指标
使用 `ListSessionMetrics`、`ListIntentMetrics`、`ListIntentStageMetrics` 和 `ListUtteranceMetrics` 操作来检索*会话*、*意图*、*意图阶段*和*言语*的摘要指标。
对于这些操作，请填写以下必填字段：
+ 提供 `startTime` 和 `endTime` 以定义要检索结果的时间范围。
+ 指定要计算的指标`metrics`、[AnalyticsSessionMetric[AnalyticsIntentMetric[AnalyticsIntentStageMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageMetric.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentMetric.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionMetric.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[AnalyticsIntentStageResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageResult.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentResult.html)、或[AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html)对象的列表。在对象中，指定要以其为基础对结果进行分组的类别的 `name` 字段。
如果您在请求中指定一个`groupBy`字段，则响应中的`results`对象将包含`groupByKeys`、[AnalyticsSessionGroupByKey[AnalyticsIntentGroupByKey[AnalyticsIntentStageGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageGroupByKey.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentGroupByKey.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionGroupByKey.html)、或[AnalyticsUtteranceGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceGroupByKey.html)多个对象的列表，每个对象都`name`包含您在请求中指定的，`value`字段中包含该类别的成员。
+ **按时间对结果进行分**箱-指定`binBy`字段，即包含单个[AnalyticsBinBySpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinBySpecification.html)对象的列表。在对象中，将 `name` 字段指定为 `ConversationStartTime` 以便按对话开始的时间对结果进行分箱，或者指定为 `UtteranceTimestamp` 以便按言语发生的时间对结果进行分箱。在 `interval` 字段中指定要对结果进行分箱的时间间隔，并且在 `order` 字段中指定排序是 `Ascending` 还是 `Descending`。
如果您在请求中指定一个`binBy`字段，则响应中的`results`对象将包含`binKeys`一个[AnalyticsBinKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinKey.html)对象列表，每个对象都`name`包含您在请求中指定的对象以及`value`字段中定义该数据桶的时间间隔。
**注意**
`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)对象的列表。在 `name` 字段中指定 `LastUsedIntent`，以返回 Amazon Lex V2 在言语时使用的意图。
在响应中，该`results`字段映射到[AnalyticsSessionResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionResult.html)、[AnalyticsIntentResult[AnalyticsIntentStageResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageResult.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentResult.html)、或[AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html)对象的列表。每个对象均包含 `metrics` 字段，以返回您所请求的指标的汇总统计数据以及使用您指定的方法创建的任何数据分箱或组。
## 在机器人中检索会话和言语的元数据
使用[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)对象的列表。每个对象均包含单个会话或言语的元数据。
## 检索意图路径分析数据
使用该[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 对话中的言语统计数据
您可以使用言语统计数据来确定您的用户向机器人发送的言语。系统将统计 Amazon Lex V2 成功检测到的言语以及未成功检测到的言语。您可以使用此信息来优化机器人。
例如，如果您发现用户正在发送 Amazon Lex V2 遗漏的言语，则可以将该言语添加到意图中。系统将使用新的言语来更新此意图的 Draft 版本，以便您在将其部署到机器人之前对其进行测试。
当 Amazon Lex V2 将某个言语识别为试图调用为机器人配置的意图时，该言语即被检测到。当 Amazon Lex V2 未能识别某个言语而是调用 `AMAZON.FallbackIntent` 时，将错过该言语。
可以使用 `ListUtteranceMetrics` API 和 `ListAggregatedUtterance` API 来查看言语统计信息。
以下条件下，系统不会使用 `ListUtteranceMetrics` API 生成言语统计数据：
+ 当使用控制台创建机器人时，“儿童在线隐私保护法案”设置被设置为**是**，或者在使用 `CreateBot` 操作创建机器人时，`childDirected` 字段被设置为 true。
该 `ListUtteranceMetrics` API 还提供其他功能，包括：
+ 更多可用信息，例如检测到言语的被映射意图。
+ 更多筛选功能（包括频道和模式）。
+ 更长的保留日期范围（30 天）。
+ 即使您已选择退出数据存储，也可以使用该 API。控制台依赖于 `ListUtteranceMetrics` API 来实现对遗漏和检测到的言语的功能。
以下条件下，系统不会使用 `ListAggregatedUtterance` API 生成言语统计数据：
+ 当使用控制台创建机器人时，“儿童在线隐私保护法案”设置被设置为**是**，或者在使用 `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` APIs，则话语按话语的文本汇总。例如，客户发出“我想订购披萨”的话语的所有实例均会在回复中汇总到同一行中。使用该[RecognizeUtterance](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeUtterance.html)操作时，使用的文本是输入脚本。
要使用`ListAggregatedUtterances`和 `ListUtteranceMetrics` APIs，请将以下策略应用于角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ListAggregatedUtterancesPolicy",
"Effect": "Allow",
"Action": "lex:ListAggregatedUtterances",
"Resource": "*"
}
]
}
```
------