本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 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) 操作的許可，這可讓您存取與表達用語相關的分析。[檢視 Lex V2 對話的表達式統計資料](#monitoring-utterances) 如需詳細資訊和要套用至 IAM 角色的 IAM 政策，請參閱 。
+ 下列 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](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",
}
```
## 擷取機器人的指標
使用 `ListSessionMetrics`、`ListIntentStageMetrics`、 `ListIntentMetrics`和 `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`、[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) 物件的清單，每個物件都具有您在請求中指定的 `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](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`欄位，除了從您指定的方法建立的任何 bin 或群組之外，還會傳回您請求之指標的摘要統計資料值。
## 擷取機器人中工作階段和表達用語的中繼資料
使用 [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)。
+ **排序結果** – 使用 `sortBy` 欄位排序結果，其中包含 [SessionDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionDataSortBy.html) 或 [UtteranceDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceDataSortBy.html) 物件。在 `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 的表達用語，您可以將表達用語新增至意圖。意圖的草稿版本會以新的表達用語更新，您可以在將其部署到機器人之前進行測試。
當 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 帳戶，則會刪除所有表達用語。儲存的表達用語會使用伺服器受管金鑰加密。
當您刪除機器人版本時，該版本可使用 表達式統計資料最多 30 天`ListUtteranceMetrics`，使用 則最多 15 天`ListAggregatedUtterances`。您在 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": "*"
}
]
}
```
------