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, zmieniając porządek wyświetlania informacji w tabeli poprzez przestawienie (obrócenie) danych do jednego lub kilku wymiarów.
Przeanalizujmy na przykład tę tabelę z surowymi danymi:
Na podstawie tych danych można utworzyć tabelę przestawną, dzieląc dane sesji według przeglądarki, a jako dodatkowe przestawienia wybierając 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 funkcji wspólnych. 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 koncentruje się na funkcjach raportów przestawnych. Aby zapoznać się z funkcjami raportowania podstawowego w interfejsie Data API w wersji 1, przeczytaj przewodnik Podstawy raportowania, a także przewodnik Zaawansowane przypadki użycia.
Metody raportowania przestawnego
Interfejs Data API w wersji 1 obsługuje funkcje przestawne w tych metodach raportowania:
runPivotReport Ta metoda zwraca niestandardowy raport przestawny zawierający dane zdarzeń z Google Analytics. Każde przestawienie opisuje widoczne kolumny i wiersze wymiarów w odpowiedzi raportu.
batchRunPivotReports Jest to wersja zbiorcza metody
runPivotReport, która umożliwia generowanie wielu raportów za pomocą jednego wywołania interfejsu API.
Wybieranie jednostki raportowania
Wszystkie metody interfejsu Data API w wersji 1 wymagają podania
identyfikatora usługi Google Analytics w
ścieżce URL żądania w postaci 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 URL żądania. Większość klientów interfejsu API udostępnia parametr property, który oczekuje ciągu znaków w postaci 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 metody batchRunPivotReports.
Aby poprosić o dane przestawne, 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 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 przestawień,o ile iloczyn parametru limit dla każdego przestawienia nie przekracza 100 tys.
Ten fragment kodu pokazuje, jak używać pola pivots do tworzenia raportu liczby sesji według kraju, przestawionego według wymiaru browser. Zwróć uwagę, że zapytanie używa pola orderBys
do sortowania oraz pól limit
i offset do implementowania
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ń 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ć 0 lub więcej wymiarów.
Wymiary muszą być zdefiniowane w polu
dimensions
treści żądania. Aby 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 przestawieniu zapytania przestawnego. Nie każdy wymiar musi być obecny w polu fieldNames przestawienia. Wymiary mogą być używane wyłącznie w filtrach, a nie w polu fieldNames żadnego przestawienia.
Ten fragment kodu pokazuje, jak używać pól dimension i fieldNames 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
}
],
Dane
Dane to ilościowe pomiary danych zdarzeń w Twojej witrynie lub aplikacji. W żądaniu raportu możesz określić 1 lub więcej danych. Pełną listę nazw danych interfejsu API, które można określić w żądaniach, znajdziesz w artykule Dane interfejsu API.
W żądaniach raportów przestawnych dane są definiowane za pomocą pola metrics treści
żądania, podobnie jak w przypadku metod raportowania podstawowego.
Ten przykład pokazuje, jak określić liczbę sesji, która ma być używana jako wartość danych w raporcie:
"metrics": [
{
"name": "sessions"
}
],
Agregacje danych
Aby obliczyć zagregowane wartości danych dla każdego przestawienia, użyj pola metricAggregations obiektu Pivot.
Agregacje będą obliczane tylko wtedy, gdy w żądaniu zostanie określone pole metricAggregations.
Ten 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 przestawne umożliwiają określenie pól limit i offset w obiekcie Pivot w celu implementowania podziału na strony.
Ustawienia podziału na strony są stosowane do każdego przestawienia osobno.
Pole limit jest wymagane w przypadku każdego obiektu Pivot, aby ograniczyć kardynalność raportu.
Interfejs Data API w wersji 1 obsługuje wiele przestawień,o ile iloczyn parametru limit dla każdego przestawienia nie przekracza 100 tys.
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 przestawnego, musisz użyć filtra wymiarów o zakresie żądania.
Sortowanie
Zachowanie związane z kolejnością zapytań raportów przestawnych można kontrolować dla każdego przestawienia osobno za pomocą pola orderBys obiektu Pivot, które zawiera listę OrderBy.
Każdy obiekt OrderBy może zawierać jedną z tych opcji:
- DimensionOrderBy – sortuje wyniki według wartości wymiaru.
- MetricOrderBy – sortuje wyniki według wartości danych.
- PivotOrderBy – używany w zapytaniach przestawnych i sortuje wyniki według wartości danych w grupie kolumn przestawnych.
Ten przykład pokazuje fragment definicji przestawienia, który przestawia raport według wymiaru browser, sortując wyniki według danych sessions w kolejności malejącej.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Odpowiedź raportu
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 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"
}
],
...
}
Ten wykres ilustruje rolę poszczególnych komponentów odpowiedzi raportu przestawnego w renderowaniu raportu przestawnego:
Wiersze odpowiedzi
Odpowiedź raportu przestawnego na metody runPivotReport i batchRunPivotReports różni się od odpowiedzi na metody raportowania podstawowego takie jak runReport i batchRunReports tym, że każdy wiersz odpowiedzi raportu przestawnego reprezentuje pojedynczą komórkę tabeli, natomiast w zwykłym raporcie pojedynczy wiersz odpowiedzi reprezentuje cały wiersz tabeli.
Ten 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
Informacje o instalowaniu i konfigurowaniu bibliotek klienta znajdziesz w krótkim przewodniku.
Te przykłady pokazują, jak używać biblioteki klienta do uruchamiania zapytania przestawnego w celu utworzenia raportu liczby sesji według kraju, przestawionego 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.