Usa i risultati delle query JSON di Amazon Pinpoint Analytics - Amazon Pinpoint
Struttura JSONOggetti e campi JSON

Avviso di fine del supporto: il 30 ottobre 2026, AWS terminerà il supporto per Amazon Pinpoint. Dopo il 30 ottobre 2026, non potrai più accedere alla console Amazon Pinpoint o alle risorse Amazon Pinpoint (endpoint, segmenti, campagne, percorsi e analisi). Per ulteriori informazioni, consulta la pagina relativa alla fine del supporto di Amazon Pinpoint. Nota: per quanto APIs riguarda gli SMS, i comandi vocali, i messaggi push su dispositivi mobili, l'OTP e la convalida del numero di telefono non sono interessati da questa modifica e sono supportati da AWS End User Messaging.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Usa i risultati delle query JSON di Amazon Pinpoint Analytics

Quando usi Amazon Pinpoint Analytics APIs per interrogare i dati di analisi, Amazon Pinpoint restituisce i risultati in una risposta JSON. Per le metriche delle applicazioni, le metriche delle campagne e le metriche di coinvolgimento del percorso, i dati nella risposta sono conformi a uno schema JSON standard per la creazione di report di dati di analisi di Amazon Pinpoint.

Ciò significa che è possibile utilizzare il linguaggio di programmazione o lo strumento di propria scelta per implementare una soluzione personalizzata che esegua query sui dati per uno o più di questi parametri, acquisisca i risultati di ogni query e quindi scriva i risultati in una tabella, un oggetto o un'altra posizione. È quindi possibile utilizzare i risultati delle query in tale posizione utilizzando un altro servizio o applicazione.

Ad esempio, puoi:

  • Creare un dashboard personalizzato che esegua regolarmente le query su un set di parametri e visualizzi i risultati utilizzando il framework di visualizzazione dei dati preferito.

  • Creare un report che tenga traccia dei tassi di coinvolgimento eseguendo una query sui parametri appropriati e visualizzando i risultati in un grafico o in un altro tipo di report che si progetta.

  • Analizzare e scrivere i dati di analisi in un particolare formato di storage e quindi eseguire il port dei risultati in una soluzione di storage a lungo termine.

Tieni presente che Amazon Pinpoint Analytics APIs non è progettato per creare o archiviare oggetti persistenti da leggere o utilizzare successivamente in un progetto Amazon Pinpoint o nel tuo account Amazon Pinpoint. APIs Sono invece progettati per aiutarti a recuperare dati di analisi e trasferirli ad altri servizi e applicazioni per ulteriori analisi, archiviazione o report. Lo fanno in parte utilizzando la stessa struttura di risposta JSON e lo stesso schema per tutti i dati di analisi su cui è possibile eseguire query in modo programmatico per i parametri dell’applicazione, i parametri della campagna e i parametri di coinvolgimento del viaggio.

In questo argomento vengono illustrati la struttura, gli oggetti e i campi in una risposta JSON a una query per un parametro dell'applicazione, un parametro della campagna o un parametro di coinvolgimento del viaggio. Per informazioni sui campi in una risposta JSON a una query relativa a un parametro di esecuzione del viaggio o a un parametro di esecuzione dell'attività di viaggio, consulta Metriche standard che si applicano a progetti, campagne e percorsi Amazon Pinpoint.

Struttura JSON

Per aiutarti ad analizzare e utilizzare i risultati delle query, Amazon Pinpoint APIs Analytics utilizza la stessa struttura di risposta JSON per tutti i dati di analisi di Amazon Pinpoint che puoi interrogare a livello di codice per le metriche delle applicazioni, le metriche delle campagne e le metriche di coinvolgimento del viaggio. Ogni risposta JSON specifica i valori che hanno definito la query, ad esempio l'ID del progetto (ApplicationId). La risposta include anche un (e solo un) oggetto KpiResult. L'oggetto KpiResult contiene il set di risultati complessivo per una query.

Ogni oggetto KpiResult contiene un oggetto Rows. Si tratta di un array di oggetti che contengono risultati di query e metadati pertinenti sui valori in tali risultati. La struttura e il contenuto di un oggetto Rows presentano le seguenti caratteristiche generali:

  • Ogni riga di risultati di query è un oggetto JSON separato, denominato Values, nell'oggetto Rows. Ad esempio, se una query restituisce tre valori, l'oggetto Rows contiene tre oggetti Values. Ogni oggetto Values contiene un singolo risultato per la query.

  • Ogni colonna dei risultati della query è una proprietà dell'oggetto Values a cui si applica. Il nome della colonna viene archiviato nel campo Key dell'oggetto Values.

  • Per i risultati delle query raggruppate, ogni oggetto Values ha un oggetto GroupedBys associato. L'oggetto GroupedBys indica quale campo è stato utilizzato per raggruppare i risultati. Fornisce inoltre il valore di raggruppamento per l'oggetto Values associato.

  • Se i risultati della query per un parametro sono null, l'oggetto Rows è vuoto.

Al di là di queste caratteristiche generali, la struttura e il contenuto dell'oggetto Rows variano a seconda del parametro. Questo perché Amazon Pinpoint supporta due tipi di metriche, ovvero metriche a valore singolo e metriche a valore multiplo.

Un parametro a valore singolo fornisce un solo valore cumulativo. Un esempio è la percentuale di messaggi recapitati ai destinatari da tutte le esecuzioni di una campagna. Un parametro a valore multiplo fornisce più di un valore e raggruppa tali valori in base a un campo pertinente. Un esempio è la percentuale di messaggi recapitati ai destinatari per ogni esecuzione di una campagna, raggruppati per esecuzione di campagna.

È possibile stabilire rapidamente se un parametro è un parametro a valore singolo o un parametro a valore multiplo facendo riferimento al nome del parametro. Se il nome non contiene grouped-by, si tratta di un parametro a valore singolo. Se lo fa, è un parametro a valore multiplo. Per un elenco completo dei parametri su cui è possibile eseguire query a livello di programmazione, consulta Metriche standard che si applicano a progetti, campagne e percorsi Amazon Pinpoint.

Parametri a valore singolo

Per un parametro a valore singolo, l'oggetto Rows contiene un oggetto Values che:

  • Specifica il nome descrittivo del parametro su cui è stata eseguita la query.

  • Fornisce il valore per il parametro su cui è stata eseguita la query.

  • Identifica il tipo di dati del valore restituito.

Ad esempio, la seguente risposta JSON contiene i risultati della query per un parametro a valore singolo. Questo parametro riporta il numero di endpoint univoci a cui sono stati recapitati i messaggi da tutte le campagne associate a un progetto, dal 1° agosto 2019 al 31 agosto 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"
    }
}

In questo esempio, la risposta indica che tutte le campagne del progetto hanno recapitato messaggi a 1.368 endpoint univoci dal 1 agosto 2019 al 31 agosto 2019, dove:

  • Key è il nome descrittivo del parametro il cui valore è specificato nel campo Value (UniqueDeliveries).

  • Type è il tipo di dati del valore specificato nel campo Value (Double).

  • Value è il valore effettivo per il parametro su cui è stata eseguita la query, inclusi eventuali filtri applicati (1368.0).

Se il risultato della query per una metrica a valore singolo è nullo (non maggiore o uguale a zero), l'oggetto Rows è vuoto. Amazon Pinpoint restituisce un valore nullo per una metrica se non ci sono dati da restituire per la metrica. Per esempio:

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

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

Parametri a più valori

La struttura e il contenuto dell'oggetto Rows per un parametro a più valori sono per lo più uguali a un parametro a valore singolo. L'oggetto Rows per un parametro a valore multiplo contiene anche un oggetto Values. L'oggetto Values specifica il nome descrittivo del parametro con query, fornisce il valore per tale parametro e identifica il tipo di dati di tale valore.

Tuttavia, l'oggetto Rows per un parametro a più valori contiene anche uno o più oggetti GroupedBy. Esiste un oggetto GroupedBy per ogni oggetto Values nei risultati della query. L'oggetto GroupedBy indica quale campo è stato utilizzato per raggruppare i dati nei risultati e il tipo di dati di quel campo. Indica anche il valore di raggruppamento per quel campo (per l'oggetto Values associato).

Ad esempio, la seguente risposta JSON contiene i risultati della query per un parametro a più valori che segnala il numero di endpoint univoci a cui sono stati recapitati i messaggi per ogni campagna associata a un progetto, dal 1 agosto 2019 al 31 agosto 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"
    }
}

In questo esempio, la risposta indica che tre delle campagne del progetto hanno inviato messaggi a endpoint univoci dal 1 agosto 2019 al 31 agosto 2019. Per ciascuna di queste campagne, la ripartizione dei conteggi dei recapiti è:

  • La campagna 80b8efd84042ff8d9c96ce2f8example ha recapitato messaggi a 123 endpoint univoci.

  • La campagna 810c7aab86d42fb2b56c8c966example ha recapitato messaggi a 456 endpoint univoci.

  • La campagna 42d8c7eb0990a57ba1d5476a3example ha recapitato messaggi a 789 endpoint univoci.

Dove la struttura generale degli oggetti e dei campi è:

  • GroupedBys.Key: nome della proprietà o del campo che archivia il valore di raggruppamento specificato nel campo GroupedBys.Value (CampaignId).

  • GroupedBys.Type: tipo di dati del valore specificato nel campo GroupedBys.Value (String).

  • GroupedBys.Value: valore effettivo del campo utilizzato per raggruppare i dati, come specificato nel campo GroupedBys.Key (ID campagna).

  • Values.Key: nome descrittivo della metrica il cui valore è specificato nel campo Values.Value (UniqueDeliveries).

  • Values.Type: tipo di dati del valore specificato nel campo Values.Value (Double).

  • Values.Value: valore effettivo della metrica su cui è stata eseguita la query, inclusi tutti i filtri applicati.

Se i risultati della query per una metrica a più valori sono null (non maggiori di o uguali a zero) per un progetto, una campagna o un'altra risorsa specifica, Amazon Pinpoint non restituisce alcun oggetto o campo per la risorsa. Se i risultati della query per una metrica a più valori sono null per tutte le risorse, Amazon Pinpoint restituisce un oggetto Rows vuoto.

Oggetti e campi JSON

Oltre a specificare i valori che hanno definito una query, ad esempio l'ID del progetto (ApplicationId), ogni risposta JSON a una query per un parametro dell'applicazione, il parametro della campagna o il parametro del viaggio include un oggetto KpiResult. Questo oggetto contiene il set di risultati complessivo per una query, che è possibile analizzare per inviare dati di analisi analitici a un altro servizio o applicazione. Ogni oggetto KpiResult contiene alcuni o tutti i seguenti oggetti e campi standard, a seconda del parametro.

Oggetto o campo Descrizione
Rows Un array di oggetti che contiene il set di risultati per una query.
Rows.GroupedBys Per un parametro a più valori, un parametro di campi che definisce il campo e i valori utilizzati per raggruppare i dati nei risultati delle query.
Rows.GroupedBys.Key Per un parametro a più valori, il nome della proprietà o del campo che memorizza il valore specificato nel campo GroupedBys.Value.
Rows.GroupedBys.Type Per un parametro a più valori, il tipo di dati del valore specificato nel campo GroupedBys.Value.
Rows.GroupedBys.Value Per un parametro a più valori, il valore effettivo per il campo utilizzato per raggruppare i dati nei risultati delle query. Questo valore è correlato a un oggetto Values associato.
Rows.Values Un array di campi che contiene i risultati delle query.
Rows.Values.Key Il nome descrittivo del parametro su cui è stata eseguita la query. Il valore del parametro è specificato nel campo Values.Value.
Rows.Values.Type Il tipo di dati del valore specificato nel campo Values.Value.
Rows.Values.Value Il valore effettivo per il parametro su cui è stata eseguita la query, inclusi tutti i filtri applicati.

Per informazioni sui campi in una risposta JSON a una query relativa a un parametro di esecuzione del viaggio o a un parametro di esecuzione dell'attività di viaggio, consulta Metriche standard che si applicano a progetti, campagne e percorsi Amazon Pinpoint.