To jest przewodnik dla programistów po interfejsie Analytics Reporting API w wersji 4. Więcej informacji o tym interfejsie API znajdziesz w jego dokumentacji.
Raporty
Interfejs Analytics Reporting API w wersji 4 udostępnia metodę batchGet, która umożliwia dostęp do zasobów Raporty.
W kolejnych sekcjach opisano strukturę treści żądania batchGet
oraz strukturę treści odpowiedzi z batchGet
.
Treść żądania
Aby używać interfejsu Analytics Reporting API w wersji 4 do wysyłania żądań danych, musisz utworzyć obiekt ReportRequest, który spełnia te minimalne wymagania:
- Prawidłowy identyfikator widoku dla pola viewId.
- Co najmniej jeden prawidłowy wpis w polu dateRanges.
- Co najmniej jeden prawidłowy wpis w polu metrics.
Aby znaleźć identyfikator widoku danych, wyślij zapytanie za pomocą metody podsumowań kont lub użyj eksploratora kont.
Jeśli zakres dat nie jest podany, domyślny zakres dat to: {"startDate": "7daysAgo", "endDate": "yesterday"}
.
Oto przykładowe żądanie z minimalną liczbą wymaganych pól:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
Metoda batchGet
akceptuje maksymalnie 5 obiektów ReportRequest. Wszystkie żądania powinny mieć te same właściwości dateRange
, viewId
, segments
, samplingLevel
i cohortGroup
.
Treść odpowiedzi
Treść odpowiedzi żądania do interfejsu API to tablica obiektów Report. Struktura raportu jest definiowana w obiekcie ColumnHeader, który opisuje wymiary i dane oraz ich typy danych w raporcie. Wartości wymiarów i danych są określone w polu dane.
Oto przykładowa odpowiedź na to przykładowe żądanie:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Wskaźniki
Dane to ilościowe pomiary. Każde żądanie wymaga co najmniej 1 obiektu Metric.
W tym przykładzie dane Sessions
są dostarczane do metody batchGet
, aby uzyskać łączną liczbę sesji w wybranym zakresie dat:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Aby uzyskać listę dostępnych wymiarów i danych, możesz użyć eksploratora wymiarów i danych lub interfejsu Metadata API.
Filtrowanie
Przesyłając żądanie batchGet
, możesz poprosić o zwrócenie tylko tych danych, które spełniają określone kryteria. Aby filtrować wskaźniki, w treści żądania określ co najmniej 1 MetricFilterClauses, a w każdym elemencie MetricFilterClause
zdefiniuj co najmniej 1 MetricFilters.
W elemencie MetricFilter
określ wartości tych parametrów:
metricName
not
operator
comparisonValue
Niech {metricName}
reprezentuje dane, {operator}
– operator
, a {comparisonValue}
– comparisonValue
. Następnie filtr działa w następujący sposób:
if {metricName} {operator} {comparisonValue}
return the metric
Jeśli podasz true
dla parametru not
, filtr będzie działać w ten sposób:
if {metricName} {operator} {comparisonValue}
do not return the metric
W tym przykładzie funkcja batchGet
zwraca tylko odsłony, których wartość jest większa niż 2:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
Wyrażenia
Wyrażenie danych to wyrażenie matematyczne zdefiniowane przez Ciebie na podstawie istniejących danych. Działa ono jak dynamiczne obliczane dane. Możesz zdefiniować alias reprezentujący wyrażenie danych, na przykład:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Kolejność
Aby posortować wyniki według wartości danych:
- Podaj jego nazwę lub alias w polu
fieldName
. - Określ kolejność sortowania (
ASCENDING
lubDESCENDING
) w polusortOrder
.
W tym przykładzie funkcja batchGet
zwraca dane posortowane najpierw według sesji, a potem według odsłon w kolejności malejącej:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Wymiary
Wymiary charakteryzują użytkowników oraz ich sesje i działania.
Na przykład wymiar Miasto opisuje cechę sesji i wskazuje miasto („Paryż” lub „Nowy Jork”), z którego pochodzi każda sesja.
W żądaniu batchGet
możesz określić zero lub więcej obiektów wymiarów, np.:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Filtrowanie
Przesyłając żądanie batchGet
, możesz poprosić o zwrócenie tylko tych wymiarów, które spełniają określone kryteria. Aby filtrować wymiary, w treści żądania określ co najmniej 1 DimensionsFilterClauses (klasyfikacji wymiarów), a w każdym elemencie DimensionsFilterClause
zdefiniuj co najmniej 1 DimensionsFilters.
W elemencie DimensionsFilters
określ wartości tych parametrów:
dimensionName
not
operator
expressions
caseSensitive
Niech {dimensionName}
reprezentuje wymiar, {operator}
– operator
, a {expressions}
– expressions
. Następnie filtr działa w następujący sposób:
if {dimensionName} {operator} {expressions}
return the dimension
Jeśli podasz true
dla parametru not
, filtr będzie działać w ten sposób:
if {dimensionName} {operator} {expressions}
do not return the dimension
W tym przykładzie batchGet
zwraca wyświetlenia stron i sesje w przeglądarce Chrome:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
Kolejność
Aby posortować wyniki według wartości wymiaru:
- Podaj jego nazwę w polu
fieldName
. - W polu
sortOrder
określ kolejność sortowania (ASCENDING
lubDESCENDING
).
Na przykład funkcja batchGet
zwraca wymiary posortowane według kraju, a następnie według przeglądarki:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Zasobniki histogramu
W przypadku wymiarów z wartościami całkowitymi łatwiej jest zrozumieć ich cechy, grupując wartości w zakresy. Użyj pola histogramBuckets
, aby zdefiniować zakresy dla wynikowych zasobników i określ HISTOGRAM_BUCKET
jako typ kolejności, np.:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Wiele zakresów dat
Interfejs Google Analytics Reporting API w wersji 4 umożliwia uzyskiwanie danych z wielu zakresów dat w jednym żądaniu. Niezależnie od tego, czy w żądaniu określono 1 czy 2 zakresy dat, dane są zwracane w obiekcie dateRangeValue, np.:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Kolejność delta
Gdy żądasz wartości danych w 2 zakresach dat, możesz posortować wyniki według różnicy między wartościami danych w zakresach dat, np.:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Zachowanie wymiaru daty
Jeśli poprosisz o wymiar związany z datą lub godziną, obiekt DateRangeValue będzie zawierał tylko wartości z dat należących do odpowiednich zakresów. Pozostałe wartości spoza określonych zakresów dat to 0
.
Weźmy np. żądanie wymiaru ga:date
i danych ga:sessions
w 2 zakresach dat: w styczniu i lutym.
W odpowiedzi na żądania danych w styczniu wartością z lutego będzie 0
, a w odpowiedzi na dane z lutego – w styczniu – 0
.
Raport za styczeń
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Raport za luty
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segmenty
Aby poprosić o podzbiór danych Analytics, użyj segmentów. Możesz np. zdefiniować w jednym segmencie użytkowników z określonego kraju lub miasta, a użytkowników z określonej części Twojej witryny – w innym. Filtry zwracają tylko te wiersze, które spełniają warunek, a segmenty zwracają podzbiory użytkowników, sesji lub zdarzeń, które spełniają warunki zawierające te segmenty.
Jeśli wysyłasz żądanie obejmujące segmenty, upewnij się, że:
- Każdy element ReportRequest w metodzie
batchGet
musi zawierać identyczne definicje segmentów. - Dodajesz do listy wymiarów wymiar
ga:segment
.
Na przykład:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Więcej przykładowych żądań z segmentami znajdziesz w sekcji Przykłady.
Identyfikator segmentu
Aby poprosić o segmenty, użyj pola segmentId
.
Do wysyłania żądań segmentów nie możesz używać jednocześnie protokołu segmentId
i dynamicSegment
.
Na przykład:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Próbkowanie
Próbkowanie może wpływać na wyniki danych i jest częstą przyczyną niezgodności wartości zwracanych przez interfejs API z interfejsem internetowym. W polu samplingLevel
ustaw odpowiedni rozmiar próbki.
- Aby uzyskać szybką odpowiedź z mniejszą próbką, ustaw wartość na
SMALL
. - ustaw wartość
LARGE
na uzyskanie dokładniejszej, ale wolniejszej odpowiedzi. - ustaw wartość
DEFAULT
, aby uzyskać odpowiedź równoważącą szybkość i dokładność.
Na przykład:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
jeśli raport zawiera spróbkowane dane, interfejs Analytics Reporting API w wersji 4 zwraca pola samplesReadCounts
i samplingSpaceSizes
.
Jeśli wyniki nie są spróbkowane, pola nie zostaną zdefiniowane.
Poniżej znajdziesz przykładową odpowiedź, która zawiera próbkowane dane z żądania z 2 zakresami dat. Wyniki zostały obliczone na podstawie prawie 500 tys. próbek z przestrzeni próbek o rozmiarze około 15 milionów sesji:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Podział na strony
Interfejs Analytics Reporting API w wersji 4 używa pól pageToken
i pageSize
do podziału na strony wyników odpowiedzi, które obejmują wiele stron. Otrzymasz pageToken
z parametru nextPageToken
w odpowiedzi na żądanie reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Następny krok
Skoro znasz już podstawy tworzenia raportu, przyjrzyj się zaawansowanym funkcjom interfejsu API w wersji 4.