Usar resultados de consultas JSON de análisis de Amazon Pinpoint - Amazon Pinpoint
Estructura JSONObjetos y campos JSON

Aviso de fin de soporte: el 30 de octubre de 2026, AWS finalizará el soporte para Amazon Pinpoint. Después del 30 de octubre de 2026, ya no podrá acceder a la consola de Amazon Pinpoint ni a los recursos de Amazon Pinpoint (puntos de enlace, segmentos, campañas, recorridos y análisis). Para obtener más información, consulte el fin del soporte de Amazon Pinpoint. Nota: en lo APIs que respecta a los SMS, este cambio no afecta a los mensajes de voz, a las notificaciones push móviles, a las OTP y a la validación de números de teléfono, y son compatibles con la mensajería para el usuario AWS final.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Usar resultados de consultas JSON de análisis de Amazon Pinpoint

Cuando utiliza Amazon Pinpoint Analytics APIs para consultar datos de análisis, Amazon Pinpoint devuelve los resultados en una respuesta JSON. Para las métricas de aplicación, las métricas de campaña y las métricas de interacción del recorrido, los datos de la respuesta siguen un esquema JSON estándar a la hora de generar informes de datos de análisis de Amazon Pinpoint.

Esto significa que puede utilizar el lenguaje de programación o la herramienta de su elección para implementar una solución personalizada que consulte los datos de una o más de estas métricas, capture los resultados de cada consulta y, a continuación, escriba los resultados en una tabla, en un objeto o en otra ubicación. Luego podrá trabajar con los resultados de la consulta en esa ubicación con otro servicio o aplicación.

Por ejemplo, puede hacer lo siguiente:

  • Crear un panel personalizado que consulte regularmente un conjunto de métricas y muestre los resultados en el marco de visualización de datos preferido.

  • Crear un informe que realice un seguimiento de las tasas de interacción a partir de las métricas adecuadas y mostrar los resultados en un gráfico u otro tipo de informe que haya diseñado.

  • Analizar y escribir datos de análisis en un formato de almacenamiento determinado y, a continuación, trasladar los resultados a una solución de almacenamiento a largo plazo.

Tenga en cuenta que Amazon Pinpoint Analytics APIs no está diseñado para crear ni almacenar ningún objeto persistente que pueda leer o utilizar posteriormente en un proyecto de Amazon Pinpoint o en su cuenta de Amazon Pinpoint. Por el contrario, APIs están diseñados para ayudarle a recuperar datos analíticos y transferirlos a otros servicios y aplicaciones para su posterior análisis, almacenamiento o elaboración de informes. Utilizan en parte la misma estructura de respuesta y esquema JSON para todos los datos de análisis que se puede consultar mediante programación para métricas de aplicación, métricas de campaña y métricas de interacción del recorrido.

En este tema se explica la estructura, los objetos y los campos de una respuesta JSON a una consulta para métricas de aplicación, métricas de campaña y métricas de interacción del recorrido. Para obtener información sobre los campos de una respuesta JSON a una consulta para una métrica de ejecución de recorrido o una métrica de ejecución de actividad de recorrido, consulte Métricas estándar que se aplican a los proyectos, campañas y recorridos de Amazon Pinpoint.

Estructura JSON

Para ayudarle a analizar y utilizar los resultados de las consultas, Amazon Pinpoint Analytics APIs utiliza la misma estructura de respuesta JSON para todos los datos de Amazon Pinpoint Analytics, que puede consultar mediante programación para obtener métricas de aplicaciones, métricas de campañas y métricas de interacción con el recorrido. Cada respuesta JSON especifica los valores que definieron la consulta, como el ID del proyecto (ApplicationId). La respuesta también incluye un (solo) objeto KpiResult. El objeto KpiResult contiene el conjunto de resultados generales de una consulta.

Cada objeto KpiResult contiene un objeto Rows. Se trata de una matriz de objetos que contiene resultados de consulta y los metadatos relevantes sobre los valores de esos resultados. La estructura y el contenido de un objeto Rows tienen las siguientes características generales:

  • Cada fila de resultados de la consulta es un objeto JSON separado, denominado Values, en el objeto Rows. Por ejemplo, si una consulta devuelve tres valores, el objeto Rows contiene tres objetos Values. Cada objeto Values contiene un resultado individual para la consulta.

  • Cada columna de los resultados de consulta es una propiedad del objeto Values al que se aplica. El nombre de la columna se almacena en el campo Key del objeto Values.

  • Para los resultados de consultas agrupadas, cada objeto Values tiene un objeto GroupedBys asociado. El objeto GroupedBys indica qué campo se utilizó para agrupar los resultados. También proporciona el valor de agrupación para el objeto Values asociado.

  • Si los resultados de la consulta de una métrica son nulos, el objeto Rows estará vacío.

Además de estas características generales, la estructura y el contenido del objeto Rows varía según la métrica. Esto se debe a que Amazon Pinpoint admite dos tipos de métricas: las métricas de valor único y las métricas de varios valores.

Una métrica de valor único solo proporciona un valor acumulativo. Un ejemplo es el porcentaje de mensajes entregados a los destinatarios por todas las ejecuciones de una campaña. Una métrica de varios valores proporciona más de un valor y los agrupa por campo relevante. Un ejemplo es el porcentaje de mensajes entregados a los destinatarios en cada ejecución de una campaña, agrupados por ejecución de campaña.

Para determinar rápidamente si una métrica es de valor único o de varios valores observe el nombre de la métrica. Si el nombre no contiene grouped-by, se tratará de una métrica de valor único. Si lo contiene, será una métrica de varios valores. Para obtener una lista completa de las métricas que puede consultar mediante programación, visite Métricas estándar que se aplican a los proyectos, campañas y recorridos de Amazon Pinpoint.

Métricas de valor único

En una métrica de valor único, el objeto Rows contiene un objeto Values que:

  • Especifica el nombre descriptivo de la métrica que se consultó.

  • Proporciona el valor de la métrica que se consultó.

  • Identifica el tipo de datos del valor devuelto.

Por ejemplo, la siguiente respuesta JSON contiene los resultados de la consulta para una métrica de valor único. Esta métrica comunica el número de puntos de enlace únicos a los que se entregaron mensajes por todas las campañas asociadas a un proyecto, desde el 1 de agosto de 2019 hasta el 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"
    }
}

En este ejemplo, la respuesta indica que todas las campañas del proyecto enviaron mensajes a 1368 puntos de enlace únicos desde el 1 de agosto de 2019 hasta el 31 de agosto de 2019, donde:

  • Key es el nombre descriptivo de la métrica cuyo valor se especifica en el campo Value (UniqueDeliveries).

  • Type es el tipo de datos del valor especificado en el campo Value (Double).

  • Value es el valor real de la métrica que se consultó, incluidos los filtros que se aplicaron (1368.0).

Si los resultados de la consulta para una métrica de un solo valor son nulos (no mayor o igual a cero), el objeto de Rows está vacío. Amazon Pinpoint devuelve un valor nulo para una métrica si no hay ningún dato que devolver para la métrica. Por ejemplo:

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

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

Métricas de varios valores

La estructura y el contenido del objeto Rows para una métrica de varios valores suelen ser las mismos que para una métrica de valor único. El objeto Rows de una métrica de valores múltiples también contiene un objeto Values. El objeto Values especifica el nombre descriptivo de la métrica consultada, proporciona el valor de esa métrica e identifica el tipo de datos de ese valor.

Sin embargo, el objeto Rows de una métrica de valores múltiples también contiene uno o más objetos GroupedBy. Hay un objeto GroupedBy para cada objeto Values en los resultados de la consulta. El objeto GroupedBy indica qué campo se utilizó para agrupar los datos en los resultados y el tipo de datos de ese campo. También indica el valor de agrupación para ese campo (para el objeto Values asociado).

Por ejemplo, la siguiente respuesta JSON contiene los resultados de la consulta de una métrica de varios valores que informa sobre el número de puntos de enlace únicos a los que se entregaron mensajes en cada campaña asociada a un proyecto desde el 1 de agosto de 2019 hasta el 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"
    }
}

En este ejemplo, la respuesta indica que tres de las campañas del proyecto entregaron mensajes a puntos de enlace únicos desde el 1 de agosto de 2019 hasta el 31 de agosto de 2019. Para cada una de estas campañas, el desglose de los recuentos de entregas es el siguiente:

  • La campaña 80b8efd84042ff8d9c96ce2f8example entregó mensajes a 123 puntos de enlace únicos.

  • La campaña 810c7aab86d42fb2b56c8c966example entregó mensajes a 456 puntos de enlace únicos.

  • La campaña 42d8c7eb0990a57ba1d5476a3example entregó mensajes a 789 puntos de enlace únicos.

Donde la estructura general de los objetos y campos es la siguiente:

  • GroupedBys.Key: el nombre de la propiedad o el campo que almacena el valor de agrupamiento especificado en el campo GroupedBys.Value (CampaignId).

  • GroupedBys.Type: el tipo de datos del valor especificado en el campo GroupedBys.Value (String).

  • GroupedBys.Value: el valor real del campo que se utilizó para agrupar los datos, tal como se especifica en el campo GroupedBys.Key (ID de campaña).

  • Values.Key: es el nombre descriptivo de la métrica cuyo valor se especifica en el campo Values.Value (UniqueDeliveries).

  • Values.Type: el tipo de datos del valor especificado en el campo Values.Value (Double).

  • Values.Value: el valor real de la métrica que se consultó, incluidos los filtros que se aplicaron.

Si los resultados de la consulta de una métrica de varios valores son nulos (ni mayor ni igual a cero) para un proyecto, campaña u otro recurso específico, Amazon Pinpoint no devuelve ningún objeto ni campo para el recurso. Si los resultados de la consulta de una métrica de varios valores son nulos para todos los recursos, Amazon Pinpoint devuelve un objeto Rows vacío.

Objetos y campos JSON

Además de especificar los valores que definieron una consulta, como el ID del proyecto (ApplicationId), cada respuesta JSON a una consulta para métricas de aplicación, métricas de campaña o métricas de interacción del recorrido incluye un objeto KpiResult. Este objeto contiene el conjunto de resultados generales de una consulta, que puede analizar para enviar los datos de análisis a otro servicio o aplicación. Cada objeto KpiResult contiene algunos o todos los objetos y campos estándar siguientes, dependiendo de la métrica.

Objeto o campo Descripción
Rows Matriz de objetos que contiene el conjunto de resultados de una consulta.
Rows.GroupedBys En una métrica de varios valores, es una matriz de campos que define el campo y los valores utilizados para agrupar datos en los resultados de la consulta.
Rows.GroupedBys.Key En una métrica de varios valores, es el nombre de la propiedad o del campo que almacena el valor especificado en el campo GroupedBys.Value.
Rows.GroupedBys.Type En una métrica de varios valores, es el tipo de dato del valor especificado en el campo GroupedBys.Value.
Rows.GroupedBys.Value En una métrica de varios valores, es el valor real del campo que se utilizó para agrupar datos en los resultados de la consulta. Este valor se correlaciona con un objeto Values asociado.
Rows.Values Matriz de campos que contiene los resultados de la consulta.
Rows.Values.Key El nombre descriptivo de la métrica que se consultó. El valor de la métrica se especifica en el campo Values.Value.
Rows.Values.Type Tipo de datos del valor especificado en el campo Values.Value.
Rows.Values.Value Valor real de la métrica que se consultó, incluidos los filtros que se aplicaron.

Para obtener información sobre los campos de una respuesta JSON a una consulta para una métrica de ejecución de recorrido o una métrica de ejecución de actividad de recorrido, consulte Métricas estándar que se aplican a los proyectos, campañas y recorridos de Amazon Pinpoint.