Con le attività relative ai report, puoi avviare una richiesta asincrona di lunga durata per creare un report personalizzato sui dati degli eventi di Google Analytics.
La risorsa Attività report generata da questa richiesta può essere utilizzata per accedere a report personalizzati da tutti gli utenti con accesso in lettura alla tua proprietà Google Analytics.
Una volta pronto, un report personalizzato sarà disponibile per 72 ore. Dopo questo periodo, la risorsa dell'attività report corrispondente e i suoi contenuti verranno eliminati automaticamente.
Creare un'attività report
La versione 1 dell'API di dati di Google Analytics utilizza un approccio asincrono per creare attività report. Innanzitutto, è necessaria una richiesta al metodo reportTasks.create
per creare un'attività report. Successivamente, viene utilizzato il metodo
reportTasks.query
per recuperare il report personalizzato generato.
Inoltre, puoi utilizzare reportTasks.get
per recuperare i metadati di configurazione su un'attività report specifica e reportTasks.list
per elencare tutte le attività report per una proprietà.
Seleziona un'entità segnalante
Tutti i metodi dell'API di dati v1 richiedono l'identificatore della proprietà Google Analytics 4 da specificare all'interno di un percorso di richiesta dell'URL nella forma di properties/GA4_PROPERTY_ID
, ad esempio:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks
Il report viene generato in base ai dati sugli eventi di Google Analytics raccolti nella proprietà Google Analytics 4 specificata.
Se utilizzi una delle librerie client dell'API di dati, non è necessario modificare manualmente il percorso dell'URL della richiesta.
La maggior parte dei client API fornisce un parametro property
che prevede una stringa in forma di properties/GA4_PROPERTY_ID
.
Consulta la guida rapida per esempi
di utilizzo delle librerie client.
Richiedere la creazione dell'attività report
Per creare un'attività report, chiama il metodo reportTasks.create
utilizzando l'oggetto ReportTask
in una richiesta. I seguenti parametri sono obbligatori:
reportDefinition
che descrive la definizione di un report personalizzato. La struttura di questo parametro è simile alla definizione del report utilizzata dai metodi di reporting principali.
Esempio di richiesta di creazione di un'attività report:
Richiesta HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
Una risposta del metodo reportTasks.create
contiene il nome dell'attività di report nel campo name
(ad esempio properties/1234567/reportTasks/123
), che può essere utilizzato nelle query successive per ottenere lo stato di un'attività report e recuperare il report risultante.
Risposta HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
Recupero dello stato di idoneità dell'attività di report
La generazione di un report dopo la chiamata a reportTasks.create
potrebbe richiedere diversi minuti. Puoi ottenere lo stato di idoneità per un'attività report chiamando il metodo reportTasks.get
.
Usa il nome dell'attività report (ad esempio properties/1234567/reportTasks/123
)
ricevuto da una risposta reportTasks.create
per specificare l'attività
report.
Esempio:
Richiesta HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
Lo stato di idoneità per un'attività report viene restituito nel campo state
di una risposta. Al termine della generazione del report, lo stato di un'attività report cambia da CREATING
a ACTIVE
.
Il campo reportMetadata
contiene informazioni generali sul report generato, ad esempio il numero di righe e la quantità di token di quota addebitati.
Risposta HTTP
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
Puoi ottenere lo stato di tutte le attività report chiamando il metodo reportTasks.list
.
Recupera il report generato
Dopo aver generato l'attività report creata utilizzando il metodo
reportTasks.create
, chiama il
metodo
reportTasks.query
e specifica il nome dell'attività report
(ad esempio properties/1234567/reportTasks/123
).
Richiesta HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
Se l'attività report è pronta, viene restituita una risposta contenente il report generato:
Risposta HTTP
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}