As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Usando APIs para análise
Esta seção descreve as operações de API que você usa para recuperar análises de um bot.
**nota**
Para usar o [ListUtteranceMetrics](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceMetrics.html)e [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html), sua função do IAM deve ter permissões para realizar a [ListAggregatedUtterances](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListAggregatedUtterances.html)operação, que fornece acesso a análises relacionadas ao enunciado. Consulte [Visualização de estatísticas de enunciados de conversas do Lex V2](#monitoring-utterances) para obter detalhes sobre a política do IAM a ser aplicada ao perfil do IAM.
+ As seguintes operações de API recuperam métricas resumidas de um 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)
+ As seguintes operações de API recuperam uma lista de metadados para sessões e enunciados:
+ [ListSessionAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionAnalyticsData.html)
+ [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html)
+ A [ListIntentPaths](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentPaths.html)operação recupera métricas sobre uma ordem de intenções que os clientes realizam nas conversas com um bot.
## Filtrar resultados
As solicitações de API de análise exigem que você especifique `startTime` e `endTime`. A API retorna sessões, intenções, estágios de intenção ou enunciados que começaram *depois* do `startTime` e que terminaram *antes* do `endTime`.
`filters` é um campo opcional nas solicitações da API de análise. Ele mapeia para uma lista de [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), ou [AnalyticsUtteranceFilter](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceFilter.html)objetos. Em cada objeto, use os campos para criar uma expressão pela qual filtrar. Por exemplo, se você adicionar o filtro a seguir à lista, o bot pesquisará conversas com mais de 30 segundos.
```
{
"name": "Duration",
"operator": "GT",
"value": "30 sec",
}
```
## Recuperar métricas para um bot
Use as operações `ListSessionMetrics`, `ListIntentMetrics`, `ListIntentStageMetrics` e `ListUtteranceMetrics` e para recuperar métricas resumidas de *sessões*, *intenções*, *estágios de intenção* e *enunciados*.
Para essas operações, preencha os seguintes campos obrigatórios:
+ Forneça um `startTime` e `endTime` para definir um intervalo de tempo que você deseja usar para recuperar os resultados.
+ Especifique as métricas que você deseja calcular`metrics`, uma lista de [AnalyticsSessionMetric[AnalyticsIntentMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentMetric.html)](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsSessionMetric.html), [AnalyticsIntentStageMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsIntentStageMetric.html), ou [AnalyticsUtteranceMetric](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceMetric.html)objetos. Em cada objeto, use o campo `name` para especificar a métrica para calcular o campo `statistic` para especificar se deseja calcular o número `Sum`, `Average` ou `Max`, e o campo `order` para especificar se os resultados devem ser classificados em ordem `Ascending` ou `Descending`.
**nota**
Tanto o objeto `metrics` quanto o `binBy` contêm um campo `order`. Você pode especificar a classificação `order` em somente um dos dois objetos.
Os campos restantes na solicitação são opcionais. É possível filtrar e organizar os resultados das seguintes maneiras:
+ **Filtrar resultados** – Use o campo `filters` para filtrar os resultados. Consulte [Filtrar resultados](#analytics-api-filters) para obter mais detalhes.
+ **Agrupamento de resultados por categoria** — Especifique o `groupBy` campo, uma lista contendo um único [AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html)objeto [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. No objeto, especifique o campo `name` com a categoria pela qual você deseja agrupar os resultados.
Se você especificar um `groupBy` campo na solicitação, o `results` objeto na resposta `groupByKeys` conterá uma lista 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)objetos, cada um com o `name` que você especificou na solicitação e um membro dessa categoria no `value` campo.
+ **Agrupando os resultados por hora** — Especifique o `binBy` campo, uma lista contendo um único [AnalyticsBinBySpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinBySpecification.html)objeto. No objeto, especifique o campo `name` com `ConversationStartTime` para agrupar os resultados de acordo com o início da conversa ou `UtteranceTimestamp` para agrupar os resultados com base no momento em que o enunciado ocorreu. Especifique o intervalo de tempo pelo qual você deseja agrupar os resultados no campo `interval` e se deseja classificar em ordem de tempo `Ascending` ou `Descending` ou no campo `order`.
Se você especificar um `binBy` campo na solicitação, o `results` objeto na resposta `binKeys` conterá uma lista de [AnalyticsBinKey](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsBinKey.html)objetos, cada um com o `name` que você especificou na solicitação e o intervalo de tempo que define esse compartimento no `value` campo.
**nota**
Tanto o objeto `metrics` quanto o `binBy` contêm um campo `order`. Você pode especificar a classificação `order` em somente um dos dois objetos.
Use os campos a seguir para lidar com a exibição da resposta:
+ Especifique um número entre 1 e 1.000 no campo `maxResults` para limitar o número de resultados a serem retornados em uma única resposta.
+ Se o número de resultados for maior que o número especificado no campo `maxResults`, a resposta conterá um `nextToken`. Faça a solicitação novamente, mas use esse valor no campo `nextToken` para retornar o próximo lote de resultados.
Se você estiver usando `ListUtteranceMetrics`, você pode especificar atributos a serem retornados no campo `attributes`. Esse campo é mapeado para uma lista contendo um único [AnalyticsUtteranceAttribute](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceAttribute.html)objeto. Especifique `LastUsedIntent` no campo `name` para retornar a intenção que o Amazon Lex V2 está usando no momento do enunciado.
Na resposta, o `results` campo é mapeado para uma lista de [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 [AnalyticsUtteranceResult](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_AnalyticsUtteranceResult.html)objetos. Cada objeto contém um campo `metrics` que retorna o valor de uma estatística resumida para uma métrica que você solicitou, além de quaisquer compartimentos ou grupos criados a partir dos métodos que você especificou.
## Recuperar metadados para sessões e enunciados em um bot
Use as [ListUtteranceAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListUtteranceAnalyticsData.html)operações [ListSessionAnalyticsData](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListSessionAnalyticsData.html)and para recuperar metadados sobre sessões e declarações individuais.
Preencha os campos `startTime` e `endTime` obrigatórios para definir um intervalo de tempo para o qual você deseja recuperar os resultados.
Os campos restantes na solicitação são opcionais. Para filtrar e classificar os resultados:
+ **Filtrar resultados** – Use o campo `filters` para filtrar os resultados. Consulte [Filtrar resultados](#analytics-api-filters) para obter mais detalhes.
+ **Classificando resultados** — Classifique os resultados com o `sortBy` campo, que contém um [UtteranceDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceDataSortBy.html)objeto [SessionDataSortBy](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionDataSortBy.html)ou. Especifique o valor que você deseja usar para classificar no campo `name` e se deseja classificar em ordem `Ascending` ou `Descending` no campo `order`.
Use os campos a seguir para lidar com a exibição da resposta:
+ Especifique um número entre 1 e 1.000 no campo `maxResults` para limitar o número de resultados a serem retornados em uma única resposta.
+ Se o número de resultados for maior que o número especificado no campo `maxResults`, a resposta conterá um `nextToken`. Faça a solicitação novamente, mas use esse valor no campo `nextToken` para retornar o próximo lote de resultados.
Na resposta, o `utterances` campo `sessions` ou é mapeado para uma lista de [SessionSpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_SessionSpecification.html)ou [UtteranceSpecification](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_UtteranceSpecification.html)objetos. Cada objeto contém metadados para uma única sessão ou enunciado.
## Recuperação dos dados de analytics do caminho de intenção
Use a [ListIntentPaths](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_ListIntentPaths.html)operação para recuperar métricas sobre uma ordem de intenções que os clientes realizam ao conversar com um bot.
Para essa operação, preencha os seguintes campos obrigatórios:
+ Forneça um `startTime` e `endTime` para definir um intervalo de tempo que você deseja usar para recuperar os resultados.
+ Forneça um `intentPath` para definir uma ordem de intenções para as quais você deseja recuperar métricas. Separe as intenções no caminho com uma barra para frente. Por exemplo, preencha o campo `intentPath` com **/BookCar/BookHotel** para ver detalhes sobre quantas vezes os usuários invocaram as intenções `BookCar` e `BookHotel` nessa ordem.
Use o campo `filters` opcional para filtrar os resultados. Consulte mais detalhes em [Filtrar resultados](#analytics-api-filters).
## Visualização de estatísticas de enunciados de conversas do Lex V2
Você pode usar estatísticas de enunciados para determinar os enunciados que seus usuários estão enviando para o seu bot. Você pode ver tanto os enunciados que o Amazon Lex V2 detecta com sucesso quanto os enunciados que ele não detecta. É possível utilizar essas informações para ajustar seu bot.
Por exemplo, se você descobrir que seus usuários estão enviando um enunciado que está faltando no Amazon Lex V2, você pode adicionar o enunciado a uma intenção. A versão Rascunho da intenção é atualizada com o novo enunciado e você pode testá-la antes de implantá-la no seu bot.
O enunciado é detectado quando o Amazon Lex V2 reconhece o enunciado como uma tentativa de invocar uma intenção configurada para um bot. Um enunciado é perdido quando o Amazon Lex V2 não o reconhece e, em vez disso, invoca o `AMAZON.FallbackIntent`.
As estatísticas do enunciado podem ser visualizadas usando a API `ListUtteranceMetrics` e a API `ListAggregatedUtterance`.
As estatísticas de enunciado não são geradas usando a API `ListUtteranceMetrics` nas seguintes condições:
+ A configuração da Lei de Proteção à Privacidade Online Infantil foi definida como **Sim** quando o bot foi criado com o console, ou o campo `childDirected` foi definido como verdadeiro quando o bot foi criado com a operação `CreateBot`.
A API `ListUtteranceMetrics` fornece recursos adicionais, incluindo:
+ Mais informações disponíveis, como intenção mapeada para enunciados detectados.
+ Mais capacidade de filtragem (incluindo canal e modo).
+ Intervalo de datas de retenção mais longo (30 dias).
+ Você pode usar a API mesmo se tiver optado por não armazenar dados. A funcionalidade do console para enunciados perdidos e detectados dependerá da API `ListUtteranceMetrics`.
As estatísticas de enunciado não são geradas usando a API `ListAggregatedUtterance` nas seguintes condições:
+ A configuração da Lei de Proteção à Privacidade Online Infantil foi definida como **Sim** quando o bot foi criado com o console, ou o campo `childDirected` foi definido como verdadeiro quando o bot foi criado com a operação `CreateBot`.
+ Você está usando a ofuscação de slots com um ou mais slots.
+ Você optou por não participar da melhoria do Amazon Lex.
A API `ListAggregatedUtterance` fornece atributos adicionais, incluindo:
+ Menos informações disponíveis (nenhuma intenção mapeada para enunciados detectados).
+ Capacidade limitada de filtragem (incluindo canal e modo).
+ Intervalo de datas de retenção curto (15 dias).
Usando as estatísticas de enunciado, você pode ver se um enunciado específico foi detectado ou não detectado, juntamente com a última vez em que o enunciado foi usado em uma interação de bot.
O Amazon Lex V2 armazena enunciados continuamente enquanto os usuários interagem com seu bot. Você pode consultar as estatísticas usando o console ou a operação `ListAggregatedUtterances`. Ele tem uma retenção de dados de 15 dias e não está disponível se o usuário tiver optado por não armazenar dados. Você pode excluir enunciados usando a operação `DeleteUtterances` ou desativando o armazenamento de dados. Todas as declarações serão excluídas se você fechar sua conta da AWS. Os enunciados armazenados são criptografados com uma chave gerenciada pelo servidor.
Quando você exclui uma versão do bot, as estatísticas de enunciado ficam disponíveis para a versão por até 30 dias com `ListUtteranceMetrics` e 15 dias usando `ListAggregatedUtterances`. Você não pode ver as estatísticas da versão excluída no console do Amazon Lex V2. Para ver as estatísticas de versões excluídas, você pode usar as operações `ListAggregatedUtterances` e `ListUtteranceMetrics`.
Com o `ListAggregatedUtterances` e `ListUtteranceMetrics` APIs, os enunciados são agregados pelo texto do enunciado. Por exemplo, todas as instâncias em que o cliente usou a frase “Quero pedir uma pizza” são agregadas na mesma linha em uma resposta. Quando você usa a [RecognizeUtterance](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeUtterance.html)operação, o texto usado é a transcrição de entrada.
Para usar o `ListAggregatedUtterances` e `ListUtteranceMetrics` APIs, aplique a política a seguir a uma função.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ListAggregatedUtterancesPolicy",
"Effect": "Allow",
"Action": "lex:ListAggregatedUtterances",
"Resource": "*"
}
]
}
```
------