Questa è una panoramica delle funzionalità Metodo API di reporting in tempo reale dell'API di dati di Google Analytics v1. Per un riferimento dettagliato dell'API, consulta la documentazione di riferimento API.
Gli eventi vengono visualizzati nei report in tempo reale pochi secondi dopo essere stati inviati a Google Analytics. I report In tempo reale mostrano i dati sugli eventi e sull'utilizzo relativi a periodi di tempo che vanno dal momento attuale a 30 minuti prima (fino a 60 minuti per le proprietà Google Analytics 360) e possono essere utilizzati per applicazioni come i contatori in tempo reale dei visitatori sul tuo sito web.
I report In tempo reale supportano un sottoinsieme limitato di dimensioni e metriche rispetto alla funzionalità Report principali dell'API di dati v1.
Funzionalità condivise con i report principali
Le richieste di report In tempo reale hanno la stessa semantica delle richieste di report principali per molte caratteristiche condivise. Ad esempio, la paginazione, i filtri delle dimensioni e le proprietà utente, si comportano allo stesso modo nei report In tempo reale dei report principali. Consulta la panoramica della funzionalità di reporting di base dell'API di dati v1, poiché la parte restante di questo documento è incentrata sulle funzionalità specifiche per le richieste di report in tempo reale.
Richiesta di report
Per richiedere report in tempo reale, puoi creare un oggetto RunRealtimeReportRequest. Ti consigliamo di iniziare con questi parametri di richiesta:
- Almeno una voce valida nel campo dimensioni.
- Almeno una voce valida nel campo metrics.
Ecco una richiesta di esempio con i campi consigliati.
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.DimensionHeader;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MetricHeader;
import com.google.analytics.data.v1beta.Row;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportSample"
* }</pre>
*/
public class RunRealtimeReportSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReport(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReport(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("country"))
.addMetrics(Metric.newBuilder().setName("activeUsers"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
printRunRealtimeReportResponse(response);
}
}
// Prints results of a runRealReport call.
static void printRunRealtimeReportResponse(RunRealtimeReportResponse response) {
System.out.printf("%s rows received%n", response.getRowsList().size());
for (DimensionHeader header : response.getDimensionHeadersList()) {
System.out.printf("Dimension header name: %s%n", header.getName());
}
for (MetricHeader header : response.getMetricHeadersList()) {
System.out.printf("Metric header name: %s (%s)%n", header.getName(), header.getType());
}
System.out.println("Report result:");
for (Row row : response.getRowsList()) {
System.out.printf(
"%s, %s%n", row.getDimensionValues(0).getValue(), row.getMetricValues(0).getValue());
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report(property_id)
def run_realtime_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
Segnala risposta
La risposta al report in tempo reale della richiesta API è principalmente un'intestazione e delle righe. L'intestazione è composta da DimensionHeaders e MetricHeaders che elencano le colonne del report. Ogni riga è composta da DimensionValues e MetricValues per le colonne del report. L'ordine delle colonne è coerente nella richiesta, nell'intestazione e in ogni riga.
Di seguito è riportato un esempio di risposta per la richiesta di esempio riportata sopra:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"rowCount": 2
}
Dimensioni
Le dimensioni descrivono e raggruppano i dati sugli eventi relativi al tuo sito web o alla tua app. La dimensione city, ad esempio, indica la città ("Parigi" o "New York") da cui ha avuto origine ogni evento. In una richiesta di report, puoi
specificare zero o più dimensioni. Consulta la sezione Dimensioni in tempo reale per un elenco completo dei nomi delle dimensioni API disponibili nelle richieste in tempo reale.
Ad esempio, questa richiesta raggruppa Utenti attivi in due colonne di dimensione:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [
{
"name": "country"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportWithMultipleDimensionsSample"
* }</pre>
*/
public class RunRealtimeReportWithMultipleDimensionsSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMultipleDimensions(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMultipleDimensions(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("country"))
.addDimensions(Dimension.newBuilder().setName(("city")))
.addMetrics(Metric.newBuilder().setName("activeUsers"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report_with_multiple_dimensions(property_id)
def run_realtime_report_with_multiple_dimensions(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country"), Dimension(name="city")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
Ad esempio, una riga nella risposta del report potrebbe contenere quanto segue. Questa riga indica che ci sono 47 utenti attivi per il tuo sito web o la tua app con eventi da Città del Capo, Sudafrica negli ultimi 30 minuti.
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
Metriche
Le metriche sono misurazioni quantitative dei dati sugli eventi per il sito web o l'app. In una richiesta di report, puoi specificare una o più metriche. Consulta Metriche in tempo reale per un elenco completo dei nomi delle metriche API disponibili nelle richieste.
Ad esempio, questa richiesta mostrerà le due metriche raggruppate in base alla dimensione unifiedScreenName:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "unifiedScreenName" }],
"metrics": [
{
"name": "screenPageViews"
},
{
"name": "conversions"
}
],
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportWithMultipleMetricsSample"
* }</pre>
*/
public class RunRealtimeReportWithMultipleMetricsSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMultipleMetrics(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMultipleMetrics(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("unifiedScreenName"))
.addMetrics(Metric.newBuilder().setName(("screenPageViews")))
.addMetrics(Metric.newBuilder().setName("conversions"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report_with_multiple_metrics(property_id)
def run_realtime_report_with_multiple_metrics(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="unifiedScreenName")],
metrics=[Metric(name="screenPageViews"), Metric(name="conversions")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
Ad esempio, una riga nella risposta del report potrebbe contenere quanto segue. Questa riga
significa che per il titolo della pagina (web) o il nome schermata (app) di main_menu, sono stati registrati
257 visualizzazioni e 72 eventi di conversione negli ultimi 30 minuti.
"rows": [
...
{
"dimensionValues": [
{
"value": "main_menu"
}
],
"metricValues": [
{
"value": "257"
},
{
"value": "72"
}
]
},
...
],
Intervalli di minuti
In una richiesta di report in tempo reale, puoi utilizzare il campo minuteRanges per specificare gli intervalli minuti di dati sugli eventi da leggere. In una query è possibile utilizzare fino a due intervalli di minuti diversi. Se una specifica dell'intervallo di minuti non è presente in una query, verrà utilizzato un singolo intervallo di minuti degli ultimi 30 minuti.
Ad esempio, la richiesta riportata di seguito mostrerà il conteggio degli utenti attivi per due intervalli di minuti separati:
- Intervallo 1: da 4 minuti fa al momento attuale.
Intervallo 2: da 29 minuti fa a 25 minuti fa (incluso).
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"metrics": [
{
"name": "activeUsers"
}
],
"minuteRanges": [
{
"name": "0-4 minutes ago",
"startMinutesAgo": 4,
},
{
"name": "25-29 minutes ago",
"startMinutesAgo": 29,
"endMinutesAgo": 25,
}
],
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MinuteRange;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* for more information.
*
* <p>Before you start the application, please review the comments starting with "TODO(developer)"
* and update the code to use correct values.
*
* <p>To run this sample using Maven:
*
* <pre>{@code
* cd google-analytics-data
* mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunRealtimeReportWithMinuteRangesSample"
* }</pre>
*/
public class RunRealtimeReportWithMinuteRangesSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMinuteRanges(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMinuteRanges(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addMetrics(Metric.newBuilder().setName(("activeUsers")))
.addMinuteRanges(
MinuteRange.newBuilder().setName("0-4 minutes ago").setStartMinutesAgo(4))
.addMinuteRanges(
MinuteRange.newBuilder()
.setName("25-29 minutes ago")
.setEndMinutesAgo(29)
.setEndMinutesAgo(25))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Metric,
MinuteRange,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_realtime_report_with_minute_ranges(property_id)
def run_realtime_report_with_minute_ranges(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property. Dimensions
field is omitted in the query, which results in total values of active users
returned for each minute range in the report.
Note the `dateRange` dimension added to the report response automatically
as a result of querying multiple minute ranges.
"""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
metrics=[Metric(name="activeUsers")],
minute_ranges=[
MinuteRange(name="0-4 minutes ago", start_minutes_ago=4),
MinuteRange(
name="25-29 minutes ago", start_minutes_ago=29, end_minutes_ago=25
),
],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
Di seguito è riportato un esempio di risposta completo per la query riportata di seguito. Tieni presente che la dimensione dateRange viene aggiunta automaticamente alla risposta del report in seguito all'esecuzione di query su più minuti.
{
"dimensionHeaders": [
{
"name": "dateRange"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "0-4 minutes ago"
}
],
"metricValues": [
{
"value": "16"
}
]
},
{
"dimensionValues": [
{
"value": "25-29 minutes ago"
}
],
"metricValues": [
{
"value": "14"
}
]
}
],
"rowCount": 2,
"kind": "analyticsData#runRealtimeReport"
}