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.
W podanych niżej przykładach wykorzystamy bibliotekę klienta do uruchomienia zapytania przestawnego w celu utworzenia raportu o liczbie sesji według kraju, przestawionej według wymiaru przeglądarki.
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $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, 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)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = 'YOUR-GA4-PROPERTY-ID'; // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require('@google-analytics/data'); // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, 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', }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log('Report result:'); response.rows.forEach(row => { row.dimensionValues.forEach(dimensionValue => { console.log(dimensionValue.value); }); row.metricValues.forEach(metricValue => { console.log(metricValue.value); }); }); }
Aplikacja w wersji demonstracyjnej
Przykład tworzenia i wyświetlania raportu przestawnego za pomocą JavaScriptu znajdziesz w aplikacji demonstracyjnej Google Analytics API v1.