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 przez przestawienie (obrócenie) danych do 1 lub kilku wymiarów.
Weźmy na przykład tę tabelę z nieprzetworzonymi danymi:
Na podstawie tych danych można utworzyć tabelę przestawną, w której dane o sesjach są podzielone według przeglądarki, a jako dodatkowe tabele przestawne wybrano wymiary kraj i język.
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 paginacja, 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 w formie tabeli przestawnej. 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ę przestawiania w tych metodach raportowania:
runPivotReport Zwraca ona niestandardowy raport przestawny zawierający dane zdarzeń z Google Analytics. Każdy element pivot opisuje widoczne kolumny i wiersze wymiarów 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.
Wybierz podmiot raportujący
Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania URL w formacie properties/GA_PROPERTY_ID, np.:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Wynikowy 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 modyfikować ścieżki adresu URL żądania. Większość klientów interfejsu API udostępnia parametr property, który oczekuje ciągu w formie properties/GA_PROPERTY_ID. Przykłady użycia bibliotek klienta znajdziesz w przewodniku dla początkujących.
Prośba o raport przestawny
Aby utworzyć żądanie z tabelą przestawną, użyj metody runPivotReport lub batchRunPivotReports.
Aby poprosić o dane przekształcone, możesz utworzyć obiekt RunPivotReportRequest. Zalecamy rozpoczęcie od tych parametrów żądania:
- Prawidłowa wartość 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 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
Użyj obiektów Pivot w polu pivot treści żądania, aby zdefiniować tabele przestawne raportu. Każdy element 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 tys.
Poniższy fragment kodu pokazuje, jak za pomocą pivots utworzyć raport liczby 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 o zdarzeniach 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 podać co najmniej 1 wymiar.
Wymiary muszą być zdefiniowane w polu dimensions w treści żądania. Aby 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 fieldNames tabeli przestawnej. Wymiary można stosować wyłącznie w filtrach, a nie w fieldNames żadnej tabeli przestawnej.
Ten fragment kodu pokazuje użycie pól dimension i fieldNames w tabeli z pivotami 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 o zdarzeniach w Twojej 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 określić w żądaniach, znajdziesz w sekcji Dane interfejsu API.
W przypadku żądań raportów przestawnych dane są definiowane za pomocą pola metrics w treści żądania, co jest podobne do metod raportowania podstawowego.
W tym przykładzie określono, że w raporcie jako wartość danych 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żdego przestawienia.
Agregacje będą obliczane tylko wtedy, gdy w żądaniu zostanie określone pole metricAggregations.
Poniższy przykład to fragment zapytania, które prosi o sumy dla wymiaru przestawnego browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Obliczone dane są zwracane w polu aggregates obiektu RunPivotReportResponse. W przypadku wierszy zagregowanych danych 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 tabeli przestawnej umożliwiają określenie pól limit i offset w obiekcie Pivot w celu wdrożenia stronicowania.
Ustawienia paginacji są stosowane do każdego widoku przestawnego 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, aby pobrać kolejne 5 wymiarów language z przesunięciem wynoszącym 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtrowanie
Podobnie jak w przypadku podstawowej funkcji raportowania, w żądaniu raportu przestawnego musisz użyć filtra wymiarów ograniczonego do żądania, jeśli chcesz filtrować wymiary.
Sortowanie
Zachowanie zapytań dotyczących raportów przestawnych można kontrolować w przypadku każdego przestawienia z osobna za pomocą pola orderBys obiektu Pivot, które zawiera listę obiektów OrderBy.
Każdy element OrderBy może zawierać jedną z tych wartości:
- DimensionOrderBy sortuje wyniki według wartości wymiaru.
- MetricOrderBy 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 na podstawie 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 do interfejsu API raportu przestawnego zawiera głównie nagłówek i wiersze.
Nagłówki odpowiedzi
Nagłówek raportu przestawnego składa się z elementów 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ł nagłówki w tym stylu:
{
"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 ilustruje rolę poszczególnych komponentów odpowiedzi Pivot Report w renderowaniu raportu przestawnego:
Wiersze odpowiedzi
Odpowiedź raportu przestawnego metod runPivotReport i batchRunPivotReports różni się od odpowiedzi metod raportowania podstawowego, takich jak runReport i batchRunReports, tym, że każdy wiersz odpowiedzi raportu przestawnego reprezentuje pojedynczą komórkę tabeli, podczas gdy w zwykłym raporcie pojedynczy wiersz odpowiedzi reprezentuje pełny wiersz tabeli.
Ten przykład pokazuje fragment odpowiedzi raportu przestawnego dla zapytania 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
Więcej informacji o instalowaniu i konfigurowaniu bibliotek klienta znajdziesz w krótkim przewodniku.
W przykładach poniżej używamy biblioteki klienta do uruchomienia zapytania przestawnego, aby utworzyć raport liczby 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 przestawnego za pomocą JavaScriptu znajdziesz w aplikacji demonstracyjnej raportu przestawnego interfejsu Google Analytics API w wersji 1.