Utiliser les résultats des requêtes JSON d'Amazon Pinpoint Analytics - Amazon Pinpoint
Structure JSONObjets et champs JSON

Avis de fin de support : le 30 octobre 2026, le support d'Amazon Pinpoint AWS prendra fin. Après le 30 octobre 2026, vous ne pourrez plus accéder à la console Amazon Pinpoint ni aux ressources Amazon Pinpoint (points de terminaison, segments, campagnes, parcours et analyses). Pour plus d'informations, consultez la page de fin de support d'Amazon Pinpoint. Remarque : en ce qui APIs concerne les SMS, la voix, le push mobile, l'OTP et la validation des numéros de téléphone ne sont pas concernés par cette modification et sont pris en charge par AWS la messagerie utilisateur final.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utiliser les résultats des requêtes JSON d'Amazon Pinpoint Analytics

Lorsque vous utilisez Amazon Pinpoint Analytics APIs pour interroger des données d'analyse, Amazon Pinpoint renvoie les résultats dans une réponse JSON. Pour les métriques d'application, de campagne et d'engagement du parcours, les données de la réponse sont conformes à un schéma JSON standard pour le reporting des données analytiques Amazon Pinpoint.

Cela signifie que vous pouvez utiliser le langage de programmation ou l'outil de votre choix pour implémenter une solution personnalisée qui interroge les données pour une ou plusieurs de ces mesures, capture les résultats de chaque requête, puis écrit les résultats dans une table, un objet ou un autre emplacement. Vous pouvez ensuite utiliser les résultats de la requête dans cet emplacement à l'aide d'un autre service ou application.

Par exemple, vous pouvez :

  • Créez un tableau de bord personnalisé qui interroge régulièrement un ensemble de métriques et affiche les résultats à l'aide de votre infrastructure de visualisation de données préférée.

  • Créez un rapport qui suit les taux d'engagement en interrogeant les métriques appropriées et en affichant les résultats dans un graphique ou un autre type de rapport que vous concevez.

  • Analysez et écrivez les données analytiques dans un format de stockage particulier, puis portez les résultats vers une solution de stockage à long terme.

Notez qu'Amazon Pinpoint Analytics n'est APIs pas conçu pour créer ou stocker des objets persistants que vous pouvez ensuite lire ou utiliser dans un projet Amazon Pinpoint ou dans votre compte Amazon Pinpoint. Ils APIs sont plutôt conçus pour vous aider à récupérer des données analytiques et à les transférer vers d'autres services et applications pour une analyse, un stockage ou des rapports plus approfondis. Ils le font en partie en utilisant la même structure de réponse JSON et le même schéma pour toutes les données d'analyse que vous pouvez interroger par programmation pour les métriques d'application, de campagne et d'engagement du parcours.

Cette rubrique explique la structure, les objets et les champs d'une réponse JSON à une requête pour une métrique d'application, de campagne ou d'engagement du parcours. Pour de plus amples informations sur les champs d'une réponse JSON à une requête pour une métrique d'exécution du parcours ou d'exécution de l'activité du parcours, veuillez consulter Mesures standard qui s'appliquent aux projets, campagnes et parcours Amazon Pinpoint.

Structure JSON

Pour vous aider à analyser et à utiliser les résultats des requêtes, Amazon Pinpoint APIs Analytics utilise la même structure de réponse JSON pour toutes les données d'analyse Amazon Pinpoint que vous pouvez interroger par programmation pour obtenir des statistiques d'application, des statistiques de campagne et des statistiques d'engagement sur le parcours. Chaque réponse JSON spécifie les valeurs ayant défini la requête, telles que l'ID de projet (ApplicationId). La réponse inclut également un (et un seul) objet KpiResult. L'objet KpiResult contient le jeu de résultats global d'une requête.

Chaque objet KpiResult contient un objet Rows. Il s'agit d'un tableau d'objets contenant des résultats de requête et des métadonnées pertinentes sur les valeurs de ces résultats. La structure et le contenu d'un objet Rows présentent les caractéristiques générales suivantes :

  • Chaque ligne de résultats de requête est un objet JSON distinct, nommé Values, dans l'objet Rows. Par exemple, si une requête renvoie trois valeurs, l'objet Rows contient trois objets Values. Chaque objet Values contient un résultat individuel pour la requête.

  • Chaque colonne de résultats de requête est une propriété de l'objet Values auquel elle s'applique. Le nom de la colonne est stocké dans le champ Key de l'objet Values.

  • Pour les résultats de requête groupés, chaque objet Values a un objet GroupedBys associé. L'objet GroupedBys indique quel champ a été utilisé pour regrouper les résultats. Il fournit également la valeur de regroupement de l'objet Values associé.

  • Si le résultat de la requête pour une métrique est nul, l'objet Rows est vide.

Au-delà de ces caractéristiques générales, la structure et le contenu de l'objet Rows varient en fonction de la métrique. En effet, Amazon Pinpoint prend en charge deux types de métriques, les métriques à valeur unique et les métriques à valeur multiples.

Une métrique à valeur unique ne fournit qu'une seule valeur cumulative. Un exemple est le pourcentage de messages remis aux destinataires par toutes les exécutions d'une campagne. Une métrique à valeurs multiples fournit plus d'une valeur et regroupe ces valeurs par un champ pertinent. Un exemple est le pourcentage de messages remis aux destinataires pour chaque exécution d'une campagne, regroupés par exécution de campagne.

Vous pouvez déterminer rapidement si une métrique est à valeur unique ou à valeur multiple en faisant référence à son nom. Si le nom ne contient pas grouped-by, il s'agit d'une métrique à valeur unique. Dans le cas contraire, il s'agit d'une métrique à plusieurs valeurs. Pour obtenir la liste complète des métriques que vous pouvez interroger par programme, reportez-vous à la section Mesures standard qui s'appliquent aux projets, campagnes et parcours Amazon Pinpoint.

Métriques à valeur unique

Pour une métrique à valeur unique, l'objet Rows contient un objet Values qui :

  • spécifie le nom convivial de la mesure interrogée ;

  • fournit la valeur de la mesure interrogée ;

  • identifie le type de données de la valeur renvoyée.

Par exemple, la réponse JSON suivante contient les résultats de la requête pour une métrique à valeur unique. Cette métrique indique le nombre de points de terminaison uniques auxquels les messages ont été remis par toutes les campagnes associées à un projet, du 1er au 31 août 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"
    }
}

Dans cet exemple, la réponse indique que toutes les campagnes du projet ont remis des messages à 1 368 points de terminaison uniques du 1er au 31 août 2019, dans lesquels :

  • Key est le nom convivial de la métrique dont la valeur est spécifiée dans le champ Value (UniqueDeliveries).

  • Type est le type de données de la valeur spécifiée dans le champ Value (Double).

  • Value est la valeur réelle de la métrique interrogée, y compris les filtres appliqués (1368.0).

Si le résultat de la requête pour une métrique à valeur unique est null (pas supérieur ou égal à zéro), l'objet Rows est vide. Amazon Pinpoint renvoie une valeur nulle pour une métrique s'il n'y a aucune donnée à renvoyer pour cette métrique. Par exemple :

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

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

Métriques à valeurs multiples

La structure et le contenu de l'objet Rows pour une métrique à valeurs multiples sont essentiellement les mêmes que ceux d'une métrique à valeur unique. L'objet Rows d'une métrique à valeurs multiples contient également un objet Values. L'objet Values spécifie le nom convivial de la métrique interrogée, fournit la valeur de cette métrique et identifie le type de données de cette valeur.

Toutefois, l'objet Rows objet d'une métrique à plusieurs valeurs contient également un ou plusieurs objets GroupedBy. Il y a un objet GroupedBy pour chaque objet Values des résultats de la requête. L'objet GroupedBy indique quel champ a été utilisé pour regrouper les données dans les résultats et le type de données de ce champ. Il indique également la valeur de regroupement pour ce champ (pour l'objet Values associé).

Par exemple, la réponse JSON suivante contient les résultats de la requête pour une mesure à valeurs multiples qui indique le nombre de points de terminaison uniques auxquels les messages ont été remis, pour chaque campagne associée à un projet, du 1er août 2019 au 31 août 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"
    }
}

Dans cet exemple, la réponse indique que trois des campagnes du projet ont transmis des messages à des points de terminaison uniques du 1er août 2019 au 31 août 2019. Pour chacune de ces campagnes, la ventilation du nombre de livraisons est la suivante :

  • La campagne 80b8efd84042ff8d9c96ce2f8example a envoyé des messages à 123 points de terminaison uniques.

  • La campagne 810c7aab86d42fb2b56c8c966example a envoyé des messages à 456 points de terminaison uniques.

  • La campagne 42d8c7eb0990a57ba1d5476a3example a envoyé des messages à 789 points de terminaison uniques.

Lorsque la structure générale des objets et des champs est :

  • GroupedBys.Key : nom de la propriété ou du champ qui stocke la valeur de regroupement spécifiée dans le champ GroupedBys.Value (CampaignId).

  • GroupedBys.Type : type de données de la valeur spécifiée dans le champ GroupedBys.Value (String).

  • GroupedBys.Value : valeur réelle du champ utilisé pour regrouper les données, comme spécifié dans le champ GroupedBys.Key (ID de campagne).

  • Values.Key : nom convivial de la métrique dont la valeur est spécifiée dans le champ Values.Value (UniqueDeliveries).

  • Values.Type : type de données de la valeur spécifiée dans le champ Values.Value (Double).

  • Values.Value : valeur réelle de la métrique interrogée, y compris les filtres appliqués.

Si le résultat de la requête pour une métrique à valeurs multiples est null (pas supérieur ou égal à zéro) pour un projet, une campagne ou une autre ressource spécifique, Amazon Pinpoint ne renvoie aucun objet ou champ pour la ressource. Si le résultat de la requête pour une métrique à valeurs multiples est null pour toutes les ressources, Amazon Pinpoint renvoie un objet Rows vide.

Objets et champs JSON

Outre la spécification des valeurs ayant défini une requête, telles que l'ID de projet (ApplicationId), chaque réponse JSON à une requête pour une métrique d'application, de campagne ou d'engagement du parcours inclut un objet KpiResult. Cet objet contient le jeu de résultats global d'une requête, que vous pouvez analyser pour envoyer les données d'analyse à un autre service ou application. Chaque objet KpiResult contient une partie ou la totalité des objets et champs standard suivants, selon la métrique.

Objet ou champ Description
Rows Tableau d'objets contenant le jeu de résultats d'une requête.
Rows.GroupedBys Pour une métrique à valeurs multiples, un tableau de champs qui définit le champ et les valeurs utilisées pour regrouper des données dans les résultats de la requête.
Rows.GroupedBys.Key Pour une métrique à valeurs multiples, nom de la propriété ou du champ qui stocke la valeur spécifiée dans le champ GroupedBys.Value.
Rows.GroupedBys.Type Pour une métrique à valeurs multiples, type de données de la valeur spécifiée dans le champ GroupedBys.Value.
Rows.GroupedBys.Value Pour une métrique à plusieurs valeurs, la valeur réelle du champ utilisé pour regrouper des données dans les résultats de la requête. Cette valeur est en corrélation avec un objet Values associé.
Rows.Values Tableau de champs contenant les résultats de la requête.
Rows.Values.Key Le nom convivial de la mesure interrogée. La valeur de la métrique est spécifiée dans le champ Values.Value.
Rows.Values.Type Type de données de la valeur spécifiée dans le champ Values.Value.
Rows.Values.Value Valeur réelle de la métrique interrogée, y compris les filtres appliqués.

Pour de plus amples informations sur les champs d'une réponse JSON à une requête pour une métrique d'exécution du parcours ou d'exécution de l'activité du parcours, veuillez consulter Mesures standard qui s'appliquent aux projets, campagnes et parcours Amazon Pinpoint.