Usar APIs para análise - Guia do desenvolvedor
Filtrar resultadosRecuperar métricas para um botRecuperar metadados para sessões e enunciados em um botRecuperação dos dados de analytics do caminho de intençãoVisualização de estatísticas de enunciados de conversas do Lex V2

Usar 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 e o ListUtteranceAnalyticsData, seu perfil do IAM deve ter permissões para realizar a operação ListAggregatedUtterances, que fornece acesso às análises relacionadas ao enunciado. Consulte Visualização de estatísticas de enunciados de conversas do Lex V2 para obter detalhes sobre a política do IAM a ser aplicada ao perfil do IAM.

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 objetos AnalyticsSessionFilter, AnalyticsIntentFilter, AnalyticsIntentStageFilter ou AnalyticsUtteranceFilter. 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 em metrics, uma lista de objetos AnalyticsSessionMetric, AnalyticsIntentMetric, AnalyticsIntentStageMetric ou AnalyticsUtteranceMetric. 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 para obter mais detalhes.

  • Agrupamento de resultados por categoria - Especifique o campo groupBy, uma lista que contém um único objeto AnalyticsSessionResult, AnalyticsIntentResult, AnalyticsIntentStageResult ou AnalyticsUtteranceResult. 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 objeto results na resposta contem groupByKeys, uma lista de objetos AnalyticsSessionGroupByKey, AnalyticsIntentGroupByKey, AnalyticsIntentStageGroupByKey ou AnalyticsUtteranceGroupByKey, cada um com o name que você especificou na solicitação e um membro dessa categoria no campo value.

  • Agrupamento dos resultados por hora – Especifique o campo binBy, uma lista que contém um único objeto AnalyticsBinBySpecification. 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 campo binBy na solicitação, o objeto results na resposta contém binKeys, uma lista de objetos AnalyticsBinKey, cada um com o name que você especificou na solicitação e o intervalo de tempo que define esse compartimento no campo value.

    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 que contém um único objeto AnalyticsUtteranceAttribute. Especifique LastUsedIntent no campo name para retornar a intenção que o Amazon Lex V2 está usando no momento do enunciado.

Na resposta, o campo results é mapeado para uma lista de objetos AnalyticsSessionResult, AnalyticsIntentResult, AnalyticsIntentStageResult ou AnalyticsUtteranceResult. 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 operações ListSessionAnalyticsData e ListUtteranceAnalyticsData para recuperar metadados sobre sessões e enunciados 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 para obter mais detalhes.

  • Classificar resultados – Classifique os resultados com o campo sortBy, que contém um objeto SessionDataSortBy ou UtteranceDataSortBy. 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 campo sessions e utterances ou mapeia para uma lista de objetos SessionSpecification ou UtteranceSpecification. 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 operação ListIntentPaths para recuperar métricas sobre uma ordem de intenções que os clientes realizam na conversa 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.

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 os enunciados serão excluídos 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 as APIs ListAggregatedUtterances e ListUtteranceMetrics, 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 operação RecognizeUtterance, o texto usado é a transcrição de entrada.

Para usar as APIs ListAggregatedUtterances e ListUtteranceMetrics, aplique a política a seguir a uma função.

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