分析に API を使用する

このセクションでは、ボットの分析情報を取得するために使用する API オペレーションについて説明します。

注記

ListUtteranceMetrics と ListUtteranceAnalyticsData を使用するには、発話関連の分析へのアクセスを提供する ListAggregatedUtterances オペレーションを実行する権限が IAM ロールに必要です。詳細と IAM ロールに適用する IAM ポリシーについては、「Lex V2 会話の発話統計の表示」を参照してください。

• 次の API オペレーションでは、ボットのサマリーメトリクスを取得します。

  • ListSessionMetrics

  • ListIntentMetrics

  • ListIntentStageMetrics

  • ListUtteranceMetrics

• 次の 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、ListIntentMetrics、ListIntentStageMetrics および ListUtteranceMetrics オペレーションを使用して、セッション、インテント、インテントステージ、発話のサマリーメトリクスを取得します。

これらのオペレーションでは、以下の必須フィールドに入力してください。

• startTime と endTime を入力して、結果を取得する時間範囲を定義します。

• metrics で計算するメトリクス、AnalyticsSessionMetric、AnalyticsIntentMetric、AnalyticsIntentStageMetric、または AnalyticsUtteranceMetric オブジェクトのリストを指定します。各オブジェクトで、name フィールドを使用して、Sum、Average、Max 数値を計算するかどうかを指定する statistic フィールドと、Ascending と Descending 順序のどちらで結果をソートするかを指定する order フィールドを指定します。

  注記

  metrics と binBy オブジェクトの両方に、order フィールドがあります。order でのソートを指定できるのは、2 つのオブジェクトのうちの 1 つのみです。

リクエストの残りのフィールドはオプションです。次の方法で検索結果をフィルタリングし、整理できます。

• 結果のフィルタリング — 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 オブジェクトには AnalyticsBinKey オブジェクトのリスト binKeys が含まれ、各オブジェクトには、リクエストで指定した name と、value フィールドでそのビンを定義する時間間隔が含まれます。

  注記

  metrics と binBy オブジェクトの両方に、order フィールドがあります。order でのソートを指定できるのは、2 つのオブジェクトのうちの 1 つのみです。

以下のフィールドを使用してレスポンスの表示を処理します。

• 1 つのレスポンスで返される結果の数を制限するには、maxResults フィールドに 1～1,000 の数値を指定します。

• 結果の数が maxResults フィールドで指定した数よりも多い場合、レスポンスには nextToken が含まれます。リクエストを再度行い、この値を nextToken フィールドに入力して次の結果のバッチを返します。

ListUtteranceMetricsを使用している場合は、attributes フィールドで返す属性を指定できます。このフィールドは、1 つの AnalyticSutteranceAttribute オブジェクトを含むリストにマップされます。発話時に Amazon Lex V2 が使用していたインテントを返すように LastUsedIntent フィールドで name を指定します。

レスポンスでは、results フィールドが AnalyticsSessionResult、AnalyticsIntentResult、AnalyticsIntentStageResult、または AnalyticsUtteranceResult オブジェクトのリストにマップされます。各オブジェクトには、指定したメソッドから作成されたビンまたはグループに加えて、要求したメトリクスの要約統計の値を返す metrics フィールドが含まれています。

ボットのセッションと発話のメタデータを取得する

ListSessionAnalyticsData オペレーションと ListUtteranceAnalyticsData オペレーションを使用して、個々のセッションと発話に関するメタデータを取得します。

必須の startTime と endTime フィールドを入力して、結果を取得する時間範囲を定義します。

リクエストの残りのフィールドはオプションです。結果をフィルタリングしてソートするには:

• 結果のフィルタリング — filters フィールドを使用して結果をフィルタリングします。詳細については、「結果のフィルタリング」を参照してください。

• 結果のソート — SessionDataSortBy オブジェクトまたは UtteranceDataSortBy オブジェクトを含む sortBy フィールドを使用して結果をソートします。name フィールド内で並べ替える値と、order フィールドで Descending と Ascending 順のどちらでソートするかを指定します。

以下のフィールドを使用してレスポンスの表示を処理します。

• 1 つのレスポンスで返される結果の数を制限するには、maxResults フィールドに 1～1,000 の数値を指定します。

• 結果の数が maxResults フィールドで指定した数よりも多い場合、レスポンスには nextToken が含まれます。リクエストを再度行い、この値を nextToken フィールドに入力して次の結果のバッチを返します。

レスポンスで、sessions または utterances フィールドが SessionSpecification オブジェクトまたは UtteranceSpecification オブジェクトのリストにマップされます。各オブジェクトには、1 つのセッションまたは発話のメタデータが含まれています。

ボットのセッションと発話のメタデータを取得する

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 を使用して生成されません。

• コンソールでボットを作成した際、児童オンラインプライバシー保護法の設定が [はい] と設定されていた、または childDirected フィールドが true に設定されていた場合は、CreateBot オペレーションでボットを作成した時です。

ListUtteranceMetrics API には次のような追加機能もあります。

• 検出された発話のインテントのマッピングなど、より多くの情報を入手できます。

• より多くのフィルタリング機能 (チャネルとモードを含む)。

• 保持日付範囲が長い (30 日間)。

• データストレージをオプトアウトしていても API を使用できます。聞き逃した発話や検出された発話のコンソール機能は ListUtteranceMetrics API に依存します。

発話の統計は、以下の条件で ListAggregatedUtterance API を使用して生成されません。

• コンソールでボットを作成した際、児童オンラインプライバシー保護法の設定が [はい] と設定されていた、または childDirected フィールドが true に設定されていた場合は、CreateBot オペレーションでボットを作成した時です。

• 1 つ以上のスロットでスロットの難読化を使用しています。

• Amazon Lex の改善への参加をオプトアウトしました。

ListAggregatedUtterance API には次のような機能もあります。

• 詳細情報を減らします (発話のインテントのマッピングなし)。

• 限定されたフィルタリング機能 (チャネルとモードを含まない)。

• 保持日付範囲が短い (15 日間)。

発話統計を使用すると、特定の発話が検出された、または見逃されたか、ボットインタラクションで発話が最後に使用されたかを確認できます。

Amazon Lex V2 は、ユーザーがボットと対話している間、発話を継続的に保存します。コンソールまたは、ListAggregatedUtterances オペレーションを使用して統計をクエリできます。データ保持期間は 15 日間で、ユーザーがデータストレージをオプトアウトした場合は使用できません。DeleteUtterances オペレーションまたはデータストレージのオプトアウトにより、発話を削除することができます。 AWS アカウントを閉鎖すると、すべての発話が削除されます。保存された発話は、サーバーマネージドキーで暗号化されます。

ボットバージョンを削除すると、そのバージョンの発話統計は ListUtteranceMetrics の場合は最大 30 日間、ListAggregatedUtterances を使用する場合は 15 日間使用できます。Amazon Lex V2 コンソールでは、削除されたバージョンの統計を表示できません。削除されたバージョンの統計を表示するには、ListAggregatedUtterances と ListUtteranceMetrics オペレーション両方を使用します。

ListAggregatedUtterances と ListUtteranceMetrics API の両方で、発話は発話のテキストによって集計されます。例えば、顧客が「ピザを注文したい」というフレーズを使用したすべてのインスタンスは、応答の同じ行に集約されます。RecognizeUtterance オペレーションを使用するとき、使用されるテキストは入力文字起こしです。

ListAggregatedUtterances と ListUtteranceMetrics API を使用するには、以下のポリシーをロールに適用してください。

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