**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 [Fine del supporto di Amazon Pinpoint](https://docs.aws.amazon.com/console/pinpoint/migration-guide). **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 End User Messaging. AWS
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](analytics-standard-metrics.md).
## 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](analytics-standard-metrics.md).
### 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. 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 | Description |
| --- | --- |
| 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](analytics-standard-metrics.md).