View a markdown version of this page

Utilisation des API pour les analyses - Amazon Lex
Filtrer les résultatsRécupération de métriques pour un botRécupération des métadonnées pour les sessions et les énoncés dans un botRécupération des données d'analyse du chemin d'intentionAffichage des statistiques relatives aux énoncés dans les conversations Lex V2

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 et ListUtteranceAnalyticsData, votre rôle IAM doit disposer des autorisations nécessaires pour effectuer l'ListAggregatedUtterancesopération, ce qui donne accès aux analyses liées aux énoncés. Consultez Affichage des statistiques relatives aux énoncés dans les conversations Lex V2 les détails et la politique IAM à appliquer au rôle IAM.

Filtrer les résultats

Les requêtes de l'API Analytics nécessitent que vous indiquiez le startTime etendTime. 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

filtersest un champ facultatif dans les requêtes de l'API Analytics. Il correspond à une liste de AnalyticsSessionFilter, AnalyticsIntentFilter AnalyticsIntentStageFilter, ou d'AnalyticsUtteranceFilterobjets. Dans chaque objet, utilisez les champs pour créer une expression à utiliser pour 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érationsListSessionMetrics, ListIntentMetricsListIntentStageMetrics, et pour récupérer des mesures récapitulatives pour les sessions, les intentions, les étapes d'intention et les é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 calculermetrics, une liste de AnalyticsSessionMetric, AnalyticsIntentMetric AnalyticsIntentStageMetric, ou d'AnalyticsUtteranceMetricobjets. Dans chaque objet, utilisez le name champ pour spécifier la métrique à calculer, le statistic champ pour spécifier s'il faut calculer le SumAverage, ou le Max nombre, et le order champ pour spécifier 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 la manière suivante :

  • Filtrage des résultats — Utilisez le filters champ pour filtrer les résultats. Pour plus d’informations, consultez Filtrer les résultats.

  • Regroupement des résultats par catégorie  : spécifiez le groupBy champ, une liste contenant un seul AnalyticsSessionResult AnalyticsIntentResult AnalyticsIntentStageResult, ou un AnalyticsUtteranceResult 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'resultsobjet de la réponse contient groupByKeys une liste de AnalyticsSessionGroupByKey, AnalyticsIntentGroupByKey AnalyticsIntentStageGroupByKey, ou d'AnalyticsUtteranceGroupByKeyobjets, chacun avec name celui que vous avez spécifié dans la demande et un membre de cette catégorie dans le value champ.

  • Répartir les résultats par heure — Spécifiez le binBy champ, une liste contenant un seul AnalyticsBinBySpecification objet. Dans l'objet, spécifiez le name champ contenant ConversationStartTime pour classer les résultats selon le début de la conversation ou UtteranceTimestamp pour classer les résultats selon la date à laquelle l'énoncé a eu lieu. Spécifiez l'intervalle de temps selon lequel vous souhaitez classer les résultats dans le interval champ, et si vous souhaitez trier Ascending ou par Descending ordre chronologique dans le order champ.

    Si vous spécifiez un binBy champ dans la demande, l'resultsobjet de la réponse contient binKeys une liste d'AnalyticsBinKeyobjets, chacun avec name celui que vous avez spécifié dans la demande et l'intervalle de temps qui définit ce groupe 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 avez indiqué dans le maxResults champ, la réponse contient unnextToken. Effectuez à nouveau la demande, mais utilisez cette valeur dans le nextToken champ pour renvoyer le prochain lot de résultats.

Si vous utilisezListUtteranceMetrics, vous pouvez spécifier les attributs à renvoyer dans le attributes champ. Ce champ correspond à une liste contenant un seul AnalyticsUtteranceAttribute 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 AnalyticsIntentResult AnalyticsIntentStageResult, ou d'AnalyticsUtteranceResultobjets. 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 bacs ou des groupes créés à l'aide 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 opérations ListSessionAnalyticsData et pour récupérer les métadonnées relatives aux sessions et aux énoncés individuels.

Renseignez les endTime champs obligatoires startTime et pour définir une 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.

  • Tri des résultats — Triez les résultats à l'aide du sortBy champ qui contient un UtteranceDataSortBy objet SessionDataSortBy ou. Spécifiez la valeur selon laquelle vous souhaitez effectuer le tri dans le name champ et si vous souhaitez effectuer un tri Ascending ou un Descending ordre 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 avez indiqué dans le maxResults champ, la réponse contient unnextToken. Renouvelez 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'UtteranceSpecificationobjets SessionSpecification ou. Chaque objet contient des métadonnées pour une seule session ou un seul énoncé.

Récupération des données d'analyse du chemin d'intention

Utilisez cette ListIntentPaths opération pour récupérer des statistiques relatives à un ordre d'intentions adopté 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.

  • Fournissez un intentPath pour définir l'ordre des intentions pour lequel vous souhaitez récupérer les métriques. Séparez les intentions du chemin par une barre oblique. Par exemple, renseignez le intentPath champ /BookCar/BookHotel pour voir les détails sur le nombre de fois que les utilisateurs ont invoqué les BookHotel intentions BookCar et les intentions dans cet ordre.

Utilisez le filters champ facultatif pour filtrer les résultats. Pour en savoir plus, consultez Filtrer les résultats.

Affichage des statistiques relatives aux énoncés dans les conversations 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 détectés avec succès par Amazon Lex V2 et ceux qu'il ne détecte pas. Vous pouvez utiliser ces informations pour ajuster 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 le tester avant de le déployer sur votre bot.

Un énoncé est détecté lorsqu'Amazon Lex V2 reconnaît qu'il s'agit d'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 à la place. AMAZON.FallbackIntent

Les statistiques relatives aux énoncés peuvent être consultées à l'aide de l'ListUtteranceMetricsAPI et de l'ListAggregatedUtteranceAPI.

Les statistiques d'énonciation ne sont pas générées à l'aide de l'ListUtteranceMetricsAPI dans les conditions suivantes :

  • Le paramètre Child Online Privacy Protection Act était défini sur Oui lorsque le bot a été créé à l'aide de la console, ou le childDirected champ était défini sur true lorsque le bot a été créé avec l'CreateBotopération.

L'ListUtteranceMetricsAPI fournit des fonctionnalités supplémentaires, notamment :

  • Plus d'informations sont disponibles, telles que l'intention cartographié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 désactivé le stockage des données. La fonctionnalité de la console pour les énoncés manqués et détectés s'appuiera sur ListUtteranceMetrics l'API.

Les statistiques d'énonciation ne sont pas générées à l'aide de l'ListAggregatedUtteranceAPI dans les conditions suivantes :

  • Le paramètre Child Online Privacy Protection Act était défini sur Oui lorsque le bot a été créé à l'aide de la console, ou le childDirected champ était défini sur true lorsque le bot a été créé avec l'CreateBotopé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'ListAggregatedUtteranceAPI 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 (canal et mode non compris).

  • Plage de dates de conservation courte (15 jours).

À l'aide des statistiques d'énoncé, vous pouvez voir 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 robot.

Amazon Lex V2 enregistre les énoncés en continu pendant que les utilisateurs interagissent avec votre bot. Vous pouvez interroger les statistiques à l'aide de la console ou de l'ListAggregatedUtterancesopé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 désactivant 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 la version d'un bot, les statistiques d'énonciation sont disponibles pour cette version pendant 30 jours maximum avec ListUtteranceMetrics et 15 jours d'utilisation. ListAggregatedUtterances Les statistiques relatives à la version supprimée ne s'affichent pas 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.

Avec les ListUtteranceMetrics API ListAggregatedUtterances et les API, les énoncés sont agrégés par le texte de l'énoncé. Par exemple, tous les cas où le client a utilisé la phrase « Je veux commander une pizza » sont regroupés sur la même ligne dans une réponse. Lorsque vous utilisez cette RecognizeUtterance opération, le texte utilisé est la transcription 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": "*"
        }
    ]
}