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 zmianę porządku wyświetlania informacji w tabeli, przestawiając (obracając) dane w jednym lub kilku wymiarach.
Rozważmy na przykład tę tabelę nieprzetworzonych danych:
Na podstawie tych danych można utworzyć tabelę przestawną, w której dane o sesjach są podzielone według przeglądarki, a wymiary kraju i języka są wybrane jako dodatkowe przestawienia.
Funkcje wspólne z raportami podstawowymi
Żądania raportów przestawnych mają taką samą semantykę jak żądania raportów podstawowych w przypadku wielu wspólnych funkcji. Na przykład podział na strony, filtry wymiarów i właściwości użytkownika działają w raportach przestawnych 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.
Metody raportowania przestawnego
Interfejs Data API w wersji 1 obsługuje funkcję tabeli przestawnej w tych metodach raportowania:
runPivotReport Ta metoda zwraca niestandardowy raport tabeli przestawnej zawierający dane zdarzeń z Google Analytics. Każda tabela przestawna opisuje widoczne kolumny i wiersze wymiarów w odpowiedzi raportu.
batchRunPivotReports To jest wersja wsadowa metody
runPivotReport, która umożliwia generowanie wielu raportów za pomocą jednego wywołania interfejsu API.
Wybierz podmiot raportujący
Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania adresu URL w formacie properties/GA_PROPERTY_ID, np.:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Raport zostanie wygenerowany na podstawie danych zdarzeń Google Analytics zebranych w określonej usłudze w Google Analytics.
Jeśli używasz jednej z bibliotek klienta interfejsu Data API, nie musisz ręcznie manipulować ścieżką adresu URL żądania. Większość klientów interfejsu API udostępnia parametr property, który oczekuje ciągu znaków w formacie properties/GA_PROPERTY_ID. Przykłady użycia bibliotek klienta znajdziesz w krótkim przewodniku.
Żądanie raportu przestawnego
Aby utworzyć żądanie z tabelą przestawną, użyj metody runPivotReport lub batchRunPivotReports.
Aby poprosić o dane przestawione, możesz utworzyć obiekt RunPivotReportRequest. Na początek zalecamy użycie tych parametrów żądania:
- prawidłowy wpis w polu dateRanges,
- Co najmniej 1 prawidłowy wpis w polu dimensions.
- Co najmniej 1 prawidłowy wpis w polu metrics.
- Co najmniej 2 prawidłowe wpisy przestawne w polu pivots.
Oto przykładowe żądanie z zalecanymi polami:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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ć przestawienia raportu, użyj obiektów Pivot w polu pivot treści żądania. Każdy obiekt Pivot opisuje widoczne kolumny i wiersze wymiarów w odpowiedzi raportu.
Interfejs Data API w wersji 1 obsługuje wiele tabel przestawnych,o ile iloczyn parametru limit dla każdej tabeli przestawnej nie przekracza 100 000.
Poniższy fragment kodu pokazuje, jak za pomocą pivots utworzyć raport z liczbą sesji według kraju, przestawiony według wymiaru browser. Zwróć uwagę, jak zapytanie używa pola orderBys do sortowania oraz pól limit i offset do implementacji stronicowania.
"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ń w Twojej witrynie lub aplikacji. Na przykład wymiar city wskazuje miasto („Paryż” lub „Nowy Jork”), z którego pochodzi każde zdarzenie. W żądaniu raportu możesz określić co najmniej 1 wymiar.
Wymiary muszą być zdefiniowane w polu dimensions treści żądania. Aby te wymiary były widoczne w raporcie, muszą być też wymienione w polu fieldNames obiektu Pivot.
Wymiar nie będzie widoczny w raporcie, jeśli nie jest używany w żadnym przestawieniu zapytania przestawnego. Nie każdy wymiar musi być obecny w tabeli przestawnej fieldNames. Wymiary mogą być używane wyłącznie w filtrach, a nie w fieldNames żadnej tabeli przestawnej.
Ten fragment kodu pokazuje użycie pól dimension i fieldNames w przypadku 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
}
],
Dane
Dane to ilościowe pomiary danych zdarzeń w witrynie lub aplikacji. W żądaniu raportu możesz określić co najmniej 1 rodzaj danych. Pełną listę nazw danych interfejsu API, które można podawać w żądaniach, znajdziesz w artykule Dane interfejsu API.
W żądaniach raportów przestawnych dane są definiowane za pomocą pola metrics w treści żądania, co jest podobne do metod Core Reporting.
W tym przykładzie określono, że jako wartość danych w raporcie ma być używana liczba sesji:
"metrics": [
{
"name": "sessions"
}
],
Agregacje wskaźników
Użyj pola metricAggregations obiektu Pivot, aby obliczyć zagregowane wartości danych dla każdej tabeli przestawnej.
Agregacje będą obliczane tylko wtedy, gdy w żądaniu określono pole metricAggregations.
Poniższy przykład to fragment zapytania, które żąda sum dla wymiaru przestawnego browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Obliczone dane są zwracane w polu aggregates obiektu RunPivotReportResponse. W przypadku wierszy 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 metod raportowania podstawowego żądania przestawne umożliwiają określenie pól limit i offset w obiekcie Pivot w celu wdrożenia podziału na strony.
Ustawienia podziału na strony są stosowane do każdej tabeli przestawnej osobno.
Pole limit jest wymagane w przypadku każdego obiektu Pivot, aby ograniczyć moc zbioru raportu.
Interfejs Data API w wersji 1 obsługuje wiele tabel przestawnych,o ile iloczyn parametru limit dla każdej tabeli przestawnej nie przekracza 100 000.
Ten fragment kodu pokazuje, jak używać pól offset i limit do pobierania kolejnych 5 wymiarów language z przesunięciem 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtrowanie
Podobnie jak w przypadku funkcji raportowania podstawowego, jeśli chcesz filtrować wymiary w żądaniu raportowania tabeli przestawnej, musisz użyć filtra wymiarów o zakresie żądania.
Sortowanie
Sposób sortowania zapytań raportu tabeli przestawnej można kontrolować dla każdej tabeli przestawnej osobno za pomocą pola orderBys obiektu Pivot, które 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, który sortuje wyniki według wartości danych.
- PivotOrderBy, używany w zapytaniach przestawnych, 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ź na żądanie raportu przestawnego w interfejsie API składa się głównie z nagłówka i wierszy.
Nagłówki odpowiedzi
Nagłówek raportu przestawnego składa się z PivotHeaders, DimensionHeaders i MetricHeaders, które zawierają listę kolumn w raporcie przestawnym.
Na przykład raport z wymiarami przestawnymi browser, country i language oraz danymi sessions będzie miał takie nagłówki:
{
"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 raportu przestawnego w renderowaniu raportu przestawnego:
Wiersze odpowiedzi
Odpowiedź raportu tabeli przestawnej metod runPivotReport i batchRunPivotReports różni się od odpowiedzi metod raportowania podstawowego, takich jak runReport i batchRunReports, tym, że każdy wiersz odpowiedzi raportu tabeli przestawnej reprezentuje pojedynczą komórkę tabeli, podczas gdy w zwykłym raporcie pojedynczy wiersz odpowiedzi reprezentuje cały wiersz tabeli.
Poniższy przykład pokazuje fragment odpowiedzi raportu przestawnego na zapytanie z wymiarami przestawnymi browser, country i language oraz danymi sessions. Każda komórka raportu przestawnego jest zwracana osobno:
"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 tej tabeli:
Biblioteki klienta
W krótkim przewodniku znajdziesz informacje o tym, jak zainstalować i skonfigurować biblioteki klienta.
W poniższych przykładach używamy biblioteki klienta do uruchomienia zapytania przestawnego, aby utworzyć raport z liczbą sesji według kraju, przestawiony 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 demonstracyjna
Przykład tworzenia i wyświetlania raportu tabeli przestawnej za pomocą JavaScriptu znajdziesz w aplikacji demonstracyjnej raportu tabeli przestawnej interfejsu Google Analytics API w wersji 1.