Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Utilisation des API pour les analyses
Cette section décrit les opérations d'API que vous utilisez pour récupérer les analyses d'un bot.
**Note**
Pour utiliser le [ListUtteranceMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceMetrics.html)et [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html), votre rôle IAM doit disposer des autorisations nécessaires pour effectuer l'[ListAggregatedUtterances](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListAggregatedUtterances.html)opération, ce qui donne accès aux analyses relatives aux énoncés. Consultez [Afficher les statistiques relatives aux énoncés issus de conversations avec Lex V2](#monitoring-utterances) pour plus de détails et la politique IAM à appliquer au rôle IAM.
+ Les opérations d'API suivantes permettent de récupérer des métriques récapitulatives pour un bot :
+ [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)
+ Les opérations d'API suivantes extraient une liste de métadonnées pour les sessions et les énoncés :
+ [ListSessionAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionAnalyticsData.html)
+ [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html)
+ L'[ListIntentPaths](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentPaths.html)opération récupère des statistiques relatives à un ordre d'intention suivi par les clients lors de conversations avec un bot.
## Filtrer les résultats
Les demandes d'API Analytics nécessitent que vous spécifiiez le `startTime` et`endTime`. *L'API renvoie les sessions, les intentions, les étapes d'intention ou les énoncés qui ont commencé *après* le `startTime` et se sont terminés avant le.* `endTime`
`filters`est un champ facultatif dans les demandes de l'API Analytics. Il correspond à une liste de [AnalyticsSessionFilter[AnalyticsIntentFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentFilter.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionFilter.html), [AnalyticsIntentStageFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageFilter.html), ou [AnalyticsUtteranceFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceFilter.html)objets. Dans chaque objet, utilisez les champs pour créer une expression à filtrer. Par exemple, si vous ajoutez le filtre suivant à la liste, le bot recherche les conversations de plus de 30 secondes.
```
{
"name": "Duration",
"operator": "GT",
"value": "30 sec",
}
```
## Récupération de métriques pour un bot
Utilisez les `ListUtteranceMetrics` opérations`ListSessionMetrics`, `ListIntentMetrics``ListIntentStageMetrics`, et pour récupérer les métriques récapitulatives des *sessions*, *des intentions*, des *étapes d'intention* et des *énoncés*.
Pour ces opérations, renseignez les champs obligatoires suivants :
+ Entrez un `startTime` et `endTime` pour définir la plage de temps pour laquelle vous souhaitez récupérer les résultats.
+ Spécifiez les mesures que vous souhaitez calculer`metrics`, une liste de [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), ou d'[AnalyticsUtteranceMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceMetric.html)objets. Dans chaque objet, utilisez le `name` champ pour spécifier la métrique à calculer, le `statistic` champ pour indiquer s'il faut calculer le `Sum``Average`, ou le `Max` nombre, et le `order` champ pour indiquer s'il faut trier les résultats par `Descending` ordre `Ascending` ou par ordre.
**Note**
Les `binBy` objets `metrics` et contiennent tous deux un `order` champ. Vous ne pouvez spécifier le tri `order` que pour l'un des deux objets.
Les autres champs de la demande sont facultatifs. Vous pouvez filtrer et organiser les résultats de différentes manières :
+ **Filtrage des résultats** : utilisez le `filters` champ pour filtrer les résultats. Pour plus d’informations, consultez [Filtrer les résultats](#analytics-api-filters).
+ **Regroupement des résultats par catégorie** : spécifiez le `groupBy` champ, une liste contenant un seul [AnalyticsSessionResult[AnalyticsIntentResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentResult.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionResult.html), [AnalyticsIntentStageResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageResult.html), ou un [AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html)objet. Dans l'objet, spécifiez le `name` champ contenant la catégorie selon laquelle vous souhaitez regrouper les résultats.
Si vous spécifiez un `groupBy` champ dans la demande, l'`results`objet de la réponse contient `groupByKeys` une liste de [AnalyticsSessionGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionGroupByKey.html), [AnalyticsIntentGroupByKey[AnalyticsIntentStageGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageGroupByKey.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentGroupByKey.html), ou [AnalyticsUtteranceGroupByKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceGroupByKey.html)objets, chacun avec `name` celui que vous avez spécifié dans la demande et un membre de cette catégorie dans le `value` champ.
+ **Classification des résultats par heure** : spécifiez le `binBy` champ, une liste contenant un seul [AnalyticsBinBySpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinBySpecification.html)objet. Dans l'objet, spécifiez le `name` champ contenant `ConversationStartTime` pour classer les résultats en fonction de la date à laquelle la conversation a commencé ou `UtteranceTimestamp` pour classer les résultats en fonction de la date à laquelle l'énoncé a eu lieu. Spécifiez l'intervalle de temps selon lequel vous souhaitez regrouper les résultats dans le `interval` champ, et indiquez si vous souhaitez trier `Ascending` ou l'`Descending`ordre chronologique dans le `order` champ.
Si vous spécifiez un `binBy` champ dans la demande, l'`results`objet de la réponse contient `binKeys` une liste d'[AnalyticsBinKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinKey.html)objets, chacun avec `name` celui que vous avez spécifié dans la demande et l'intervalle de temps qui définit ce casier dans le `value` champ.
**Note**
Les `binBy` objets `metrics` et contiennent tous deux un `order` champ. Vous ne pouvez spécifier le tri `order` que pour l'un des deux objets.
Utilisez les champs suivants pour gérer l'affichage de la réponse :
+ Spécifiez un nombre compris entre 1 et 1 000 dans le `maxResults` champ pour limiter le nombre de résultats à renvoyer dans une seule réponse.
+ Si le nombre de résultats est supérieur au nombre que vous spécifiez dans le `maxResults` champ, la réponse contient un`nextToken`. Effectuez à nouveau la demande, mais utilisez cette valeur dans le `nextToken` champ pour renvoyer le prochain lot de résultats.
Si vous en utilisez`ListUtteranceMetrics`, vous pouvez spécifier les attributs à renvoyer dans le `attributes` champ. Ce champ correspond à une liste contenant un seul [AnalyticsUtteranceAttribute](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceAttribute.html)objet. Spécifiez `LastUsedIntent` dans le `name` champ pour renvoyer l'intention utilisée par Amazon Lex V2 au moment de l'énoncé.
Dans la réponse, le `results` champ correspond à une liste de [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), ou d'[AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html)objets. Chaque objet contient un `metrics` champ qui renvoie la valeur d'une statistique récapitulative pour une métrique que vous avez demandée, en plus des groupes ou groupes créés à partir des méthodes que vous avez spécifiées.
## Récupération des métadonnées pour les sessions et les énoncés dans un bot
Utilisez les [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html)opérations [ListSessionAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionAnalyticsData.html)et pour récupérer les métadonnées relatives à des sessions et à des énoncés individuels.
Renseignez les `endTime` champs obligatoires `startTime` et pour définir la plage de temps pour laquelle vous souhaitez récupérer les résultats.
Les autres champs de la demande sont facultatifs. Pour filtrer et trier les résultats :
+ **Filtrage des résultats** : utilisez le `filters` champ pour filtrer les résultats. Pour plus d’informations, consultez [Filtrer les résultats](#analytics-api-filters).
+ **Tri des résultats** : triez les résultats avec le `sortBy` champ contenant un [UtteranceDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceDataSortBy.html)objet [SessionDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionDataSortBy.html)ou. Spécifiez la valeur selon laquelle vous souhaitez trier dans le `name` champ et indiquez s'il faut trier `Ascending` ou `Descending` trier dans le `order` champ.
Utilisez les champs suivants pour gérer l'affichage de la réponse :
+ Spécifiez un nombre compris entre 1 et 1 000 dans le `maxResults` champ pour limiter le nombre de résultats à renvoyer dans une seule réponse.
+ Si le nombre de résultats est supérieur au nombre que vous spécifiez dans le `maxResults` champ, la réponse contient un`nextToken`. Effectuez à nouveau la demande, mais utilisez cette valeur dans le `nextToken` champ pour renvoyer le prochain lot de résultats.
Dans la réponse, le `utterances` champ `sessions` ou correspond à une liste d'[SessionSpecification[UtteranceSpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceSpecification.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionSpecification.html)objets. Chaque objet contient les métadonnées d'une seule session ou d'un seul énoncé.
## Récupération des données d'analyse des trajectoires d'intention
Utilisez cette [ListIntentPaths](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentPaths.html)opération pour récupérer des statistiques relatives à un ordre d'intention suivi par les clients lors d'une conversation avec un bot.
Pour cette opération, renseignez les champs obligatoires suivants :
+ Entrez un `startTime` et `endTime` pour définir la plage de temps pour laquelle vous souhaitez récupérer les résultats.
+ Indiquez un `intentPath` pour définir l'ordre d'intention pour lequel vous souhaitez récupérer les métriques. Séparez les intentions du tracé par une barre oblique. Par exemple, renseignez le `intentPath` champ avec **/BookCar/BookHotel** pour voir le nombre de fois où les utilisateurs ont invoqué le `BookCar` et `BookHotel` les intentions dans cet ordre.
Utilisez le `filters` champ facultatif pour filtrer les résultats. Pour en savoir plus, consultez [Filtrer les résultats](#analytics-api-filters).
## Afficher les statistiques relatives aux énoncés issus de conversations avec Lex V2
Vous pouvez utiliser les statistiques relatives aux énoncés pour déterminer les énoncés que vos utilisateurs envoient à votre bot. Vous pouvez voir à la fois les énoncés qu'Amazon Lex V2 détecte avec succès et ceux qu'il ne détecte pas. Vous pouvez utiliser ces informations pour optimiser votre bot.
Par exemple, si vous constatez que vos utilisateurs envoient un énoncé indiquant qu'Amazon Lex V2 est absent, vous pouvez ajouter cet énoncé à une intention. La version préliminaire de l'intention est mise à jour avec le nouvel énoncé et vous pouvez la tester avant de la déployer sur votre bot.
Un énoncé est détecté lorsqu'Amazon Lex V2 le reconnaît comme une tentative d'invoquer une intention configurée pour un bot. Un énoncé est oublié lorsqu'Amazon Lex V2 ne le reconnaît pas et l'invoque à sa place. `AMAZON.FallbackIntent`
Les statistiques relatives aux énoncés peuvent être consultées à l'aide de l'`ListUtteranceMetrics`API et de l'`ListAggregatedUtterance`API.
Les statistiques d'énoncé ne sont pas générées à l'aide de l'`ListUtteranceMetrics`API dans les conditions suivantes :
+ Le paramètre Child Online Privacy Protection Act était défini sur **Oui** lorsque le bot a été créé avec la console, ou le `childDirected` champ était défini sur true lorsque le bot a été créé avec l'`CreateBot`opération.
L'`ListUtteranceMetrics`API fournit des fonctionnalités supplémentaires, notamment :
+ Plus d'informations sont disponibles, telles que l'intention mappée pour les énoncés détectés.
+ Plus de capacité de filtrage (y compris le canal et le mode).
+ Plage de dates de conservation plus longue (30 jours).
+ Vous pouvez utiliser l'API même si vous avez choisi de ne pas enregistrer les données. La fonctionnalité de console pour les énoncés manqués ou détectés s'appuiera sur `ListUtteranceMetrics` l'API.
Les statistiques d'énoncé ne sont pas générées à l'aide de l'`ListAggregatedUtterance`API dans les conditions suivantes :
+ Le paramètre Child Online Privacy Protection Act était défini sur **Oui** lorsque le bot a été créé avec la console, ou le `childDirected` champ était défini sur true lorsque le bot a été créé avec l'`CreateBot`opération.
+ Vous utilisez l'obfuscation des emplacements avec un ou plusieurs emplacements.
+ Vous avez choisi de ne pas participer à l'amélioration d'Amazon Lex.
L'`ListAggregatedUtterance`API fournit des fonctionnalités telles que :
+ Informations moins détaillées disponibles (aucune intention cartographiée pour les énoncés).
+ Capacité de filtrage limitée (sans compter le canal et le mode).
+ Période de conservation courte (15 jours).
À l'aide des statistiques relatives aux énoncés, vous pouvez savoir si un énoncé spécifique a été détecté ou oublié, ainsi que la dernière fois que cet énoncé a été utilisé lors d'une interaction avec un bot.
Amazon Lex V2 stocke les énoncés en continu pendant que les utilisateurs interagissent avec votre bot. Vous pouvez consulter les statistiques à l'aide de la console ou de l'`ListAggregatedUtterances`opération. Il a une durée de conservation des données de 15 jours et n'est pas disponible si l'utilisateur a choisi de ne pas le stocker. Vous pouvez supprimer des énoncés à l'aide de cette `DeleteUtterances` opération ou en refusant le stockage des données. Tous les énoncés sont supprimés si vous fermez votre compte AWS. Les énoncés enregistrés sont chiffrés à l'aide d'une clé gérée par le serveur.
Lorsque vous supprimez une version de bot, les statistiques d'énoncé sont disponibles pour cette version pendant 30 jours au maximum et pendant 15 jours en `ListUtteranceMetrics` cas d'utilisation. `ListAggregatedUtterances` Vous ne pouvez pas consulter les statistiques relatives à la version supprimée dans la console Amazon Lex V2. Pour consulter les statistiques des versions supprimées, vous pouvez utiliser à la fois les `ListUtteranceMetrics` opérations `ListAggregatedUtterances` et les opérations.
Avec les `ListUtteranceMetrics` API `ListAggregatedUtterances` et, les énoncés sont agrégés en fonction du texte de l'énoncé. Par exemple, tous les cas où le client a utilisé l'expression « Je veux commander une pizza » sont regroupés sur la même ligne dans une réponse. Lorsque vous utilisez l'[RecognizeUtterance](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeUtterance.html)opération, le texte utilisé est le transcrit d'entrée.
Pour utiliser les `ListUtteranceMetrics` API `ListAggregatedUtterances` et, appliquez la politique suivante à un rôle.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ListAggregatedUtterancesPolicy",
"Effect": "Allow",
"Action": "lex:ListAggregatedUtterances",
"Resource": "*"
}
]
}
```
------