Mit der Google Analytics Data API v1 können Sie Pivot-Tabellen erstellen. Pivot-Tabellen sind ein Tool zur Datenzusammenfassung, mit dem Daten visualisiert werden können. Dazu werden die Informationen in der Tabelle neu angeordnet, indem die Daten anhand einer oder mehrerer Dimensionen pivotiert (gedreht) werden.
Betrachten Sie als Beispiel die folgende Tabelle mit Rohdaten:
Anhand dieser Daten kann eine Pivot-Tabelle erstellt werden, in der die Sitzungsdaten nach Browser aufgeschlüsselt sind. Die Dimensionen „Land“ und „Sprache“ werden als zusätzliche Pivots ausgewählt.
Gemeinsame Funktionen mit Standardberichten
Pivot-Berichtsanfragen haben für viele gemeinsame Funktionen dieselbe Semantik wie Standardberichtsanfragen. So verhalten sich beispielsweise die Paginierung, Dimensionsfilter und Nutzerattribute in Pivot-Berichten genauso wie in Standardberichten. In diesem Leitfaden werden die Funktionen für Pivot-Berichte behandelt. Wenn Sie sich mit den Standardberichtsfunktionen der Data API v1 vertraut machen möchten, lesen Sie den Leitfaden zu den Grundlagen der Berichterstellung, sowie den Leitfaden zu erweiterten Anwendungsfällen.
Methoden für Pivot-Berichte
Die Data API v1 unterstützt die Pivot-Funktionalität in den folgenden Berichtsmethoden:
runPivotReport: Mit dieser Methode wird ein benutzerdefinierter Pivot-Bericht Ihrer Google Analytics-Ereignisdaten zurückgegeben. Jeder Pivot beschreibt die sichtbaren Dimensionsspalten und ‑zeilen in der Berichtantwort.
batchRunPivotReports: This is a batch version of the
runPivotReportmethod which allows generating multiple reports using a single API call.
Berichtseinheit auswählen
Für alle Methoden der Data API v1 muss die
Google Analytics-Property-ID in einem
URL-Anfragepfad im Format properties/GA_PROPERTY_ID angegeben werden, z. B.:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Der resultierende Bericht wird anhand der Google Analytics-Ereignisdaten generiert, die in der angegebenen Google Analytics-Property erfasst wurden.
Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den Anfrage-URL-Pfad
nicht manuell bearbeiten. Die meisten API-Clients bieten einen Parameter property, der einen String im Format properties/GA_PROPERTY_ID erwartet. Beispiele für die Verwendung der Clientbibliotheken finden Sie in der Kurzanleitung.
Anfrage für Pivot-Bericht
Wenn Sie eine Anfrage mit einer Pivot-Tabelle erstellen möchten, verwenden Sie entweder die runPivotReport oder die batchRunPivotReports Methode.
Wenn Sie pivotierte Daten anfordern möchten, können Sie ein RunPivotReportRequest Objekt erstellen. Wir empfehlen, mit diesen Anfrageparametern zu beginnen:
- Ein gültiger Eintrag im Feld dateRanges.
- Mindestens ein gültiger Eintrag im Feld dimensions.
- Mindestens ein gültiger Eintrag im Feld metrics.
- Mindestens zwei gültige Pivot-Einträge im Feld pivots.
Hier ist ein Beispiel für eine Anfrage mit den empfohlenen Feldern:
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
}
]
}
Pivot-Tabellen
Verwenden Sie Pivot-Objekte im Feld pivot des Anfragetexts
, um Berichtspivots zu definieren. Jeder Pivot beschreibt die sichtbaren Dimensionsspalten und ‑zeilen in der Berichtantwort.
Die Data API v1 unterstützt mehrere Pivots,solange das Produkt des Parameters limit für jeden Pivot 100.000 nicht übersteigt.
Das folgende Snippet zeigt die Verwendung von pivots, um einen Bericht mit der Anzahl der Sitzungen nach Land zu erstellen, pivotiert nach der Dimension browser. Beachten Sie, wie in der Abfrage das Feld orderBys zum Sortieren und die Felder limit
und offset zum Implementieren
der Paginierung verwendet werden.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Abmessungen
Dimensionen beschreiben und gruppieren Ereignisdaten für Ihre
Website oder App. Die city Dimension gibt beispielsweise die Stadt an, aus der jedes Ereignis stammt („Berlin“
oder „München“). In einer Berichtsanfrage können Sie null oder mehr Dimensionen angeben.
Dimensionen müssen im
dimensions
Feld eines Anfragetexts definiert werden. Damit sie in einem Bericht sichtbar sind, müssen sie auch
im Feld fieldNames
eines Pivot Objekts aufgeführt sein.
Eine Dimension ist in einem Bericht nicht sichtbar, wenn sie in keinem Pivot einer Pivot-Abfrage verwendet wird. Nicht jede Dimension muss in den fieldNames eines Pivots vorhanden sein. Dimensionen können ausschließlich in Filtern und nicht in den fieldNames eines Pivots verwendet werden.
Das folgende Snippet zeigt die Verwendung der Felder dimension und fieldNames für eine Tabelle mit den Pivots browser, country und language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Messwerte
Messwerte sind quantitative Messungen von Ereignisdaten für Ihre Website oder App. In einer Berichtsanfrage können Sie einen oder mehrere Messwerte angeben. Eine vollständige Liste der API-Messwert namen, die in Anfragen angegeben werden können, finden Sie unter API-Messwerte.
In Pivot-Berichtsanfragen werden Messwerte mit dem Feld metrics des
Anfragetexts definiert, ähnlich wie bei Standardberichtsmethoden.
Im folgenden Beispiel wird die Anzahl der Sitzungen als Messwert in einem Bericht angegeben:
"metrics": [
{
"name": "sessions"
}
],
Messwertaggregationen
Verwenden Sie das metricAggregations Feld eines Pivot-Objekts, um aggregierte Messwerte für jeden Pivot zu berechnen.
Aggregationen werden nur berechnet, wenn das metricAggregations Feld in einer Anfrage angegeben ist.
Das folgende Beispiel ist ein Snippet einer Abfrage, in der die Summen für die Pivot-Dimension browser angefordert werden:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Die berechneten Messwerte werden im Feld aggregates
des Objekts RunPivotReportResponse
zurückgegeben. Für aggregierte Messwertzeilen enthält das Feld dimensionValues einen Sonderwert: RESERVED_TOTAL, RESERVED_MAX oder 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"
}
]
},
....
}
Seitenumbruch
Ähnlich wie bei Standardberichtsmethoden können Sie in Pivot-Anfragen die Felder limit und offset im Pivot-Objekt angeben, um die Paginierung zu implementieren.
Die Paginierungseinstellungen werden auf jeden Pivot einzeln angewendet.
Das Feld limit ist für jedes Pivot-Objekt erforderlich, um die Kardinalität des Berichts zu begrenzen.
Die Data API v1 unterstützt mehrere Pivots,solange das Produkt des Parameters limit für jeden Pivot 100.000 nicht übersteigt.
Das folgende Snippet zeigt die Verwendung der Felder offset und limit, um die nächsten fünf language-Dimensionen mit einem Offset von 10 abzurufen:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtern
Ähnlich wie bei der Standardberichtsfunktion muss ein dimensionsbezogener Filter für die Anfrage verwendet werden, wenn Sie Dimensionen in einer Pivot-Berichtsanfrage filtern möchten.
Sortieren
Das Sortierverhalten von Pivot-Berichtsabfragen kann für jeden Pivot einzeln mit dem orderBys Feld eines Pivot-Objekts gesteuert werden. Dieses Feld enthält eine Liste von OrderBy-Objekten.
Jedes OrderBy-Objekt kann eines der folgenden Objekte enthalten:
- DimensionOrderBy: Sortiert die Ergebnisse nach den Werten einer Dimension.
- MetricOrderBy: Sortiert die Ergebnisse nach den Werten eines Messwerts.
- PivotOrderBy: Wird in Pivot-Abfragen verwendet und sortiert die Ergebnisse nach den Werten eines Messwerts in einer Pivot-Spaltengruppe.
Dieses Beispiel zeigt ein Snippet für eine Pivot-Definition, mit der der Bericht nach der Dimension browser pivotiert wird. Die Ergebnisse werden in absteigender Reihenfolge nach dem Messwert sessions sortiert.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Berichtantwort
Die Pivot-Berichtantwort einer API-Anfrage für einen Pivot Bericht besteht hauptsächlich aus einem Header und Zeilen.
Antwortheader
Der Header des Pivot-Berichts besteht aus PivotHeaders, DimensionHeaders und MetricHeaders, in denen die Spalten im Pivot-Bericht aufgeführt sind.
Ein Bericht mit den Pivot-Dimensionen browser, country und language und dem Messwert sessions würde beispielsweise so aussehen:
{
"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"
}
],
...
}
Das folgende Diagramm veranschaulicht die Rolle der einzelnen Komponenten der Pivot-Berichtantwort beim Rendern des Pivot-Berichts:
Antwortzeilen
Die Pivot-Berichtantwort der Methoden runPivotReport und batchRunPivotReports unterscheidet sich von einer Antwort für Standardberichtsmethoden wie runReport und batchRunReports dadurch, dass jede Zeile der Pivot-Berichtantwort eine einzelne Zelle der Tabelle darstellt. In einem regulären Bericht stellt eine einzelne Antwortzeile eine vollständige Tabellenzeile dar.
Das folgende Beispiel zeigt ein Fragment einer Pivot-Berichtantwort für eine Abfrage mit den Pivot-Dimensionen browser, country und language und dem Messwert sessions. Jede Zelle des Pivot-Berichts wird einzeln zurückgegeben:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Diese Daten entsprechen den beiden Zellen, die in der folgenden Tabelle hervorgehoben sind:
Clientbibliotheken
Eine Anleitung zum Installieren und Konfigurieren von Clientbibliotheken finden Sie in der Kurzanleitung.
In den folgenden Beispielen wird die Clientbibliothek verwendet, um eine Pivot-Abfrage auszuführen und einen Bericht mit der Anzahl der Sitzungen nach Land zu erstellen, pivotiert nach der Dimension „Browser“.
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); }); }); }
Demoanwendung
In der Demoanwendung für Pivot-Berichte der Google Analytics API v1 finden Sie ein Beispiel dafür, wie Sie mit JavaScript einen Pivot-Bericht erstellen und anzeigen.