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 poprzez zmianę porządku wyświetlania informacji w tabeli przez przestawienie (obrócenie) danych do jednego lub kilku wymiarów.
Weźmy na przykład tę tabelę z danymi pierwotnymi:
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 omawia funkcje 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 zaawansowane przypadki użycia.
Metody raportowania przestawnego
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 punkt zwrotny 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.
Wybieranie podmiotu raportującego
Wszystkie metody interfejsu Data API w wersji 1 wymagają podania identyfikatora usługi w Google Analytics w ścieżce żądania URL w formie properties/GA_PROPERTY_ID, np.:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Raport zostanie wygenerowany na podstawie danych o zdarzeniach w 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.
Żądanie raportu przestawnego
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ł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 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 przestawień,o ile iloczyn parametru limit dla każdego przestawienia nie przekracza 100 000.
Poniżej znajdziesz fragment kodu pokazujący, jak za pomocą funkcji 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. Wymiar city wskazuje np. 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. Wymiarów można używać wyłącznie w filtrach, a nie w fieldNames żadnej tabeli przestawnej.
Poniżej znajduje się fragment kodu pokazujący użycie pól dimension i fieldNames w tabeli z tabelami przestawnymi 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 wskaźników interfejsu API, które można określić w żądaniach, znajdziesz w sekcji Wskaźniki interfejsu API.
W przypadku zapytań o raporty przestawne dane są definiowane za pomocą pola metrics w treści żądania, co jest podobne do metod raportowania podstawowego.
W przykładzie poniżej 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żej znajdziesz fragment zapytania, które zawiera prośbę o podanie łącznych wartości 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 paginacji.
Ustawienia podziału na strony są stosowane do każdego elementu przestawnego osobno.
Pole limit jest wymagane w przypadku każdego obiektu Pivot, aby ograniczyć kardynalność raportu.
Interfejs Data API w wersji 1 obsługuje wiele tabel przestawnych,o ile iloczyn parametru limit dla każdej tabeli nie przekracza 100 000.
Poniżej znajdziesz fragment kodu, który 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 podstawowych funkcji raportowania, w przypadku żądania raportu przestawnego, w którym ma być używane filtrowanie wymiarów, należy zastosować filtr wymiarów ograniczony do żądania.
Sortowanie
Kolejność zapytań w raporcie przestawnym można kontrolować dla 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 interfejsu API raportu przestawnego składa się głównie z nagłówka i wierszy.
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 tabeli przestawnej 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"
}
],
...
}
Wykres poniżej ilustruje rolę poszczególnych komponentów odpowiedzi Pivot Report Response 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.
Poniżej znajduje się 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 tabeli poniżej:
Biblioteki klienta
W krótkim przewodniku znajdziesz wyjaśnienie, jak zainstalować i skonfigurować biblioteki klienta.
W tym przykładzie biblioteka klienta służy 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 w wersji demonstracyjnej
Przykład tworzenia i wyświetlania raportu przestawnego za pomocą JavaScriptu znajdziesz w aplikacji demonstracyjnej interfejsu Google Analytics API w wersji 1 do raportów przestawnych.