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

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 ListUtteranceMetricse ListUtteranceAnalyticsData, sua função do IAM deve ter permissões para realizar a ListAggregatedUtterancesoperação, que fornece acesso a 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 AnalyticsSessionFilter, AnalyticsIntentFilter, AnalyticsIntentStageFilter, ou AnalyticsUtteranceFilterobjetos. 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 calcularmetrics, uma lista de AnalyticsSessionMetricAnalyticsIntentMetric, AnalyticsIntentStageMetric, ou AnalyticsUtteranceMetricobjetos. 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 groupBy campo, uma lista contendo um único AnalyticsUtteranceResultobjeto AnalyticsSessionResultAnalyticsIntentResult, AnalyticsIntentStageResult, 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,, AnalyticsIntentGroupByKeyAnalyticsIntentStageGroupByKey, ou AnalyticsUtteranceGroupByKeyobjetos, 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 AnalyticsBinBySpecificationobjeto. 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 AnalyticsBinKeyobjetos, 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 AnalyticsUtteranceAttributeobjeto. 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 AnalyticsSessionResultAnalyticsIntentResult, AnalyticsIntentStageResult, ou AnalyticsUtteranceResultobjetos. 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 ListUtteranceAnalyticsDataoperações ListSessionAnalyticsDataand 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 para obter mais detalhes.

  • Classificando resultados — Classifique os resultados com o sortBy campo, que contém um UtteranceDataSortByobjeto SessionDataSortByou. 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 SessionSpecificationou UtteranceSpecificationobjetos. Cada objeto contém metadados para uma única sessão ou enunciado.

Recuperando dados de análise do caminho de intenção

Use a ListIntentPathsoperaçã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.

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 AWS conta. 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.

Tanto 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 RecognizeUtteranceoperaçã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": "*"
        }
    ]
}