**Aviso de fim do suporte:** em 30 de outubro de 2026, AWS encerrará o suporte para o Amazon Pinpoint. Após 30 de outubro de 2026, você não poderá mais acessar o console do Amazon Pinpoint nem seus recursos (endpoints, segmentos, campanhas, jornadas e analytics). Para obter mais informações, consulte [Fim do suporte do Amazon Pinpoint](https://docs.aws.amazon.com/console/pinpoint/migration-guide). **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, você pode:
+ 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](analytics-standard-metrics.md).
## 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](analytics-standard-metrics.md).
### 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 | Description |
| --- | --- |
| 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](analytics-standard-metrics.md).