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, indem die Informationen in der Tabelle neu angeordnet werden. Dazu werden die Daten anhand einer oder mehrerer Dimensionen gedreht.
Sehen Sie sich als Beispiel die folgende Rohdatentabelle an:
Anhand dieser Daten lässt sich eine Pivot-Tabelle erstellen, in der die Sitzungsdaten nach Browser aufgeschlüsselt werden. Als zusätzliche Pivots werden die Dimensionen „Land“ und „Sprache“ ausgewählt.
Gemeinsame Funktionen mit Core-Berichten
Pivot-Berichtsanfragen haben für viele gemeinsame Funktionen dieselbe Semantik wie Core-Berichtsanfragen. Die Paginierung, Dimensionsfilter und Nutzerattribute funktionieren in Pivot-Berichten genauso wie in Standardberichten. In diesem Leitfaden geht es um Pivot-Berichtsfunktionen. Wenn Sie sich mit den Core Reporting-Funktionen 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-Funktion 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 Antwort des Berichts.
batchRunPivotReports: Dies ist eine Batch-Version der Methode
runPivotReport, mit der mehrere Berichte mit einem einzigen API-Aufruf generiert werden können.
Berichtseinheit auswählen
Für alle Methoden der Data API v1 muss die Google Analytics-Property-ID in einem URL-Anforderungspfad 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 auf Grundlage der Google Analytics-Ereignisdaten erstellt, die in der angegebenen Google Analytics-Property erfasst werden.
Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den Anfrage-URL-Pfad nicht manuell bearbeiten. Die meisten API-Clients bieten einen property-Parameter, der einen String im Format properties/GA_PROPERTY_ID erwartet. Beispiele für die Verwendung der Clientbibliotheken finden Sie im Schnellstart.
Anfrage für Pivot-Bericht
Wenn Sie eine Anfrage mit einer Pivot-Tabelle erstellen möchten, verwenden Sie entweder die Methode runPivotReport oder batchRunPivotReports.
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 eine Beispielanfrage 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. Jedes Pivot beschreibt die sichtbaren Dimensionsspalten und ‑zeilen in der Antwort des Berichts.
Die Data API v1 unterstützt mehrere Pivots,sofern das Produkt des Parameters limit für jeden Pivot 100.000 nicht überschreitet.
Im Folgenden sehen Sie ein Snippet, in dem die Verwendung von pivots zum Erstellen eines Berichts mit Sitzungszahlen nach Land, der nach der Dimension browser aufgeschlüsselt ist, veranschaulicht wird. Beachten Sie, dass 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 Dimension city gibt beispielsweise die Stadt an („Berlin“ oder „München“), in der die einzelnen Ereignisse stattgefunden haben. In einer Berichtsanfrage können Sie null oder mehr Dimensionen angeben.
Dimensionen müssen im Feld dimensions eines Anfragetexts definiert werden. Damit diese Dimensionen 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 der fieldNames eines Pivots vorhanden sein. Dimensionen können ausschließlich in Filtern und nicht in der fieldNames eines Pivots verwendet werden.
Unten sehen Sie ein Snippet, in dem die Verwendung der Felder dimension und fieldNames für eine Tabelle mit den Pivots browser, country und language veranschaulicht wird:
"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-Messwertnamen, die in Anfragen angegeben werden können, finden Sie unter API-Messwerte.
In Anfragen für Pivot-Berichte werden Messwerte mit dem Feld metrics des Anfragetexts definiert. Das ist ähnlich wie bei Core Reporting-Methoden.
Im folgenden Beispiel wird die Anzahl der Sitzungen als Messwert in einem Bericht angegeben:
"metrics": [
{
"name": "sessions"
}
],
Messwertaggregationen
Verwenden Sie das Feld metricAggregations eines Pivot-Objekts, um aggregierte Messwerte für jeden Pivot zu berechnen.
Zusammenfassungen werden nur berechnet, wenn das Feld metricAggregations in einer Anfrage angegeben ist.
Unten sehen Sie einen Ausschnitt einer Abfrage, in der die Summenwerte 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. Bei aggregierten 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 Core Reporting-Methoden können Sie bei Pivot-Anfragen die Felder limit und offset im Objekt Pivot angeben, um die Seitennummerierung zu implementieren.
Die Einstellungen für die Paginierung 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,sofern das Produkt des limit-Parameters für jeden Pivot 100.000 nicht überschreitet.
Unten sehen Sie ein Snippet, das die Verwendung der Felder offset und limit zum Abrufen der nächsten fünf language-Dimensionen mit einem Offset von 10 veranschaulicht:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtern
Ähnlich wie bei der Core Reporting API muss ein Dimensionsfilter mit Anforderungsbereich verwendet werden, wenn das Filtern von Dimensionen in einer Pivot-Berichtsanfrage gewünscht ist.
Sortieren
Das Sortierverhalten von Pivot-Berichtsabfragen kann für jeden Pivot einzeln über das Feld orderBys eines Pivot-Objekts gesteuert werden, das eine Liste von OrderBy-Objekten enthält.
Jedes OrderBy kann eines der folgenden Elemente enthalten:
- Mit DimensionOrderBy werden Ergebnisse nach den Werten einer Dimension sortiert.
- Mit MetricOrderBy werden Ergebnisse nach den Werten eines Messwerts sortiert.
- PivotOrderBy wird in Pivot-Abfragen verwendet und sortiert Ergebnisse nach den Werten einer Messwertspalte innerhalb einer Pivot-Spaltengruppe.
In diesem Beispiel sehen Sie einen Ausschnitt für eine Pivot-Definition, mit der der Bericht nach der Dimension browser aufgeschlüsselt und die Ergebnisse nach dem Messwert sessions in absteigender Reihenfolge sortiert werden.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Antwort melden
Die Pivot Report Response einer API-Anfrage für einen Pivot-Bericht besteht hauptsächlich aus einem Header und Zeilen.
Antwortheader
Die Kopfzeile des Pivot-Berichts besteht aus PivotHeaders, DimensionHeaders und MetricHeaders, in denen die Spalten des Pivot-Berichts aufgeführt sind.
Ein Bericht mit den Pivot-Dimensionen browser, country und language und dem Messwert sessions hat beispielsweise die folgenden Überschriften:
{
"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-Berichtsantwort beim Rendern des Pivot-Berichts:
Antwortzeilen
Die Pivot-Berichtsantwort der Methoden runPivotReport und batchRunPivotReports unterscheidet sich von einer Antwort für Core Reporting-Methoden wie runReport und batchRunReports, da jede Zeile der Pivot-Berichtsantwort eine einzelne Zelle der Tabelle darstellt, während in einem regulären Bericht eine einzelne Antwortzeile eine vollständige Tabellenzeile darstellt.
Unten sehen Sie einen Ausschnitt aus der Antwort eines Pivot-Berichts für eine Abfrage mit den Pivot-Dimensionen browser, country und language sowie 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 Tabelle unten 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 Sitzungszahlen nach Land zu erstellen, der nach der Browserdimension pivotiert wird.
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 Google Analytics API v1 Pivot Report Demo-Anwendung finden Sie ein Beispiel dafür, wie Sie mit JavaScript einen Pivot-Bericht erstellen und anzeigen.