Consultar dados do Amazon Pinpoint para mensagens SMS transacionais - Amazon Pinpoint

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

Consultar dados do Amazon Pinpoint para mensagens SMS transacionais

Para consultar os dados de mensagens SMS transacionais que foram enviadas para um projeto, use a API de Métricas de aplicativo e especifique valores para os seguintes parâmetros necessários:

  • application-id: o ID do projeto, que é o identificador exclusivo do projeto. No Amazon Pinpoint, os termos projeto e aplicativo têm o mesmo significado.

  • kpi-name: o nome da métrica a ser consultada. Esse valor descreve a métrica associada e consiste em dois ou mais termos, que são compostos por caracteres alfanuméricos minúsculos, separados por um hífen. Para obter uma lista completa das métricas compatíveis e o valor kpi-name de cada uma, consulte Métricas padrão para projetos, campanhas e jornadas.

Também é possível aplicar um filtro que consulta os dados para um intervalo de datas específico. Se você não especificar um intervalo de datas, o Amazon Pinpoint retornará os dados para os 31 dias corridos anteriores. Para filtrar os dados por datas diferentes, use os parâmetros de intervalo de datas compatíveis para especificar a primeira e a última data e hora do intervalo de datas. Os valores devem estar no formato ISO 8601 estendido e usar o Tempo Universal Coordenado (UTC), por exemplo, 2019-09-06T20:00:00Z para 20h UTC 6 de setembro de 2019. Os intervalos de datas são inclusivos e devem estar limitados a 31 dias ou menos. Adicionalmente, a primeira data e hora devem ser inferiores a 90 dias a partir do dia atual.

Os exemplos a seguir mostram como consultar dados de análise para mensagens SMS transacionais usando a API REST do Amazon Pinpoint, o AWS CLI e o AWS SDK for Java. Você pode usar qualquer AWS SDK compatível para consultar dados analíticos para mensagens transacionais. Os exemplos da AWS CLI são formatados para o Microsoft Windows. Para Unix, Linux e macOS, substitua o caractere de continuação de linha circunflexo (^) por uma barra invertida (\).

REST API

Para consultar dados de análise de mensagens SMS transacionais usando a API REST do Amazon Pinpoint, envie uma solicitação HTTP(S) GET para o URI de Métricas de aplicativo. No URI, especifique os valores apropriados para os parâmetros de caminho necessários:

https://endpoint/v1/apps/application-id/kpis/daterange/kpi-name

Em que:

  • endpoint é o endpoint do Amazon Pinpoint da Região da AWS que hospeda o projeto.

  • application-id é o identificador exclusivo do projeto.

  • kpi-name é o valor kpi-name da métrica a consultar.

Todos os parâmetros devem ser codificados por URL.

Para aplicar um filtro que recupera os dados de um intervalo de datas específico, acrescente os valores e parâmetros de consulta start-time e end-time ao URI. Ao usar esses parâmetros, é possível especificar a primeira e a última data e hora, no formato ISO 8601 estendido, de um intervalo de datas inclusivo para o qual recuperar os dados. Use um "e" comercial (&) para separar os parâmetros.

Por exemplo, a seguinte solicitação recupera o número de mensagens SMS transacionais que foram enviadas todos os dias de 6 de setembro de 2019 a 8 de setembro de 2019:

https://pinpoint.us-east-1.amazonaws.com/v1/apps/1234567890123456789012345example/kpis/daterange/txn-sms-sent-grouped-by-date?start-time=2019-09-06T00:00:00Z&end-time=2019-09-08T23:59:59Z

Em que:

  • pinpoint.us-east-1.amazonaws.com é o endpoint do Amazon Pinpoint da Região da AWS que hospeda o projeto.

  • 1234567890123456789012345example é o identificador exclusivo do projeto.

  • txn-sms-sent-grouped-by-date é o valor kpi-name da métrica do aplicativo envios, agrupados por data, que é a métrica que retorna o número de mensagens SMS transacionais que foram enviadas durante cada dia do intervalo de datas.

  • 2019-09-06T00:00:00Z é a primeira data e hora para as quais recuperar dados, como parte de um intervalo de datas inclusivo.

  • 2019-09-08T23:59:59Z é a última data e hora para as quais recuperar dados, como parte de um intervalo de datas inclusivo.

AWS CLI

Para consultar dados de análise de mensagens SMS transacionais usando a AWS CLI, use o comando get-application-date-range-kpi e especifique os valores apropriados para os parâmetros necessários:

C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id application-id ^
    --kpi-name kpi-name

Em que:

  • application-id é o identificador exclusivo do projeto.

  • kpi-name é o valor kpi-name da métrica a consultar.

Para aplicar um filtro que recupera os dados de um intervalo de datas específico, inclua os valores e parâmetros start-time e end-time na consulta. Ao usar esses parâmetros, é possível especificar a primeira e a última data e hora, no formato ISO 8601 estendido, de um intervalo de datas inclusivo para o qual recuperar os dados. Por exemplo, a seguinte solicitação recupera o número de mensagens SMS transacionais que foram enviadas todos os dias de 6 de setembro de 2019 a 8 de setembro de 2019:

C:\> aws pinpoint get-application-date-range-kpi ^
    --application-id 1234567890123456789012345example ^
    --kpi-name txn-sms-sent-grouped-by-date ^
    --start-time 2019-09-06T00:00:00Z ^
    --end-time 2019-09-08T23:59:59Z

Em que:

  • 1234567890123456789012345example é o identificador exclusivo do projeto.

  • txn-sms-sent-grouped-by-date é o valor kpi-name da métrica do aplicativo envios, agrupados por data, que é a métrica que retorna o número de mensagens SMS transacionais que foram enviadas durante cada dia do intervalo de datas.

  • 2019-09-06T00:00:00Z é a primeira data e hora para as quais recuperar dados, como parte de um intervalo de datas inclusivo.

  • 2019-09-08T23:59:59Z é a última data e hora para as quais recuperar dados, como parte de um intervalo de datas inclusivo.

SDK for Java

Para consultar dados analíticos para mensagens SMS transacionais usando o AWS SDK for Java, use o método GetApplicationDateRangeKpiRequest da API de Métricas de aplicativo e especifique os valores apropriados para os parâmetros necessários:

GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("applicationId")
        .withKpiName("kpiName")

Em que:

  • applicationId é o identificador exclusivo do projeto.

  • kpiName é o valor kpi-name da métrica a consultar.

Para aplicar um filtro que recupera os dados de um intervalo de datas específico, inclua os valores e parâmetros startTime e endTime na consulta. Ao usar esses parâmetros, é possível especificar a primeira e a última data e hora, no formato ISO 8601 estendido, de um intervalo de datas inclusivo para o qual recuperar os dados. Por exemplo, a seguinte solicitação recupera o número de mensagens SMS transacionais que foram enviadas todos os dias de 6 de setembro de 2019 a 8 de setembro de 2019:

GetApplicationDateRangeKpiRequest request = new GetApplicationDateRangeKpiRequest()
        .withApplicationId("1234567890123456789012345example")
        .withKpiName("txn-sms-sent-grouped-by-date")
        .withStartTime(Date.from(Instant.parse("2019-09-06T00:00:00Z")))
        .withEndTime(Date.from(Instant.parse("2019-09-08T23:59:59Z")));

Em que:

  • 1234567890123456789012345example é o identificador exclusivo do projeto.

  • txn-sms-sent-grouped-by-date é o valor kpi-name da métrica do aplicativo envios, agrupados por data, que é a métrica que retorna o número de mensagens SMS transacionais que foram enviadas durante cada dia do intervalo de datas.

  • 2019-09-06T00:00:00Z é a primeira data e hora para as quais recuperar dados, como parte de um intervalo de datas inclusivo.

  • 2019-09-08T23:59:59Z é a última data e hora para as quais recuperar dados, como parte de um intervalo de datas inclusivo.

Depois de enviar sua consulta, o Amazon Pinpoint retorna os resultados dela em uma resposta JSON. A estrutura dos resultados varia dependendo da métrica consultada. Algumas métricas retornam apenas um valor. Outras métricas retornam vários valores e agrupam esses valores por um campo relevante. Se uma métrica retornar vários valores, a resposta JSON incluirá um campo que indica qual campo foi usado para agrupar os dados.

Por exemplo, a métrica do aplicativo sends, grouped by date (txn-sms-sent-grouped-by-date), usada nos exemplos anteriores, retorna vários valores: o número de mensagens SMS transacionais enviadas durante cada dia do intervalo de datas especificado. Nesse caso, a resposta JSON é a seguinte:

{
    "ApplicationDateRangeKpiResponse":{
        "ApplicationId":"1234567890123456789012345example",
        "EndTime":"2019-09-08T23:59:59Z",
        "KpiName":"txn-sms-sent-grouped-by-date",
        "KpiResult":{
            "Rows":[
                {
                    "GroupedBys":[
                        {
                            "Key":"Date",
                            "Type":"String",
                            "Value":"2019-09-06"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"TxnSmsSent",
                            "Type":"Double",
                            "Value":"29.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"Date",
                            "Type":"String",
                            "Value":"2019-09-07"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"TxnSmsSent",
                            "Type":"Double",
                            "Value":"35.0"
                        }
                    ]
                },
                {
                    "GroupedBys":[
                        {
                            "Key":"Date",
                            "Type":"String",
                            "Value":"2019-09-08"
                        }
                    ],
                    "Values":[
                        {
                            "Key":"TxnSmsSent",
                            "Type":"Double",
                            "Value":"10.0"
                        }
                    ]
                }
            ]
        },
        "StartTime":"2019-09-06T00:00:00Z"
    }
}

Nesse caso, o campo GroupedBys indica que os valores são agrupados por dia do calendário (Date). Isto significa que:

  • 29 mensagens foram enviadas em 6 de setembro de 2019.

  • 35 mensagens foram enviadas em 7 de setembro de 2019.

  • 10 mensagens foram enviadas em 8 de setembro de 2019.

Para saber mais sobre a estrutura dos resultados da consulta, consulte Usar resultados da consulta JSON.