Ten dokument zawiera instrukcje dotyczące przenoszenia istniejącego kodu z interfejsu Google Analytics Reporting API w wersji 4 do interfejsu Google Analytics Data API w wersji 1. Pokrótce omawiamy najważniejsze różnice między tymi interfejsami.
Dlaczego muszę przeprowadzić migrację?
Jeśli Twoja aplikacja potrzebuje dostępu do danych w usłudze w Google Analytics 4, musisz zaktualizować kod, aby używał interfejsu Data API w wersji 1, ponieważ interfejs Reporting API w wersji 4 ma dostęp tylko do usług utworzonych w Universal Analytics.
Wymagania wstępne
Zapoznaj się z podstawami interfejsu Data API w wersji 1, korzystając z krótkiego przewodnika.
Wprowadzenie
Zacznij od przygotowania usługi w Google Analytics 4, włączenia interfejsu Data API v1, a następnie skonfigurowania biblioteki klienta interfejsu API odpowiedniej dla Twojej platformy.
Przygotowanie usługi w Google Analytics 4
Zanim rozpoczniesz migrację kodu w celu obsługi interfejsu Data API w wersji 1, musisz przenieść witrynę do usługi w Google Analytics 4. Nie można uzupełniać usługi Google Analytics 4 danymi historycznymi z usługi w Universal Analytics.
Włącz API
Kliknij ten przycisk, aby automatycznie włączyć interfejs Data API v1 w wybranym projekcie Google Cloud.
Włączanie interfejsu Google Analytics Data API w wersji 1Korzystanie z biblioteki klienta
Instalowanie biblioteki klienta
Jeśli używasz biblioteki klienta, musisz zainstalować bibliotekę klienta Data API v1 dla swojego języka programowania.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Inicjowanie biblioteki klienta
Biblioteki klienta interfejsu Data API w wersji 1 zostały zaprojektowane tak, aby umożliwić Ci szybkie rozpoczęcie pracy. Domyślnie biblioteki klienta próbują automatycznie znaleźć dane logowania do konta usługi.
Łatwym sposobem podania danych logowania na konto usługi jest ustawienie zmiennej środowiskowej GOOGLE_APPLICATION_CREDENTIALS. Klient interfejsu API użyje wartości tej zmiennej, aby znaleźć plik JSON klucza konta usługi.
Na przykład możesz ustawić dane logowania na konto usługi, uruchamiając poniższe polecenie i korzystając ze ścieżki do pliku JSON konta usługi:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Poniżej znajdziesz fragmenty kodu powszechnie używane do inicjowania bibliotek klienta interfejsu Data API w wersji 1.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Zamiast używać zmiennej środowiskowej możesz też bezpośrednio przekazać dane logowania do instancji klienta interfejsu API podczas inicjowania usługi. Poniżej znajdziesz fragmenty kodu służące do inicjowania bibliotek klienta interfejsu Data API w wersji 1 przez bezpośrednie przekazywanie w kodzie danych logowania.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Nieużywanie biblioteki klienta
Jeśli korzystasz z interfejsu API do raportowania w wersji 4 bez biblioteki klienta, ale chcesz nadal korzystać z interfejsu Data API w wersji 1, możesz nadal używać swoich danych logowania.
Musisz skorzystać z nowego dokumentu dotyczącego punktu końcowego HTTP i odkrywania dostępnego w interfejsie Data API:
Jeśli Twój kod wykorzystuje dokument Discovery, musisz go zaktualizować do dokumentu wykrywania udostępnianego przez interfejs Data API w wersji 1:
Po zaktualizowaniu punktu końcowego musisz zapoznać się z nową strukturą żądań i pojęciami związanymi z interfejsem Data API, aby zaktualizować zapytanie JSON.
Raportowanie podstawowe
Dostępne metody raportowania
Interfejs Reporting API w wersji 4 udostępniał jedną metodę batchGet zapewniającą dostęp do podstawowych funkcji raportowania. Interfejs Data API w wersji 1 udostępnia kilka podstawowych metod raportowania:
- runReport Ta metoda zwraca niestandardowy raport z danymi o zdarzeniach z Google Analytics. Nie obsługuje ona funkcji przestawnych i jest preferowaną metodą w przypadku prostych zapytań o raporty.
- runPivotReport Ta metoda zwraca niestandardowy raport przestawny zawierający dane zdarzeń Google Analytics. Podobnie jak w przypadku przestawień w interfejsie API do raportowania w wersji 4, każda tabela zawiera opis widocznych kolumn i wierszy wymiarów w odpowiedzi raportu.
- batchRunReports To jest wsadowa wersja metody
runReport, która umożliwia generowanie wielu raportów za pomocą jednego wywołania interfejsu API. - batchRunPivotReports To jest zbiorcza wersja metody
runPivotReport, która umożliwia generowanie wielu raportów za pomocą jednego wywołania interfejsu API.
Stosowanie kilku metod raportowania jest przeważnie udogodnieniem, przy czym niektóre z nich obsługują bardziej złożone funkcje niż inne (przestawienia, grupowanie), ale poza tym mają podobną strukturę żądań.
Zmiany schematu interfejsu API
Możliwości raportowania przez interfejs API do raportowania i interfejs Data API zależą głównie od ich schematu, czyli wymiarów i danych obsługiwanych w zapytaniach raportowania. Między tymi dwoma interfejsami API występują istotne różnice w schematach API z powodu różnic koncepcyjnych między Universal Analytics a Google Analytics 4.
- Zapoznaj się z aktualną listą wymiarów i danych obsługiwanych przez interfejs Data API. Obecnie wszystkie wymiary i dane są ze sobą zgodne, nie ma więc potrzeby określania zgodnych kombinacji w narzędziu Dimensions and Metrics Explorer. To zachowanie zmieni się w przyszłości.
- Dostęp do wymiarów niestandardowych w Google Analytics 4 można uzyskać za pomocą składni wymiarów niestandardowych interfejsu Data API v1, której należy używać zamiast boksów wymiarów ga:dimensionXX w interfejsie API do raportowania w wersji 4.
- Dostęp do danych niestandardowych w Google Analytics 4 można uzyskać za pomocą składni danych niestandardowych interfejsu Data API v1, której należy używać zamiast przedziałów danych ga:metricXX w interfejsie API do raportowania w wersji 4.
- Niektóre wymiary i dane dostępne w Universal Analytics mają bezpośredni odpowiednik w Google Analytics 4. Więcej informacji znajdziesz na wykresie równoważności schematów interfejsów API UA/GA4.
- W Google Analytics 4 nazwy wymiarów i danych nie mają już prefiksu
ga:. - Niektóre funkcje Universal Analytics (np. Campaign Manager, DV360, integracja z Search Ads 360) nie są jeszcze dostępne w GA4. Gdy wdrożysz tę funkcję w Google Analytics 4, będzie ją obsługiwać interfejs Data API, a do schematu interfejsu API będą dodawane nowe wymiary i dane.
Encje
W Google Analytics 4 nie ma koncepcji widoków danych (profili) wprowadzonych w Universal Analytics. W efekcie w żądaniach raportowania interfejsu Data API w wersji 1 nie ma parametru viewId. Zamiast tego podczas wywoływania metod interfejsu Data API w wersji 1 w ścieżce adresu URL żądania należy podać numeryczny identyfikator usługi w Google Analytics 4.
Różni się to od interfejsu API do raportowania w wersji 4, który identyfikuje podmiot zgłaszający na podstawie identyfikatorów widoku danych (profili).
Interfejs Data API v1
W przypadku interfejsu Data API v1 w ścieżce adresu URL trzeba podać numeryczny identyfikator usługi Google Analytics 4.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Interfejs API do raportowania wersja 4
Interfejs Reporting API w wersji 4 wymaga określenia identyfikatora widoku (profilu) Universal Analytics w treści zapytania dotyczącego raportu.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Jeśli używasz jednej z bibliotek klienta interfejsu Data API, nie musisz ręcznie modyfikować ścieżki adresu URL żądania. Większość klientów korzystających z interfejsu API udostępnia parametr property, który oczekuje ciągu znaków w postaci properties/GA4_PROPERTY_ID. Przykłady korzystania z bibliotek klienta znajdziesz w krótkim przewodniku.
Zakresy dat
Zarówno interfejs API do raportowania w wersji 4, jak i interfejs Data API v1 obsługuje wiele zakresów dat określonych w polu dateRanges w żądaniu raportowania. Oba interfejsy API używają tego samego formatu do wprowadzania daty, akceptując bezwzględne wartości daty w postaci YYYY-MM-DD lub daty względne, takie jak yesderday, today, 7daysAgo itp.
Żądania do interfejsu Data API w wersji 1 są ograniczone do 4 zakresów dat, natomiast interfejs API do raportowania w wersji 4 dopuszcza 2 zakresy dat w jednym żądaniu raportu.
Każdy element dateRange w interfejsie Data API w wersji 1 może zawierać opcjonalne pole name, które pozwala odwołać się w odpowiedzi do odpowiedniego zakresu dat.
Jeśli nie podasz name, nazwa zakresu dat zostanie wygenerowana automatycznie.
Jeśli w żądaniu do interfejsu Data API w wersji 1 określisz wiele zakresów dat, do odpowiedzi zostanie automatycznie dodany nowy wymiar dateRange, a jako jego wartość zostanie użyta nazwa zakresu dat. Zwróć uwagę, że to zachowanie różni się od interfejsu Reporting API w wersji 4, która zwraca dane z zakresu dat jako grupę wartości danych w każdym wierszu.
Żądanie do interfejsu Data API v1
Dla każdej wartości dateRange w żądaniu używane jest opcjonalne pole name.
Ta nazwa zakresu dat zostanie użyta jako wartość wymiaru dateRange w odpowiedzi.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Odpowiedź interfejsu Data API w wersji 1
Dodatkowy wymiar dateRange jest automatycznie uwzględniany w odpowiedzi.
Wartość wymiaru dateRange zawiera nazwę zakresu dat, który pochodzi z pola dateRange.name lub jest generowany automatycznie.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Żądanie w wersji 4 interfejsu Reporting API
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Odpowiedź interfejsu API w wersji 4
W interfejsie API do raportowania w wersji 4 wartości z poszczególnych zakresów dat są zgrupowane w polu metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Sortowanie
Kolejność zapytań dotyczących raportów interfejsu Data API w wersji 1 można kontrolować za pomocą pola orderBys, podobnie jak w polu orderBys interfejsu Reporting API w wersji 4.
Specyfikacja OrderBy w interfejsie Data API w wersji 1 została zmieniona.
Każdy element OrderBy może zawierać jeden z tych elementów:
- DimensionOrderBy sortuje wyniki według wartości wymiaru.
- MetricOrderBy, sortuje wyniki według wartości danych.
- Kolumna PivotOrderBy jest używana w zapytaniach przestawnych i sortuje wyniki według wartości danych w grupie kolumn przestawnych.
Typy zamówień DELTA, SMART i HISTOGRAM_BUCKET obsługiwane przez interfejs API do raportowania w wersji 4 nie są zaimplementowane w interfejsie Data API w wersji 1.
Typ kolejności OrderType.NUMERIC w interfejsie Data API w wersji 1 jest odpowiednikiem wartości OrderType.DIMENSION_AS_INTEGER w interfejsie Reporting API w wersji 4.
Żądanie do interfejsu Data API v1
W tym przykładzie pokazujemy przykładowe zapytanie, które podaje liczbę sesji według kraju i uporządkowuje wiersze w kolejności malejącej według danych sessions.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Odpowiedź interfejsu Data API w wersji 1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Żądanie w wersji 4 interfejsu Reporting API
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Odpowiedź interfejsu API w wersji 4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Filtrowanie
Klasów dimensionFilter i metricFilter w interfejsie Data API w wersji 1 można używać, by prosić interfejs API o zwracanie danych tylko o konkretnych wartościach wymiarów lub danych. Jest to podobne do klasy dimensionFilterClauses i metricFilterClauses interfejsu Reporting API w wersji 4.
Interfejs Data API w wersji 1 nie obsługuje ciągów wyrażeń filtra, takich jak klauzula filtersExpression interfejsu Reporting API w wersji 4. Należy je przepisać z użyciem klauzul dimensionFilter i metricFilter.
Żądanie do interfejsu Data API v1
To przykładowe żądanie zwraca listę liczby sesji dla określonych ścieżek stron odwiedzonych przez użytkowników.
Klauzula dimensionFilter służy do zwracania tylko tych wierszy, których wartości wymiaru pagePath zaczynają się od /webstore/ i zawierają ciąg znaków action=a12345.
Klauzula metricFilter wymaga od metody runReport zwracania tylko wierszy z wartościami danych sessions większymi niż 1000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Żądanie w wersji 4 interfejsu Reporting API
To przykładowe żądanie jest podobne do przykładowego interfejsu Data API w wersji 1. Zwraca listę liczby sesji związanych z określonymi ścieżkami do stron odwiedzanych przez użytkowników.
Pole dimensionFilterClauses zwraca tylko wiersze z wartościami wymiaru pagePath, które zaczynają się od /webstore/ i zawierają ciąg znaków action=a12345.
Pole metricFilterClauses służy do zwracania tylko wierszy,w których wartości danych ga:sessions są większe niż 1000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Podział na strony
Interfejs Data API w wersji 1 używa pól limit i offset do podziału wyników odpowiedzi, które obejmują wiele stron, natomiast interfejs API do raportowania w wersji 4 używa wartości pageToken i pageSize.
W przypadku żądań przestawnych w interfejsie Data API w wersji 1 do wdrożenia podziału na strony dla każdej tabeli przestawnej należy użyć pól limit i offset obiektu Pivot. Pole limit jest teraz wymagane dla każdego obiektu Pivot.
Domyślnie interfejs Data API w wersji 1 zwraca maksymalnie pierwsze 10 000 wierszy danych zdarzenia, a w przypadku interfejsu API do raportowania w wersji 4 – 1000 wierszy.
Łączna liczba wierszy pasujących do zapytania jest zwracana za pomocą pola rowCount w odpowiedzi interfejsu Data API w wersji 1, która jest podobna do interfejsu Reporting API w wersji 4.
Żądanie do interfejsu Data API v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Odpowiedź interfejsu Data API w wersji 1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Żądanie w wersji 4 interfejsu Reporting API
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Odpowiedź interfejsu API w wersji 4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Agregacje wskaźników
Interfejs Data API w wersji 1 oblicza wartości zagregowanych danych tylko wtedy, gdy w żądaniu określone jest pole metricAggregations. W przeciwieństwie do tego interfejs API do raportowania w wersji 4 domyślnie zwraca wartości łączne, minimalną i maksymalną dla każdego rodzaju danych, chyba że pola hideTotals i hideValueRanges są ustawione na true.
Żądanie do interfejsu Data API v1
Agregacje będą obliczane tylko wtedy, gdy w żądaniu będzie określone pole metricAggregations.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Odpowiedź interfejsu Data API w wersji 1
Wiersze zagregowanych danych są zwracane w polach totals, minimum i maximum odpowiedzi. W wierszach danych zbiorczych pole dimensionValues zawiera specjalną wartość RESERVED_TOTAL, RESERVED_MAX lub RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Żądanie w wersji 4 interfejsu Reporting API
Przykładowe żądanie zwracania liczby sesji według kraju.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Odpowiedź interfejsu API w wersji 4
Pola totals, minimums i maximums występują domyślnie w odpowiedzi interfejsu Reporting API w wersji 4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Przestawienia
Interfejs Data API w wersji 1 obsługuje funkcję przestawną w metodach raportowania runPivotReport i batchRunPivotReports.
Interfejs API do raportowania w wersji 4 umożliwia uwzględnianie przestawienia w zapytaniach raportowania za pomocą metody batchGet.
W interfejsie Data API v1 przestawienia są implementowane inaczej niż w interfejsie API do raportowania v4, ponieważ każdy wiersz odpowiedzi odpowiada jednej komórce tabeli, natomiast w interfejsie Reporting API v4 pojedynczy wiersz odpowiedzi przedstawia pełną linię tabeli.
Interfejs Data API v1
Poniżej znajdziesz fragment odpowiedzi interfejsu Data API v1 na zapytanie runPivotReport. Każda komórka raportu przestawnego jest zwracana oddzielnie:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Interfejs API do raportowania wersja 4
Poniżej znajdziesz fragment odpowiedzi interfejsu API do raportowania w wersji 4 na zapytanie batchGet. Pojedynczy wiersz odpowiedzi reprezentuje pełny wiersz tabeli zawierający wszystkie wartości danych w tabeli przestawnej w tabeli pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
W interfejsie Data API w wersji 1 każdy wymiar zapytania runPivotReport lub batchRunPivotReports musi być zdefiniowany w obiekcie przestawnym. Wymiar nie będzie widoczny w raporcie, jeśli nie jest używany w żadnej funkcji przestawnej w zapytaniu przestawnym.
Kolumny przestawne interfejsu Data API w wersji 1 są określone w polu fieldNames, a nie dimensions w interfejsie Reporting API w wersji 4.
Jeśli w żądaniu raportowania interfejsu Data API w wersji 1 chcesz korzystać z filtrowania wymiarów, musisz użyć filtra wymiarów o zakresie na poziomie żądania. Różni się od interfejsu Reporting API w wersji 4, która akceptuje specyfikację dimensionFilterClauses w obiekcie przestawnym.
Pole offset interfejsu Data API w wersji 1 działa podobnie do pola startGroup interfejsu Reporting API w wersji 4.
Pole limit interfejsu Data API w wersji 1 jest podobne do pola maxGroupCount interfejsu Reporting API w wersji 4 i powinno ograniczać moc zbioru raportów.
Interfejs Data API w wersji 1 obsługuje wiele przestawień,o ile iloczyn parametru limit dla każdej z nich nie przekracza 100 tys. Interfejs Reporting API w wersji 4 obsługuje
tylko 1 wymiar w tabeli przestawnej.
Domyślnie wymiary zamówień interfejsu Data API w wersji 1 są wyświetlane w tabeli przestawnej według pierwszych danych w raporcie. Różni się to od interfejsu Reporting API w wersji 4, w której porządek sortowania w tabeli przestawnej jest określany w kolejności malejącej „łącznej” wartości żądanych wskaźników. Aby określić kolejność sortowania w interfejsie Data API w wersji 1, użyj pola orderBys w specyfikacji tabeli przestawnej.
Żądanie do interfejsu Data API v1
To zapytanie dotyczące interfejsu Data API w wersji 1 tworzy raport o liczbie sesji według kraju, przestawiony przez wymiar browser. Zwróć uwagę, jak zapytanie korzysta z pól orderBys, limit i offset, aby odtworzyć działanie podobnego zapytania w interfejsie Reporting API w wersji 4 i zachować ustawienia kolejności i podziału na strony.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
},
{
"name": "browser"
}
]
}
Odpowiedź interfejsu Data API w wersji 1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Żądanie w wersji 4 interfejsu Reporting API
To zapytanie przestawne interfejsu API do raportowania w wersji 4 tworzy raport o liczbie sesji według kraju, który jest przestawiony przez wymiar ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Odpowiedź interfejsu API w wersji 4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Kohorty
Interfejs Data API w wersji 1 używa specyfikacji CohortSpec do konfigurowania raportów dotyczących kohorty. Jest to podobne do specyfikacji CohortGroup w interfejsie Reporting API w wersji 4.
Wszystkie dane dostępne w interfejsie Data API w wersji 1 są obecnie zgodne z zapytaniami dotyczącymi kohorty, natomiast interfejs Reporting API v4 zezwala na wykorzystanie w zapytaniu dotyczącym kohorty tylko podzbioru specjalnych danych.
W żądaniu dotyczącym kohorty interfejsu Data API w wersji 1 wymagane są dane cohortActiveUsers.
Zarówno interfejs Data API v1, jak i interfejs Reporting API v4 umożliwiają obsługę maksymalnie 12 kohort w jednym żądaniu.
Dane dotyczące wartości od początku śledzenia nie są obecnie obsługiwane w interfejsie Data API w wersji 1.
Równoważność danych kohorty
Większość danych kohortowych zdefiniowanych w interfejsie API do raportowania w wersji 4 można zastąpić wyrażeniem, aby uzyskać w interfejsie Data API v1 równoważny wynik, jak widać na wykresie poniżej.
| Nazwa danych w wersji 4 interfejsu API do raportowania | Nazwa lub wyrażenie danych w wersji 1 interfejsu Data API |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers" oprócz filtra wymiaru według wymiaru eventName odpowiadającego wybranemu zdarzeniu realizacji celu. |
Żądanie do interfejsu Data API v1
Przykładowe zapytanie konfiguruje kohortę użytkowników, których pierwsza sesja miała miejsce w tygodniu 3 stycznia 2021 r. Liczba aktywnych użytkowników i wskaźnik utrzymania użytkowników są obliczane dla kohorty na przestrzeni 5 tygodni z zastosowaniem szczegółowości WEEKLY.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Odpowiedź interfejsu Data API w wersji 1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Żądanie w wersji 4 interfejsu Reporting API
Przykładowe zapytanie konfiguruje kohortę użytkowników, których pierwsza sesja miała miejsce w tygodniu 3 stycznia 2021 r. Liczba aktywnych użytkowników i wskaźnik utrzymania użytkowników są obliczane dla kohorty na przestrzeni 5 tygodni z zastosowaniem szczegółowości WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Odpowiedź interfejsu API w wersji 4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Próbkowanie
Interfejs Data API w wersji 1 automatycznie używa próbkowania danych, gdy przewiduje, że limity mocy zbioru obniżą jakość danych. Jeśli wyniki z danego zakresu dat są spróbkowane, pole metadata w RunReportResponse będzie zawierać odpowiedni element SamplingMetadata, podobny do pola samplingLevel, które było dostępne w interfejsie API do raportowania w wersji 4.
Częstotliwość aktualizacji danych
Interfejs Data API nie zapewnia odpowiednika pola isDataGolden z interfejsu Reporting API w wersji 4, które służyło do wskazywania, czy wszystkie działania w przypadku danego raportu zostały przetworzone. Ten sam raport może zwracać inne wyniki po wysłaniu zapytania w późniejszym terminie ze względu na dodatkowe przetwarzanie.
Segmenty (nieobsługiwane)
Interfejs Data API w wersji 1 nie obsługuje obecnie segmentów.
Raportowanie w czasie rzeczywistym
Użyj metody properties.runRealtimeReport w interfejsie Data API w wersji 1, aby generować raporty w czasie rzeczywistym dotyczące usług Google Analytics 4. Funkcja raportowania w czasie rzeczywistym w usługach Universal Analytics jest udostępniana za pomocą metody data.realtime.get interfejsu Google Analytics API w wersji 3.
Schemat raportowania w czasie rzeczywistym interfejsu Data API różni się od schematu raportowania w czasie rzeczywistym w interfejsie Analytics API w wersji 3 z powodu różnic koncepcyjnych między Universal Analytics a Google Analytics 4.
Żądanie do interfejsu Data API v1
Aby zachować domyślne zachowanie sortowania interfejsu API Google Analytics w wersji 3, w tym przykładzie dodaliśmy do przykładowego zapytania do interfejsu Data API w wersji 1 opcjonalny element orderBy.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Odpowiedź interfejsu Data API w wersji 1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Żądanie Google Analytics API v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Odpowiedź interfejsu Google Analytics API v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Nieobsługiwane) Raportowanie aktywności użytkownika
Interfejs Data API w wersji 1 nie obsługuje obecnie funkcji raportowania aktywności poszczególnych użytkowników, podobnie jak w przypadku metody userActivity.search w interfejsie Reporting API w wersji 4.
Zmiany limitów interfejsu API
Kategorie limitów podstawowych i czasu rzeczywistego
Aby umożliwić realizację limitu, interfejs Data API dzieli się na 2 kategorie żądań: podstawową i w czasie rzeczywistym. Żądania do interfejsu API wysyłane do podstawowych metod raportowania (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) obciążają limity podstawowe.
Żądania do interfejsu API wysyłane do metody runRealtimeReport obciążają limity w czasie rzeczywistym.
Limity tokenów
Oprócz limitów projektu każde żądanie obsługuje limity tokenów usługi, które są naliczane w zależności od złożoności zapytania. Szczegółowy opis limitów interfejsu API znajdziesz w dokumentacji limitów interfejsu Data API w wersji 1.
Bieżący stan wszystkich limitów usługi w Analytics można uzyskać, ustawiając wartość returnPropertyQuota na true w głównym lub rzeczywistym żądaniu raportowania. Stan limitu zostanie zwrócony w funkcji PropertyQuota.
(Nieobsługiwany) Limit na podstawie zasobów
Wszystkie podstawowe raporty w Google Analytics 4 opierają się na niespróbkowanych danych, dlatego limit oparty na zasobach wprowadzony w interfejsie Reporting API w wersji 4 nie ma już zastosowania, a żądanie raportowania interfejsu Data API w wersji 1 nie ma odpowiednika pola useResourceQuotas.
(Nieobsługiwane) Limit żądań na wyświetlenie (profil) na dzień
W Google Analytics 4 nie ma widoków danych, dlatego w interfejsie Data API w wersji 1 brakuje limitu requests per view (profile) per day. Został on zastąpiony limitami tokenów.