翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 分析に API を使用する
このセクションでは、ボットの分析情報を取得するために使用する 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) を使用するには、発話関連の分析へのアクセスを提供する [ListAggregatedUtterances](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListAggregatedUtterances.html) オペレーションを実行する権限が IAM ロールに必要です。詳細と 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](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`、`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` フィールドを使用して、`Sum`、`Average`、`Max` 数値を計算するかどうかを指定する `statistic` フィールドと、`Ascending` と `Descending` 順序のどちらで結果をソートするかを指定する `order` フィールドを指定します。
**注記**
`metrics` と `binBy` オブジェクトの両方に、`order` フィールドがあります。`order` でのソートを指定できるのは、2 つのオブジェクトのうちの 1 つのみです。
リクエストの残りのフィールドはオプションです。次の方法で検索結果をフィルタリングし、整理できます。
+ **結果のフィルタリング** — `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` オブジェクトには [AnalyticsBinKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinKey.html) オブジェクトのリスト `binKeys` が含まれ、各オブジェクトには、リクエストで指定した `name` と、`value` フィールドでそのビンを定義する時間間隔が含まれます。
**注記**
`metrics` と `binBy` オブジェクトの両方に、`order` フィールドがあります。`order` でのソートを指定できるのは、2 つのオブジェクトのうちの 1 つのみです。
以下のフィールドを使用してレスポンスの表示を処理します。
+ 1 つのレスポンスで返される結果の数を制限するには、`maxResults` フィールドに 1～1,000 の数値を指定します。
+ 結果の数が `maxResults` フィールドで指定した数よりも多い場合、レスポンスには `nextToken` が含まれます。リクエストを再度行い、この値を `nextToken` フィールドに入力して次の結果のバッチを返します。
`ListUtteranceMetrics`を使用している場合は、`attributes` フィールドで返す属性を指定できます。このフィールドは、1 つの [AnalyticSutteranceAttribute](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceAttribute.html) オブジェクトを含むリストにマップされます。発話時に Amazon Lex V2 が使用していたインテントを返すように `LastUsedIntent` フィールドで `name` を指定します。
レスポンスでは、`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` フィールドが含まれています。
## ボットのセッションと発話のメタデータを取得する
[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` フィールドで `Descending` と `Ascending` 順のどちらでソートするかを指定します。
以下のフィールドを使用してレスポンスの表示を処理します。
+ 1 つのレスポンスで返される結果の数を制限するには、`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) オブジェクトのリストにマップされます。各オブジェクトには、1 つのセッションまたは発話のメタデータが含まれています。
## インテントパス分析データの取得
[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 を使用して生成されません。
+ コンソールでボットを作成した際、児童オンラインプライバシー保護法の設定が **[はい]** と設定されていた、または `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](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": "*"
}
]
}
```
------