Questa guida spiega come creare un report di base per i dati di Analytics utilizzando l'API di dati di Google Analytics v1. I report dell'API di dati v1 sono simili ai report che puoi generare nella sezione Report dell'interfaccia utente di Google Analytics.
Questa guida illustra i principali report, la funzionalità generale di generazione dei report dell'API di dati. L'API di dati v1 dispone anche di report In tempo reale e report di canalizzazione specializzati.
runReport
è il metodo consigliato per le query ed è utilizzato in tutti gli esempi della presente guida. Consulta le funzionalità avanzate per una panoramica degli altri metodi principali di generazione dei report. Prova a utilizzare Explorer query per testare le tue query.
Panoramica dei rapporti
I report sono tabelle di dati sugli eventi per una proprietà Google Analytics 4. Ogni tabella del report contiene le dimensioni e le metriche richieste nella query, con i dati in singole righe.
Utilizza i filtri per restituire solo le righe che corrispondono a una determinata condizione e la paginazione per spostarti tra i risultati.
Ecco una tabella di report di esempio che mostra una dimensione (Country
) e una metrica (activeUsers
):
Paese | Utenti attivi |
---|---|
Giappone | 2541 |
Francia | 12 |
Specifica un'origine dati
Ogni richiesta di runReport
richiede di specificare un ID proprietà Google Analytics 4. La proprietà Analytics specificata viene utilizzata come set di dati per
la query. Esempio:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
La risposta di questa richiesta include solo i dati della proprietà Analytics
specificata come GA4_PROPERTY_ID
.
Se utilizzi le librerie client dell'API di dati, specifica l'origine dati nel parametro property
, nel formato properties/GA4_PROPERTY_ID
. Consulta la guida rapida per alcuni esempi di utilizzo delle librerie client.
Consulta Inviare eventi Measurement Protocol a Google Analytics se vuoi includere eventi Measurement Protocol nei report.
Generare un report
Per generare un report, crea un oggetto RunReportRequest
.
Ti consigliamo di iniziare con i seguenti parametri:
- Una voce valida nel campo
dateRanges
. - Almeno una voce valida nel campo
dimensions
. - 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:runReport
{
"dateRanges": [{ "startDate": "2023-09-01"", "endDate": "2023-09-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; 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.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the creation of a basic report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport * 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.RunReportSample" * }</pre> */ public class RunReportSample { public static void main(String... args) throws Exception { /** * TODO(developer): Replace this variable with your Google Analytics 4 property ID before * running the sample. */ String propertyId = "YOUR-GA4-PROPERTY-ID"; sampleRunReport(propertyId); } // Runs a report of active users grouped by country. static void sampleRunReport(String propertyId) throws Exception { // Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("country")) .addMetrics(Metric.newBuilder().setName("activeUsers")) .addDateRanges( DateRange.newBuilder().setStartDate("2020-09-01").setEndDate("2020-09-15")) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); printRunResponseResponse(response); } } // Prints results of a runReport call. static void printRunResponseResponse(RunReportResponse 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 ( DateRange, Dimension, Metric, MetricType, RunReportRequest, ) 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_report(property_id) def run_report(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report of active users grouped by country.""" client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", dimensions=[Dimension(name="country")], metrics=[Metric(name="activeUsers")], date_ranges=[DateRange(start_date="2020-09-01", end_date="2020-09-15")], ) response = client.run_report(request) print_run_report_response(response) def print_run_report_response(response): """Prints results of a runReport call.""" print(f"{response.row_count} rows received") for dimensionHeader in response.dimension_headers: print(f"Dimension header name: {dimensionHeader.name}") for metricHeader in response.metric_headers: metric_type = MetricType(metricHeader.type_).name print(f"Metric header name: {metricHeader.name} ({metric_type})") print("Report result:") for rowIdx, row in enumerate(response.rows): print(f"\nRow {rowIdx}") for i, dimension_value in enumerate(row.dimension_values): dimension_name = response.dimension_headers[i].name print(f"{dimension_name}: {dimension_value.value}") for i, metric_value in enumerate(row.metric_values): metric_name = response.metric_headers[i].name print(f"{metric_name}: {metric_value.value}")
Query sulle metriche
Metrics
sono le misurazioni quantitative dei
dati degli eventi. Devi specificare almeno una metrica nelle richieste runReport
.
Consulta Metriche API per un elenco completo delle metriche su cui puoi eseguire query.
Ecco una richiesta di esempio che mostra tre metriche, raggruppate per dimensione
date
:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "date" }],
"metrics": [
{
"name": "activeUsers"
},
{
"name": "newUsers"
},
{
"name": "totalRevenue"
}
],
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the creation of a basic report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport * 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.RunReportWithMultipleMetricsSample" * }</pre> */ public class RunReportWithMultipleMetricsSample { 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"; sampleRunReportWithMultipleMetrics(propertyId); } // Runs a report of active users, new users and total revenue grouped by date dimension. static void sampleRunReportWithMultipleMetrics(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("date")) .addMetrics(Metric.newBuilder().setName("activeUsers")) .addMetrics(Metric.newBuilder().setName("newUsers")) .addMetrics(Metric.newBuilder().setName("totalRevenue")) .addDateRanges(DateRange.newBuilder().setStartDate("7daysAgo").setEndDate("today")) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Metric, RunReportRequest, ) 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_report_with_multiple_metrics(property_id) def run_report_with_multiple_metrics(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report of active users, new users and total revenue grouped by date dimension.""" client = BetaAnalyticsDataClient() # Runs a report of active users grouped by three dimensions. request = RunReportRequest( property=f"properties/{property_id}", dimensions=[Dimension(name="date")], metrics=[ Metric(name="activeUsers"), Metric(name="newUsers"), Metric(name="totalRevenue"), ], date_ranges=[DateRange(start_date="7daysAgo", end_date="today")], ) response = client.run_report(request) print_run_report_response(response)
Ecco una risposta di esempio che mostra 1135 utenti attivi, 512 nuovi utenti e
73,0841 entrate totali nella valuta della proprietà Analytics alla data
20231025
(25 ottobre 2023).
"rows": [
...
{
"dimensionValues": [
{
"value": "20231025"
}
],
"metricValues": [
{
"value": "1135"
},
{
"value": "512"
},
{
"value": "73.0841"
}
]
},
...
],
Leggi la risposta
La risposta al report contiene un'intestazione e righe di dati. L'intestazione è composta da
DimensionHeaders
e
MetricHeaders
, che elencano le colonne nel
report. Ogni riga è composta da
DimensionValues
e
MetricValues
. L'ordine delle colonne è coerente nella richiesta, nell'intestazione e nelle righe.
Di seguito è riportato un esempio di risposta per la precedente richiesta di esempio:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"metadata": {},
"rowCount": 2
}
Raggruppa e filtra i dati
Le dimensioni sono attributi qualitativi che puoi utilizzare
per raggruppare e filtrare i dati. Ad esempio, la dimensione city
indica la
città, come Paris
o New York
, da cui ha avuto origine ogni evento. Le dimensioni sono
facoltative per le richieste runReport
e puoi utilizzare fino a nove
dimensioni per richiesta.
Consulta Dimensioni API per un elenco completo delle dimensioni che puoi utilizzare per raggruppare e filtrare i dati.
Gruppo
Ecco una richiesta di esempio che raggruppa gli utenti attivi in tre dimensioni:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [
{
"name": "country"
},
{
"name": "region"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
```
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the creation of a basic report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport * 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.RunReportWithMultipleDimensionsSample" * }</pre> */ public class RunReportWithMultipleDimensionsSample { 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"; sampleRunReportWithMultipleDimensions(propertyId); } // Runs a report of active users grouped by three dimensions. static void sampleRunReportWithMultipleDimensions(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("country")) .addDimensions(Dimension.newBuilder().setName("region")) .addDimensions(Dimension.newBuilder().setName("city")) .addMetrics(Metric.newBuilder().setName("activeUsers")) .addDateRanges(DateRange.newBuilder().setStartDate("7daysAgo").setEndDate("today")) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Metric, RunReportRequest, ) 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_report_with_multiple_dimensions(property_id) def run_report_with_multiple_dimensions(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report of active users grouped by three dimensions.""" client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", dimensions=[ Dimension(name="country"), Dimension(name="region"), Dimension(name="city"), ], metrics=[Metric(name="activeUsers")], date_ranges=[DateRange(start_date="7daysAgo", end_date="today")], ) response = client.run_report(request) print_run_report_response(response)
Di seguito è riportato un esempio di riga del report per la richiesta precedente. Questa riga mostra che erano presenti 47 utenti attivi durante l'intervallo di date specificato con eventi a Città del Capo, in Sudafrica.
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Western Cape"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
Filtro
Genera report con dati solo per valori di dimensione specifici. Per filtrare le dimensioni, specifica un FilterExpression
nel campo dimensionFilter
.
Ecco un esempio che restituisce un report sulle serie temporali di eventCount
, quando
eventName
è first_open
per ogni date
:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "date" }],
"metrics": [{ "name": "eventCount" }],
"dimensionFilter": {
"filter": {
"fieldName": "eventName",
"stringFilter": {
"value": "first_open"
}
}
},
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Filter; import com.google.analytics.data.v1beta.FilterExpression; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the usage of dimension and metric * filters in a report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#body.request_body.FIELDS.dimension_filter * 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.RunReportWithDimensionFilterSample" * }</pre> */ public class RunReportWithDimensionFilterSample { 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"; sampleRunReportWithDimensionFilter(propertyId); } // Runs a report using a dimension filter. The call returns a time series report of `eventCount` // when `eventName` is `first_open` for each date. // This sample uses relative date range values. // See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange // for more information. static void sampleRunReportWithDimensionFilter(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("date")) .addMetrics(Metric.newBuilder().setName("eventCount")) .addDateRanges( DateRange.newBuilder().setStartDate("7daysAgo").setEndDate("yesterday")) .setDimensionFilter( FilterExpression.newBuilder() .setFilter( Filter.newBuilder() .setFieldName("eventName") .setStringFilter( Filter.StringFilter.newBuilder().setValue("first_open")))) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Filter, FilterExpression, Metric, RunReportRequest, ) 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_report_with_dimension_filter(property_id) def run_report_with_dimension_filter(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report using a dimension filter. The call returns a time series report of `eventCount` when `eventName` is `first_open` for each date. This sample uses relative date range values. See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange for more information. """ client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", dimensions=[Dimension(name="date")], metrics=[Metric(name="eventCount")], date_ranges=[DateRange(start_date="7daysAgo", end_date="yesterday")], dimension_filter=FilterExpression( filter=Filter( field_name="eventName", string_filter=Filter.StringFilter(value="first_open"), ) ), ) response = client.run_report(request) print_run_report_response(response)
Ecco un altro esempio di FilterExpression
, in cui andGroup
include solo i dati che soddisfano tutti i criteri nell'elenco delle espressioni. Questo dimensionFilter
seleziona quando entrambi browser
è Chrome
e countryId
è US
:
HTTP
...
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"fieldName": "browser",
"stringFilter": {
"value": "Chrome"
}
}
},
{
"filter": {
"fieldName": "countryId",
"stringFilter": {
"value": "US"
}
}
}
]
}
},
...
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Filter; import com.google.analytics.data.v1beta.FilterExpression; import com.google.analytics.data.v1beta.FilterExpressionList; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the usage of dimension and metric * filters in a report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#body.request_body.FIELDS.dimension_filter * 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.RunReportWithMultipleDimensionFiltersSample" * }</pre> */ public class RunReportWithMultipleDimensionFiltersSample { 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"; sampleRunReportWithMultipleDimensionFilters(propertyId); } // Runs a report using multiple dimension filters joined as `and_group` expression. The filter // selects for when both `browser` is `Chrome` and `countryId` is `US`. // This sample uses relative date range values. // See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange // for more information. static void sampleRunReportWithMultipleDimensionFilters(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("browser")) .addMetrics(Metric.newBuilder().setName("activeUsers")) .addDateRanges( DateRange.newBuilder().setStartDate("7daysAgo").setEndDate("yesterday")) .setDimensionFilter( FilterExpression.newBuilder() .setAndGroup( FilterExpressionList.newBuilder() .addExpressions( FilterExpression.newBuilder() .setFilter( Filter.newBuilder() .setFieldName("browser") .setStringFilter( Filter.StringFilter.newBuilder() .setValue("Chrome")))) .addExpressions( FilterExpression.newBuilder() .setFilter( Filter.newBuilder() .setFieldName("countryId") .setStringFilter( Filter.StringFilter.newBuilder() .setValue("US")))))) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Filter, FilterExpression, FilterExpressionList, Metric, RunReportRequest, ) 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_report_with_multiple_dimension_filters(property_id) def run_report_with_multiple_dimension_filters(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report using multiple dimension filters joined as `and_group` expression. The filter selects for when both `browser` is `Chrome` and `countryId` is `US`. This sample uses relative date range values. See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange for more information. """ client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", dimensions=[Dimension(name="browser")], metrics=[Metric(name="activeUsers")], date_ranges=[DateRange(start_date="7daysAgo", end_date="yesterday")], dimension_filter=FilterExpression( and_group=FilterExpressionList( expressions=[ FilterExpression( filter=Filter( field_name="browser", string_filter=Filter.StringFilter(value="Chrome"), ) ), FilterExpression( filter=Filter( field_name="countryId", string_filter=Filter.StringFilter(value="US"), ) ), ] ) ), ) response = client.run_report(request) print_run_report_response(response)
Un elemento orGroup
include i dati che soddisfano uno qualsiasi dei criteri nell'elenco delle espressioni.
Un elemento notExpression
esclude i dati che corrispondono alla sua espressione interna. Ecco un dimensionFilter
che restituisce i dati solo quando pageTitle
non è My
Homepage
. Il report mostra i dati sugli eventi per ogni pageTitle
diverso da My
Homepage
:
HTTP
...
"dimensionFilter": {
"notExpression": {
"filter": {
"fieldName": "pageTitle",
"stringFilter": {
"value": "My Homepage"
}
}
}
},
...
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Filter; import com.google.analytics.data.v1beta.FilterExpression; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the usage of dimension and metric * filters in a report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#body.request_body.FIELDS.dimension_filter * 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.RunReportWithDimensionExcludeFilterSample" * }</pre> */ public class RunReportWithDimensionExcludeFilterSample { 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"; sampleRunReportWithDimensionExcludeFilter(propertyId); } // Runs a report using a filter with `not_expression`. The dimension filter selects for when // `pageTitle` is not `My Homepage`. // This sample uses relative date range values. // See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange // for more information. static void sampleRunReportWithDimensionExcludeFilter(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("pageTitle")) .addMetrics(Metric.newBuilder().setName("sessions")) .addDateRanges( DateRange.newBuilder().setStartDate("7daysAgo").setEndDate("yesterday")) .setDimensionFilter( FilterExpression.newBuilder() .setNotExpression( FilterExpression.newBuilder() .setFilter( Filter.newBuilder() .setFieldName("pageTitle") .setStringFilter( Filter.StringFilter.newBuilder() .setValue("My Homepage"))))) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Filter, FilterExpression, Metric, RunReportRequest, ) 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_report_with_dimension_exclude_filter(property_id) def run_report_with_dimension_exclude_filter(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report using a filter with `not_expression`. The dimension filter selects for when `pageTitle` is not `My Homepage`. This sample uses relative date range values. See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange for more information. """ client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", dimensions=[Dimension(name="pageTitle")], metrics=[Metric(name="sessions")], date_ranges=[DateRange(start_date="7daysAgo", end_date="yesterday")], dimension_filter=FilterExpression( not_expression=FilterExpression( filter=Filter( field_name="pageTitle", string_filter=Filter.StringFilter(value="My Homepage"), ) ) ), ) response = client.run_report(request) print_run_report_response(response)
Un elemento inListFilter
corrisponde ai dati di qualsiasi valore nell'elenco. Ecco un
dimensionFilter
che restituisce i dati sugli eventi in cui eventName
è uno di
purchase
, in_app_purchase
e app_store_subscription_renew
:
HTTP
...
"dimensionFilter": {
"filter": {
"fieldName": "eventName",
"inListFilter": {
"values": ["purchase",
"in_app_purchase",
"app_store_subscription_renew"]
}
}
},
...
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Filter; import com.google.analytics.data.v1beta.FilterExpression; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; import java.util.ArrayList; /** * Google Analytics Data API sample application demonstrating the usage of dimension and metric * filters in a report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#body.request_body.FIELDS.dimension_filter * 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.RunReportWithDimensionInListFilterSample" * }</pre> */ public class RunReportWithDimensionInListFilterSample { 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"; sampleRunReportWithDimensionInListFilter(propertyId); } // Runs a report using a dimension filter with `in_list_filter` expression. The filter selects for // when `eventName` is set to one of three event names specified in the query. // This sample uses relative date range values. // See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange // for more information. static void sampleRunReportWithDimensionInListFilter(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDimensions(Dimension.newBuilder().setName("eventName")) .addMetrics(Metric.newBuilder().setName("sessions")) .addDateRanges( DateRange.newBuilder().setStartDate("7daysAgo").setEndDate("yesterday")) .setDimensionFilter( FilterExpression.newBuilder() .setFilter( Filter.newBuilder() .setFieldName("eventName") .setInListFilter( Filter.InListFilter.newBuilder() .addAllValues( new ArrayList<String>() { { add("purchase"); add("in_app_purchase"); add("app_store_subscription_renew"); } }) .build()))) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Filter, FilterExpression, Metric, RunReportRequest, ) 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_report_with_dimension_in_list_filter(property_id) def run_report_with_dimension_in_list_filter(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report using a dimension filter with `in_list_filter` expression. The filter selects for when `eventName` is set to one of three event names specified in the query. This sample uses relative date range values. See https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange for more information. """ client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", dimensions=[Dimension(name="eventName")], metrics=[Metric(name="sessions")], date_ranges=[DateRange(start_date="7daysAgo", end_date="yesterday")], dimension_filter=FilterExpression( filter=Filter( field_name="eventName", in_list_filter=Filter.InListFilter( values=[ "purchase", "in_app_purchase", "app_store_subscription_renew", ] ), ) ), ) response = client.run_report(request) print_run_report_response(response)
Esplorare i report lunghi
Per impostazione predefinita, il report contiene solo le prime 10.000 righe di dati sugli eventi. Per visualizzare fino a 100.000 righe nel report, puoi includere "limit": 100000
in RunReportRequest
.
Per i report con più di 100.000 righe, devi inviare una serie di richieste e sfogliare i risultati. Ad esempio, ecco una richiesta per le prime 100.000 righe:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
...
"limit": 100000,
"offset": 0
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the use of pagination to retrieve * large result sets. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#body.request_body.FIELDS.offset * 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.RunReportWithPaginationSample" * }</pre> */ public class RunReportWithPaginationSample { 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"; sampleRunReportWithPagination(propertyId); } // Runs a report several times, each time retrieving a portion of result using pagination. static void sampleRunReportWithPagination(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDateRanges( DateRange.newBuilder().setStartDate("365daysAgo").setEndDate("yesterday")) .addDimensions(Dimension.newBuilder().setName("firstUserSource")) .addDimensions(Dimension.newBuilder().setName("firstUserMedium")) .addDimensions(Dimension.newBuilder().setName("firstUserCampaignName")) .addMetrics(Metric.newBuilder().setName("sessions")) .addMetrics(Metric.newBuilder().setName("conversions")) .addMetrics(Metric.newBuilder().setName("totalRevenue")) .setLimit(100000) .setOffset(0) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); RunReportSample.printRunResponseResponse(response); // Run the same report with a different offset value to retrieve the second page of a // response. request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDateRanges( DateRange.newBuilder().setStartDate("365daysAgo").setEndDate("yesterday")) .addDimensions(Dimension.newBuilder().setName("firstUserSource")) .addDimensions(Dimension.newBuilder().setName("firstUserMedium")) .addDimensions(Dimension.newBuilder().setName("firstUserCampaignName")) .addMetrics(Metric.newBuilder().setName("sessions")) .addMetrics(Metric.newBuilder().setName("conversions")) .addMetrics(Metric.newBuilder().setName("totalRevenue")) .setLimit(100000) .setOffset(100000) .build(); // Make the request. response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
request = RunReportRequest( property=f"properties/{property_id}", date_ranges=[DateRange(start_date="365daysAgo", end_date="yesterday")], dimensions=[ Dimension(name="firstUserSource"), Dimension(name="firstUserMedium"), Dimension(name="firstUserCampaignName"), ], metrics=[ Metric(name="sessions"), Metric(name="conversions"), Metric(name="totalRevenue"), ], limit=100000, offset=0, ) response = client.run_report(request)
Il parametro rowCount
nella risposta indica il numero totale di righe,
indipendentemente dai valori limit
e offset
nella richiesta. Ad esempio, se
la risposta mostra "rowCount": 272345
, devi avere tre richieste con 100.000 righe,ognuna
per recuperare tutti i dati.
Ecco una richiesta di esempio per le prossime 100.000 righe. Tutti gli altri parametri, come dateRange
, dimensions
e metrics
, devono essere uguali a quelli della prima richiesta.
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
...
"limit": 100000,
"offset": 100000
}
Java
request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDateRanges( DateRange.newBuilder().setStartDate("365daysAgo").setEndDate("yesterday")) .addDimensions(Dimension.newBuilder().setName("firstUserSource")) .addDimensions(Dimension.newBuilder().setName("firstUserMedium")) .addDimensions(Dimension.newBuilder().setName("firstUserCampaignName")) .addMetrics(Metric.newBuilder().setName("sessions")) .addMetrics(Metric.newBuilder().setName("conversions")) .addMetrics(Metric.newBuilder().setName("totalRevenue")) .setLimit(100000) .setOffset(100000) .build(); // Make the request. response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response);
Python
request = RunReportRequest( property=f"properties/{property_id}", date_ranges=[DateRange(start_date="365daysAgo", end_date="yesterday")], dimensions=[ Dimension(name="firstUserSource"), Dimension(name="firstUserMedium"), Dimension(name="firstUserCampaignName"), ], metrics=[ Metric(name="sessions"), Metric(name="conversions"), Metric(name="totalRevenue"), ], limit=100000, offset=100000, ) response = client.run_report(request)
Puoi utilizzare i valori offset
, ad esempio 200000
o 300000
, per recuperare
i risultati successivi. Tutti gli altri parametri, come dateRange
, dimensions
e
metrics
, devono essere uguali a quelli della prima richiesta.
Utilizzare più intervalli di date
Una richiesta di report può recuperare i dati per più dateRanges
. Ad esempio, questo report mette a confronto le prime due settimane di agosto 2022 e 2023:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
{
"startDate": "2022-08-01",
"endDate": "2022-08-14"
},
{
"startDate": "2023-08-01",
"endDate": "2023-08-14"
}
],
"dimensions": [{ "name": "platform" }],
"metrics": [{ "name": "activeUsers" }]
}
Java
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Metric; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; /** * Google Analytics Data API sample application demonstrating the usage of date ranges in a report. * * <p>See * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport#body.request_body.FIELDS.date_ranges * 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.RunReportWithDateRangesSample" * }</pre> */ public class RunReportWithDateRangesSample { 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"; sampleRunReportWithDateRanges(propertyId); } // Runs a report using two date ranges. static void sampleRunReportWithDateRanges(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()) { RunReportRequest request = RunReportRequest.newBuilder() .setProperty("properties/" + propertyId) .addDateRanges( DateRange.newBuilder().setStartDate("2019-08-01").setEndDate("2019-08-14")) .addDateRanges( DateRange.newBuilder().setStartDate("2020-08-01").setEndDate("2020-08-14")) .addDimensions(Dimension.newBuilder().setName("platform")) .addMetrics(Metric.newBuilder().setName("activeUsers")) .build(); // Make the request. RunReportResponse response = analyticsData.runReport(request); // Prints the response using a method in RunReportSample.java RunReportSample.printRunResponseResponse(response); } } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Metric, RunReportRequest, ) 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_report_with_date_ranges(property_id) def run_report_with_date_ranges(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a report using two date ranges.""" client = BetaAnalyticsDataClient() request = RunReportRequest( property=f"properties/{property_id}", date_ranges=[ DateRange(start_date="2019-08-01", end_date="2019-08-14"), DateRange(start_date="2020-08-01", end_date="2020-08-14"), ], dimensions=[Dimension(name="platform")], metrics=[Metric(name="activeUsers")], ) response = client.run_report(request) print_run_report_response(response)
Quando includi più dateRanges
in una richiesta, alla risposta viene aggiunta automaticamente una colonna dateRange
. Quando la colonna dateRange
è
date_range_0
, i dati della riga si riferiscono al primo intervallo di date. Quando la colonna dateRange
è date_range_1
, i dati della riga si riferiscono al secondo intervallo di date.
Di seguito è riportato un esempio di risposta per due intervalli di date:
{
"dimensionHeaders": [
{
"name": "platform"
},
{
"name": "dateRange"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "iOS"
},
{
"value": "date_range_0"
}
],
"metricValues": [
{
"value": "774"
}
]
},
{
"dimensionValues": [
{
"value": "Android"
},
{
"value": "date_range_1"
}
],
"metricValues": [
{
"value": "335"
}
]
},
...
],
}
Passaggi successivi
Consulta le funzionalità avanzate e i report in tempo reale per una panoramica delle funzionalità di reporting più avanzate dell'API di dati v1.