Usar os resultados da consulta de análise do Amazon Pinpoint - Amazon Pinpoint
Estrutura JSONObjetos e campos JSON

Aviso de fim do suporte: em 30 de outubro de 2026, AWS encerrará o suporte para o Amazon Pinpoint. Depois de 30 de outubro de 2026, você não poderá mais acessar o console do Amazon Pinpoint ou os recursos do Amazon Pinpoint (endpoints, segmentos, campanhas, viagens e análises). Para obter mais informações, consulte Fim do suporte do Amazon Pinpoint. Observação: APIs relacionados a SMS, voz, push móvel, OTP e validação de número de telefone não são afetados por essa alteração e são compatíveis com o AWS End User Messaging.

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á.

Usar os resultados da consulta de análise do Amazon Pinpoint

Quando você usa o Amazon Pinpoint Analytics APIs para consultar dados analíticos, o Amazon Pinpoint retorna os resultados em uma resposta JSON. Para métricas de aplicativos, métricas de campanha e métricas de engajamento de jornada, os dados na resposta aderem a um esquema JSON padrão para relatórios de dados analíticos do Amazon Pinpoint.

Isso significa que você pode usar a linguagem de programação ou a ferramenta de sua escolha para implementar uma solução personalizada que consulta os dados de uma ou mais métricas, captura os resultados de cada consulta e, depois, grava os resultados em uma tabela, um objeto ou outro local. Em seguida, você pode trabalhar com os resultados da consulta nesse local usando outro serviço ou aplicativo.

Por exemplo, é possível:

  • Crie um painel personalizado que consulta regularmente um conjunto de métricas e exiba os resultados usando sua estrutura de visualização de dados preferida.

  • Crie um relatório que rastreia as taxas de engajamento consultando as métricas apropriadas e exibindo os resultados em um gráfico ou outro tipo de relatório criado por você.

  • Analise e grave dados analíticos em um formato de armazenamento específico e, em seguida, migre os resultados para uma solução de armazenamento de longo prazo.

Observe que o Amazon Pinpoint Analytics APIs não foi projetado para criar ou armazenar objetos persistentes que você possa ler ou usar posteriormente em um projeto do Amazon Pinpoint ou em sua conta do Amazon Pinpoint. Em vez disso, APIs eles são projetados para ajudá-lo a recuperar dados analíticos e transferi-los para outros serviços e aplicativos para análise, armazenamento ou geração de relatórios adicionais. Elas fazem isso em parte usando a mesma estrutura de resposta JSON e o mesmo esquema para todos os dados analíticos que você pode consultar programaticamente para métricas de aplicativos, métricas de campanha e métricas de engajamento de jornada.

Este tópico explica a estrutura, os objetos e os campos em uma resposta JSON a uma consulta para uma métrica de aplicativo, métrica de campanha ou métrica de engajamento de jornada. Para obter informações sobre os campos em uma resposta JSON a uma consulta para uma métrica de execução de jornada ou métrica de execução de atividade de jornada, consulte Métricas padrão que se aplicam a projetos, campanhas e jornadas do Amazon Pinpoint.

Estrutura JSON

Para ajudá-lo a analisar e usar os resultados da consulta, o Amazon Pinpoint APIs Analytics usa a mesma estrutura de resposta JSON para todos os dados analíticos do Amazon Pinpoint que você pode consultar programaticamente para métricas de aplicativos, métricas de campanha e métricas de engajamento na jornada. Cada resposta JSON especifica os valores que definiram a consulta, como o ID do projeto (ApplicationId). A resposta também inclui um (e apenas um) objeto KpiResult. O objeto KpiResult contém o conjunto geral de resultados para uma consulta.

Cada objeto KpiResult contém um objeto Rows. Esta é uma matriz de objetos que contêm resultados de consulta e metadados relevantes sobre os valores nesses resultados. A estrutura e o conteúdo de um objeto Rows têm as seguintes características gerais:

  • Cada linha de resultados da consulta é um objeto JSON separado, chamado Values, no objeto Rows. Por exemplo, se uma consulta retornar três valores, o objeto Rows conterá três objetos Values. Cada objeto Values contém um resultado individual para a consulta.

  • Cada coluna de resultados de consulta é uma propriedade do objeto Values ao qual ela se aplica. O nome da coluna é armazenado no campo Key do objeto Values.

  • Para resultados de consulta agrupados, cada objeto Values tem um objeto GroupedBys associado. O objeto GroupedBys indica qual campo foi usado para agrupar os resultados. Ele também fornece o valor de agrupamento para o objeto Values associado.

  • Se os resultados da consulta para uma métrica forem nulos, o objeto Rows estará vazio.

Além dessas características gerais, a estrutura e o conteúdo do objeto Rows variam dependendo da métrica. Isso ocorre porque o Amazon Pinpoint oferece suporte a dois tipos de métrica: métricas de valor único e métricas de vários valores.

Uma métrica de valor único fornece apenas um valor cumulativo. Um exemplo é a porcentagem de mensagens que foram entregues aos destinatários por todas as execuções de uma campanha. Uma métrica de vários valores fornece mais de um valor e agrupa esses valores por um campo relevante. Um exemplo é a porcentagem de mensagens que foram entregues aos destinatários para cada execução de uma campanha, agrupadas por execução de campanha.

Você pode determinar rapidamente se uma métrica é uma métrica de valor único ou uma métrica de vários valores referindo-se ao nome da métrica. Se o nome não contiver grouped-by, será uma métrica de valor único. Se isso acontecer, é uma métrica de vários valores. Para obter uma lista completa das métricas que você pode consultar programaticamente, consulte Métricas padrão que se aplicam a projetos, campanhas e jornadas do Amazon Pinpoint.

Métricas de valor único

Para uma métrica de valor único, o objeto Rows contém um objeto Values que:

  • Especifica o nome amigável da métrica que foi consultada.

  • Fornece o valor para a métrica que foi consultada.

  • Identifica o tipo de dados do valor retornado.

Por exemplo, a seguinte resposta JSON contém os resultados da consulta para uma métrica de valor único. Essa métrica registra o número de endpoints exclusivos aos quais as mensagens foram entregues por todas as campanhas associadas a um projeto, de 1 de agosto de 2019 a 31 de agosto de 2019:

{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-08-31T23:59:59Z",
        "KpiName":"unique-deliveries",
        "KpiResult":{
            "Rows":[
                {
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"1368.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-08-01T00:00:00Z"
    }
}

Neste exemplo, a resposta indica que todas as campanhas do projeto entregaram mensagens para 1.368 endpoints exclusivos de 1 de agosto de 2019 a 31 de agosto de 2019, onde:

  • Key é o nome amigável da métrica cujo valor é especificado no campo Value (UniqueDeliveries).

  • Type é o tipo de dados do valor especificado no campo Value (Double).

  • Value é o valor real para a métrica que foi consultada, incluindo quaisquer filtros que foram aplicados (1368.0).

Se os resultados da consulta para uma métrica de valor único forem nulos (não maiores ou iguais a zero), o objeto Rows estará vazio. O Amazon Pinpoint retornará um valor nulo para uma métrica se não houver nenhum dado a ser retornado para a métrica. Por exemplo:

{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"2345678901234567890123456example",
        "EndTime":"2019-08-31T23:59:59Z",
        "KpiName":"unique-deliveries",
        "KpiResult":{
            "Rows":[

            ]
        },
        "StartTime":"2019-08-01T00:00:00Z"
    }
}

Métricas de vários valores

A estrutura e o conteúdo do objeto Rows para uma métrica de vários valores são principalmente os mesmos que uma métrica de valor único. O objeto Rows para uma métrica de vários valores também contém um objeto Values. O objeto Values especifica o nome amigável da métrica que foi consultada, fornece o valor para essa métrica e identifica o tipo de dados desse valor.

No entanto, o objeto Rows para uma métrica de vários valores também contém um ou mais objetos GroupedBy. Há um objeto GroupedBy para cada objeto Values nos resultados da consulta. O objeto GroupedBy indica qual campo foi usado para agrupar os dados nos resultados e o tipo de dados desse campo. Ele também indica o valor de agrupamento para esse campo (para o objeto Values associado).

Por exemplo, a seguinte resposta JSON contém os resultados da consulta para uma métrica de vários valores que relata o número de endpoints exclusivos aos quais as mensagens foram entregues, para cada campanha associada a um projeto, de 1 de agosto de 2019 a 31 de agosto de 2019:

{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-08-31T23:59:59Z",
        "KpiName":"unique-deliveries-grouped-by-campaign",
        "KpiResult":{
            "Rows":[
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"80b8efd84042ff8d9c96ce2f8example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"123.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"810c7aab86d42fb2b56c8c966example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"456.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"CampaignId",
                            "Type":"String",
                            "Value":"42d8c7eb0990a57ba1d5476a3example"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"UniqueDeliveries",
                            "Type":"Double",
                            "Value":"789.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-08-01T00:00:00Z"
    }
}

Neste exemplo, a resposta indica que três das campanhas do projeto entregaram mensagens para endpoints exclusivos de 1 de agosto de 2019 a 31 de agosto de 2019. Para cada uma dessas campanhas, a repartição das contagens de entregas é:

  • Campanha 80b8efd84042ff8d9c96ce2f8example entregou mensagens para 123 endpoints exclusivos.

  • Campanha 810c7aab86d42fb2b56c8c966example entregou mensagens para 456 endpoints exclusivos.

  • Campanha 42d8c7eb0990a57ba1d5476a3example entregou mensagens para 789 endpoints exclusivos.

Onde a estrutura geral dos objetos e campos é:

  • GroupedBys.Key: o nome da propriedade ou campo que armazena o valor de agrupamento especificado no campo GroupedBys.Value (CampaignId).

  • GroupedBys.Type: o tipo de dados do valor especificado no campo GroupedBys.Value (String).

  • GroupedBys.Value: o valor real para o campo que foi usado para agrupar os dados, conforme especificado no campo GroupedBys.Key (ID da campanha).

  • Values.Key: o nome amigável da métrica cujo valor é especificado no campo Values.Value (UniqueDeliveries).

  • Values.Type: o tipo de dados do valor especificado no campo Values.Value (Double).

  • Values.Value: o valor real para a métrica que foi consultada, incluindo quaisquer filtros que foram aplicados.

Se os resultados da consulta para uma métrica de vários valores forem nulos (não maiores ou iguais a zero) para um projeto específico, campanha ou outro recurso, o Amazon Pinpoint não retornará nenhum objeto ou campo para o recurso. Se os resultados da consulta para uma métrica de vários valores forem nulos para todos os recursos, o Amazon Pinpoint retornará um objeto Rows vazio.

Objetos e campos JSON

Além de especificar os valores que definiram uma consulta, como o ID do projeto (ApplicationId), cada resposta JSON a uma consulta para uma métrica de aplicativo, métrica de campanha ou métrica de engajamento de jornada inclui um objeto KpiResult. Este objeto contém o conjunto de resultados geral de uma consulta, que você pode analisar para enviar dados analíticos para outro serviço ou aplicativo. Cada objeto KpiResult contém alguns ou todos os seguintes objetos e campos padrão, dependendo da métrica.

Objeto ou campo Descrição
Rows Uma matriz de objetos que contém o conjunto de resultados para uma consulta.
Rows.GroupedBys Para uma métrica de vários valores, uma matriz de campos que define o campo e os valores que foram usados para agrupar dados nos resultados da consulta.
Rows.GroupedBys.Key Para uma métrica de vários valores, o nome da propriedade ou campo que armazena o valor especificado no campo GroupedBys.Value.
Rows.GroupedBys.Type Para uma métrica de vários valores, o tipo de dados do valor especificado no campo GroupedBys.Value.
Rows.GroupedBys.Value Para uma métrica de vários valores, o valor real para o campo que foi usado para agrupar dados nos resultados da consulta. Esse valor se correlaciona a um objeto Values associado.
Rows.Values Uma matriz de campos que contém resultados de consulta.
Rows.Values.Key O nome amigável da métrica que foi consultada. O valor da métrica é especificado no campo Values.Value.
Rows.Values.Type O tipo de dados do valor especificado no campo Values.Value.
Rows.Values.Value O valor real para a métrica que foi consultada, incluindo quaisquer filtros que foram aplicados.

Para obter informações sobre os campos em uma resposta JSON a uma consulta para uma métrica de execução de jornada ou métrica de execução de atividade de jornada, consulte Métricas padrão que se aplicam a projetos, campanhas e jornadas do Amazon Pinpoint.