使用 APIs進行分析

焦點模式

使用 APIs進行分析 - Amazon Lex

篩選結果擷取機器人的指標擷取機器人中工作階段和表達用語的中繼資料擷取機器人中工作階段和表達用語的中繼資料從 Lex V2 對話檢視表達式統計資料

本節說明您用來擷取機器人分析的 API 操作。

注意

若要使用 ListUtteranceMetrics 和 ListUtteranceAnalyticsData，您的 IAM 角色必須具有執行 ListAggregatedUtterances 操作的許可，這可讓您存取與表達用語相關的分析。如需詳細資訊和要套用至 IAM 角色的 IAM 政策，從 Lex V2 對話檢視表達式統計資料請參閱。

下列 API 操作會擷取機器人的摘要指標：
下列 API 操作會擷取工作階段和表達用語的中繼資料清單：
- ListSessionAnalyticsData
- ListUtteranceAnalyticsData
ListIntentPaths 操作會擷取有關客戶在與機器人對話時所採取意圖順序的指標。

篩選結果

Analytics API 請求需要您指定 startTime和 endTime。API 會傳回在之後開始startTime並在之前結束的工作階段、意圖、意圖階段或表達用語endTime。

filters 是 Analytics API 請求中的選用欄位。它映射到 AnalyticsSessionFilter、AnalyticsIntentFilter、AnalyticsIntentStageFilter 或 AnalyticsUtteranceFilter 物件的清單。在每個物件中，使用欄位來建立要篩選的表達式。例如，如果您將下列篩選條件新增至清單，機器人會搜尋超過 30 秒的對話。


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

擷取機器人的指標

使用 ListSessionMetrics、ListIntentStageMetrics、 ListIntentMetrics和 ListUtteranceMetrics操作來擷取工作階段、意圖、意圖階段和表達用語的摘要指標。

對於這些操作，請填寫下列必要欄位：

提供 startTime和 endTime 來定義您要擷取結果的時間範圍。
指定您要在中計算的指標metrics，即 AnalyticsSessionMetric、AnalyticsIntentMetric、AnalyticsIntentStageMetric 或 AnalyticsUtteranceMetric 物件的清單。在每個物件中，使用 name 欄位指定指標來計算 statistic 欄位，以指定是否計算 Sum、 Average或 Max數字，以及使用 order 欄位來指定是否依 Ascending或 Descending順序排序結果。

注意
metrics 和 binBy 物件都包含 order 欄位。您只能在兩個物件之一order中指定排序。

請求中的其餘欄位是選用的。您可以透過下列方式篩選和組織結果：

篩選結果 – 使用 filters 欄位篩選結果。如需詳細資訊，請參閱篩選結果。
依類別分組結果 – 指定 groupBy 欄位、包含單一 AnalyticsSessionResult、AnalyticsIntentResult、AnalyticsIntentStageResult 或 AnalyticsUtteranceResult 物件的清單。在物件中，使用您要將結果分組的類別指定 name 欄位。

如果您在請求中指定groupBy欄位，回應中的results物件會包含 groupByKeys、AnalyticsSessionGroupByKey、AnalyticsIntentGroupByKey、AnalyticsIntentStageGroupByKey 或 AnalyticsUtteranceGroupByKey 物件的清單，每個物件都具有您在請求中指定的 name ，以及 value 欄位中該類別的成員。
依時間繫結結果 – 指定 binBy 欄位，此為包含單一 AnalyticsBinBySpecification 物件的清單。在物件中，使用指定 name 欄位ConversationStartTime，以透過對話開始時分隔結果UtteranceTimestamp，或透過發生表達用語時分隔結果。指定您要在 interval 欄位中將結果綁定的時間間隔，以及是否要在 order 欄位中依Ascending時間Descending順序排序。

如果您在請求中指定binBy欄位，回應中的results物件會包含 binKeys，AnalyticsBinKey 物件的清單，每個物件都有您在請求中指定的 name，以及定義value該欄位內儲存貯體的時間間隔。

注意
metrics 和 binBy 物件都包含 order 欄位。您只能在兩個物件之一order中指定排序。

使用下列欄位來處理回應的顯示：

在 maxResults 欄位中指定介於 1 到 1，000 之間的數字，以限制在單一回應中傳回的結果數量。
如果結果數目大於您在 maxResults 欄位中指定的數目，回應會包含 nextToken。再次提出請求，但在 nextToken 欄位中使用此值來傳回下一批結果。

如果您使用的是 ListUtteranceMetrics，則可以在 attributes 欄位中指定要傳回的屬性。此欄位會映射至包含單一 AnalyticsUtteranceAttribute 物件的清單。在 name LastUsedIntent欄位中指定，以傳回 Amazon Lex V2 在表達用語時正在使用的意圖。

在回應中， results 欄位會映射至 AnalyticsSessionResult、AnalyticsIntentResult、AnalyticsIntentStageResult 或 AnalyticsUtteranceResult 物件的清單。每個物件都包含一個metrics欄位，除了從您指定的方法建立的任何 bin 或群組之外，還會傳回您請求之指標的摘要統計資料值。

擷取機器人中工作階段和表達用語的中繼資料

使用 ListSessionAnalyticsData 和 ListUtteranceAnalyticsData 操作來擷取個別工作階段和表達用語的中繼資料。

填寫必要 startTime和 endTime 欄位，以定義您要擷取結果的時間範圍。

請求中的其餘欄位是選用的。若要篩選和排序結果：

篩選結果 – 使用 filters 欄位篩選結果。如需詳細資訊，請參閱篩選結果。
排序結果 – 使用 sortBy 欄位排序結果，其中包含 SessionDataSortBy 或 UtteranceDataSortBy 物件。在 name 欄位中指定您要排序的值，以及是否要在 order 欄位中排序Ascending或Descending排序。

使用下列欄位來處理回應的顯示：

在 maxResults 欄位中指定介於 1 到 1，000 之間的數字，以限制在單一回應中傳回的結果數量。
如果結果數目大於您在 maxResults 欄位中指定的數目，回應會包含 nextToken。再次提出請求，但在 nextToken 欄位中使用此值來傳回下一批結果。

在回應中， sessions或 utterances 欄位會映射至 SessionSpecification 或 UtteranceSpecification 物件的清單。每個物件都包含單一工作階段或表達用語的中繼資料。

擷取機器人中工作階段和表達用語的中繼資料

使用 ListIntentPaths 操作來擷取有關客戶與機器人對話時所採取意圖順序的指標。

針對此操作，請填寫下列必要欄位：

提供 startTime和 endTime 來定義您要擷取結果的時間範圍。
提供 intentPath來定義您要擷取指標的意圖順序。以斜線分隔路徑中的意圖。例如，將 intentPath 欄位填入 /BookCar/BookHotel ，以查看使用者依該順序叫用 BookCar和 BookHotel意圖的次數詳細資訊。

使用選用filters欄位來篩選結果。如需詳細資訊，請參閱篩選結果。

從 Lex V2 對話檢視表達式統計資料

您可以使用表達用語統計資料來判斷使用者傳送給機器人的表達用語。您可以看到 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 設定設為 Yes，或使用 CreateBot操作建立機器人時， childDirected 欄位設為 true。

ListUtteranceMetrics API 提供額外功能，包括：

更多可用資訊，例如偵測到的表達用語的映射意圖。
更多篩選功能（包括頻道和模式）。
較長的保留日期範圍 (30 天）。
即使您已選擇退出資料儲存，也可以使用 API。遺漏和偵測到的表達用語的主控台功能將依賴 ListUtteranceMetrics API。

在下列情況下，不會使用 ListAggregatedUtterance API 產生張量統計資料：

使用主控台建立機器人時，Child Online Privacy Protection Act 設定設為 Yes，或使用 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 操作時，使用的文字是輸入文字記錄。

若要使用 ListAggregatedUtterances和 ListUtteranceMetrics APIs，請將下列政策套用至角色。


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