Interfejs Google Analytics Data API w wersji 1 umożliwia generowanie tabel przestawnych. Tabele przestawne to narzędzie do podsumowywania danych, które wizualizuje dane przez ich ułożenie w jednym lub wielu wymiarach przez ich przestawianie.
Przyjrzyjmy się przykładowej tabeli nieprzetworzonych danych:
Na podstawie tych danych można utworzyć tabelę przestawną, która dzieli dane dotyczące sesji według przeglądarki, a wymiary kraju i języka wybrano jako dodatkowe dane.
Wspólne funkcje w podstawowych raportach
Żądania raportowania przestawnego mają tę samą semantykę co żądania raportu podstawowego dotyczące wielu udostępnionych funkcji. Na przykład podział na strony, filtry wymiarów i właściwości użytkownika – w raportach przestawnych działa tak samo jak w raportach podstawowych. Ten przewodnik dotyczy funkcji raportowania przestawnego. Aby zapoznać się z podstawowymi funkcjami raportowania interfejsu Data API w wersji 1, przeczytaj przewodnik po podstawach raportowania oraz przewodnik po zaawansowanych przypadkach użycia.
Przestaw metody raportowania
Interfejs Data API w wersji 1 obsługuje funkcję przestawiania w tych metodach raportowania:
runPivotReport – ta metoda zwraca niestandardowy raport przestawny zawierający dane zdarzeń z Google Analytics. Każdy z tabel przestawnych opisuje widoczne kolumny wymiarów i wiersze w odpowiedzi raportu.
batchRunPivotReports To jest wersja zbiorcza metody
runPivotReport, która umożliwia generowanie wielu raportów za pomocą jednego wywołania interfejsu API.
Wybór podmiotu raportującego
Wszystkie metody interfejsu Data API w wersji 1 wymagają określenia identyfikatora usługi Google Analytics 4 w ścieżce żądania adresu URL w postaci properties/GA4_PROPERTY_ID, np.:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Gotowy raport zostanie wygenerowany na podstawie danych o zdarzeniach w Google Analytics zebranych w określonej usłudze w Google Analytics 4.
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.
Żądanie raportu przestawnego
Aby utworzyć żądanie przy użyciu tabeli przestawnej, użyj metody runPivotReport lub batchRunPivotReports.
Aby wysłać żądanie przestawienia danych, możesz utworzyć obiekt RunPivotReportRequest. Zalecamy zacząć od następujących parametrów żądania:
- Prawidłowa wartość w polu dateRanges.
- Co najmniej 1 prawidłowy wpis w polu wymiary.
- Co najmniej jeden prawidłowy wpis w polu metrics.
- Co najmniej 2 prawidłowe wpisy przestawne w polu przestawny.
Oto przykładowe żądanie z zalecanymi polami:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Przestawienia
Aby zdefiniować tabele przestawne w raporcie, użyj obiektów tabeli przestawnej w polu pivot treści żądania. Każdy Pivot opisuje kolumny i wiersze widocznych wymiarów w odpowiedzi raportu.
Interfejs Data API w wersji 1 obsługuje wiele przestawień,o ile iloczyn parametru limit dla każdej z nich nie przekracza 100 000.
Poniżej znajdziesz fragment kodu ilustrujący użycie parametru pivots do tworzenia raportu o liczbie sesji według kraju z przestawionym według wymiaru browser. Zwróć uwagę, jak zapytanie wykorzystuje pole orderBys do sortowania oraz pola limit i offset do zaimplementowania podziału na strony.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Wymiary
Wymiary opisują i grupują dane zdarzeń dotyczące Twojej witryny lub aplikacji. Na przykład wymiar city wskazuje miasto („Paryż” lub „Nowy Jork”), z którego pochodzą poszczególne zdarzenia. W żądaniu raportu możesz określić zero lub więcej wymiarów.
Wymiary muszą być zdefiniowane w polu wymiarów w treści żądania. Aby wymiary te były widoczne w raporcie, muszą też być wymienione w polu fieldNames obiektu Pivot.
Wymiar nie będzie widoczny w raporcie, jeśli nie jest używany w żadnym punkcie przestawnym w zapytaniu przestawnym. Element fieldNames tabeli przestawnej nie musi zawierać wszystkich wymiarów. Wymiarów można używać wyłącznie w filtrach, a nie w funkcji fieldNames żadnej tabeli przestawnej.
Poniżej znajdziesz fragment kodu ilustrujący użycie pól dimension i fieldNames do użycia w tabeli z przestawieniami browser, country i language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Wskaźniki
Dane to ilościowe pomiary danych zdarzeń dotyczących witryny lub aplikacji. W żądaniu raportu możesz określić co najmniej 1 rodzaj danych. Pełną listę nazw wskaźników interfejsu API, które można określić w żądaniach, znajdziesz w sekcji Wskaźniki interfejsu API.
W żądaniach raportu przestawnego dane są definiowane za pomocą pola metrics w treści żądania, co jest podobne do podstawowych metod raportowania.
Przykład poniżej określa liczbę sesji, która zostanie użyta jako wartość danych w raporcie:
"metrics": [
{
"name": "sessions"
}
],
Agregacje wskaźników
Użyj pola metricAggregations obiektu Pivot do obliczenia zbiorczych wartości danych dla każdej tabeli przestawnej.
Agregacje będą obliczane tylko wtedy, gdy w żądaniu będzie określone pole metricAggregations.
Poniżej znajdziesz fragment zapytania, które prosi o wartości łączne dla wymiaru browser w tabeli przestawnej:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Obliczone dane są zwracane w polu aggregates obiektu RunPivotReportResponse. W wierszach danych zbiorczych pole dimensionValues zawiera specjalną wartość RESERVED_TOTAL, RESERVED_MAX lub RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Podział na strony
Podobnie jak w przypadku podstawowych metod raportowania, żądania przestawne umożliwiają określenie pól limitu i offset w obiekcie Pivot (tabela przestawna) w celu zaimplementowania podziału na strony.
Ustawienia podziału na strony są stosowane do każdej tabeli przestawnej oddzielnie.
Aby ograniczyć moc zbioru raportu, wymagane jest pole limit w przypadku każdego obiektu Pivot.
Interfejs Data API w wersji 1 obsługuje wiele przestawień,o ile iloczyn parametru limit dla każdej z nich nie przekracza 100 tys.
Poniżej znajdziesz fragment kodu ilustrujący użycie pól offset i limit do pobrania kolejnych 5 wymiarów language z przesunięciem równym 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtrowanie
Podobnie jak w przypadku podstawowej funkcji raportowania, jeśli chcesz filtrować wymiary w żądaniu raportu przestawnego, musisz użyć filtra wymiaru o zakresie żądania.
Sortowanie
Kolejność zapytań o raport przestawny można kontrolować w przypadku każdej tabeli przestawnej oddzielnie za pomocą pola orderBys obiektu Pivot, który zawiera listę obiektów OrderBy.
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 wskaźnika.
- Parametr PivotOrderBy jest używany w zapytaniach przestawnych i sortuje wyniki według wartości danych w grupie kolumn przestawnych.
Ten przykład pokazuje fragment definicji tabeli przestawnej, która przestawia raport według wymiaru browser, porządkując wyniki według danych sessions w kolejności malejącej.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Zgłoś odpowiedź
Odpowiedź raportu przestawnego na żądanie API raportu przestawnego to głównie nagłówek i wiersze.
Nagłówki odpowiedzi
Nagłówek raportu przestawnego składa się z kolumn PivotHeaders, DimensionHeaders i MetricHeaders, które zawierają listę kolumn w raporcie przestawnym.
Na przykład raport z wymiarami przestawnymi browser, country, language i danymi sessions będzie generował nagłówki podobne do tych:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
Poniższy wykres przedstawia rolę poszczególnych komponentów odpowiedzi na raport przestawny w renderowaniu raportu przestawnego:
Wiersze odpowiedzi
Odpowiedź raportu przestawnego w przypadku metod runPivotReport i batchRunPivotReports różni się od odpowiedzi w przypadku podstawowych metod raportowania, takich jak runReport i batchRunReports, tym, że każdy wiersz odpowiedzi w raporcie przestawnym odpowiada jednej komórce tabeli, a w raporcie standardowym pojedynczy wiersz odpowiedzi odpowiada pełnej linii tabeli.
Poniżej znajdziesz fragment odpowiedzi w raporcie przestawnym na zapytanie z wymiarami browser, country i language oraz danymi sessions. Każda komórka raportu przestawnego jest zwracana oddzielnie:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Te dane odpowiadają 2 komórkom wyróżnionym w tabeli poniżej:
Biblioteki klienta
Wyjaśnienie sposobu instalowania i konfigurowania bibliotek klienta znajdziesz w krótkim przewodniku dla początkujących.
Poniżej znajduje się przykład użycia biblioteki klienta w Pythonie, która uruchamia zapytanie przestawne w celu utworzenia raportu o liczbie sesji według kraju, przestawionej według wymiaru przeglądarki.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
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_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Aplikacja w wersji demonstracyjnej
Przykład tworzenia i wyświetlania raportu przestawnego za pomocą JavaScriptu znajdziesz w aplikacji demonstracyjnej Google Analytics API v1.