Mit der Google Analytics Data API v1 können Sie Pivot-Tabellen generieren. Pivot-Tabellen sind ein Tool zur Datenzusammenfassung, mit dem Daten visualisiert werden, indem die Informationen in der Tabelle neu angeordnet werden, indem die Daten in einer oder mehreren Dimensionen gedreht werden.
Betrachten Sie als Beispiel die folgende Tabelle mit Rohdaten:
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 Hauptberichten
Anfragen für Pivot-Berichte haben dieselbe Semantik wie Anfragen für grundlegende Berichte für viele gemeinsame Funktionen. Funktionen wie Paginierung, Dimensionsfilter und Nutzereigenschaften funktionieren in Pivot-Berichten genauso wie in Basisberichten. In diesem Leitfaden geht es hauptsächlich um die Funktionen für Pivot-Berichte. Weitere Informationen zu den grundlegenden Berichtsfunktionen der Data API v1 finden Sie im Leitfaden zu Berichtsgrundlagen und im 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. In jedem Pivot-Diagramm werden die sichtbaren Dimensionsspalten und ‑zeilen in der Berichtsantwort beschrieben.
batchRunPivotReports: Dies ist eine Batchversion 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-Anfragepfad in Form von properties/GA_PROPERTY_ID angegeben werden, z. B.:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Der Bericht wird anhand der Google Analytics-Ereignisdaten erstellt, die in der angegebenen Google Analytics-Property erfasst wurden.
Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den URL-Pfad der Anfrage nicht manuell bearbeiten. Die meisten API-Clients bieten einen property-Parameter an, für den ein String in Form von properties/GA_PROPERTY_ID erwartet wird. In der Kurzanleitung finden Sie Beispiele für die Verwendung der Clientbibliotheken.
Anfrage für Pivot-Bericht
Verwenden Sie zum Erstellen einer Anfrage mit einer Pivot-Tabelle entweder die Methode runPivotReport oder batchRunPivotReports.
Wenn Sie Pivot-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 Dimensionen
- Mindestens ein gültiger Eintrag im Feld Messwerte
- 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
}
]
}
Pivots
Verwenden Sie Pivot-Objekte im Feld pivot des Anfragetexts, um Berichts-Pivots zu definieren. Jede Pivot beschreibt die sichtbaren Dimensionenspalten und ‑zeilen in der Berichtsantwort.
Die Data API v1 unterstützt mehrere Pivot-Tabellen,solange das Produkt des Parameters limit für jede Pivot-Tabelle 100.000 nicht überschreitet.
Im Folgenden finden Sie ein Snippet, das die Verwendung von pivots zum Erstellen eines Berichts mit Sitzungszahlen nach Land zeigt, der anhand der Dimension browser gepivotet ist. Beachten Sie, dass in der Abfrage das Feld orderBys für die Sortierung und die Felder limit und offset für die Paginierung verwendet werden.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Dimensionen
Dimensionen beschreiben und gruppieren Ereignisdaten für Ihre Website oder App. Die Dimension city gibt beispielsweise die Stadt an („Berlin“ oder „München“), von der jedes Ereignis stammt. In einer Berichtsanfrage können Sie null oder mehrere Dimensionen angeben.
Dimensionen müssen im Feld dimensions eines Anfragetexts definiert werden. Damit diese Dimensionen in einem Bericht zu sehen sind, müssen sie auch im Feld fieldNames eines Pivot-Objekts aufgeführt sein.
Eine Dimension ist in einem Bericht nicht zu sehen, wenn sie in keinem Pivot einer Pivot-Abfrage verwendet wird. Nicht jede Dimension muss in der fieldNames eines Pivot-Diagramms vorhanden sein. Dimensionen können ausschließlich in Filtern und nicht in der fieldNames eines Pivot-Diagramms verwendet werden.
Im folgenden Snippet wird die Verwendung der Felder dimension und fieldNames für eine Tabelle mit browser-, country- und language-Pivots veranschaulicht:
"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 über das Feld metrics im Anfragetext definiert. Das entspricht den Methoden für grundlegende Berichte.
Im folgenden Beispiel wird die Anzahl der Sitzungen als Messwert in einem Bericht verwendet:
"metrics": [
{
"name": "sessions"
}
],
Messwertaggregationen
Verwenden Sie das Feld metricAggregations eines Pivot-Objekts, um aggregierte Messwertwerte für jedes Pivot zu berechnen.
Zusammenfassungen werden nur berechnet, wenn das Feld metricAggregations in einer Anfrage angegeben ist.
Unten sehen Sie ein Snippet einer Abfrage, mit 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. Bei aggregierten Messwertzeilen enthält das Feld dimensionValues einen Sonderwert von 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 den Methoden für grundlegende Berichte können Sie mit Pivot-Anfragen die Felder limit und offset im Pivot-Objekt angeben, um die Paginierung zu implementieren.
Die Einstellungen für die Paginierung werden auf jeden Pivot-Bericht 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 limit-Parameters für jeden Pivot nicht mehr als 100.000 beträgt.
Im folgenden Snippet wird die Verwendung von offset- und limit-Feldern 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 den Hauptfunktionen für Berichte muss ein Dimensionenfilter auf Anfrageebene verwendet werden, wenn in einer Anfrage für Pivot-Berichte nach Dimensionen gefiltert werden soll.
Sortieren
Das Sortierungsverhalten 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:
- DimensionOrderBy: Die Ergebnisse werden nach den Werten einer Dimension sortiert.
- MetricOrderBy: Sortiert die Ergebnisse nach den Werten eines Messwerts.
- PivotOrderBy: Wird in Pivot-Abfragen verwendet und sortiert Ergebnisse nach den Werten eines Messwerts innerhalb einer Pivot-Spaltengruppe.
In diesem Beispiel wird ein Snippet für eine Pivot-Definition gezeigt, bei der der Bericht um die Dimension browser gedreht und die Ergebnisse in absteigender Reihenfolge nach dem Messwert sessions sortiert werden.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Antwort melden
Die Pivot-Berichtsantwort 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.
In einem Bericht mit den Pivot-Dimensionen browser, country und language und dem Messwert sessions werden beispielsweise folgende Überschriften angezeigt:
{
"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 Antwort für Pivot-Berichte der Methoden runPivotReport und batchRunPivotReports unterscheidet sich von der Antwort für Methoden der grundlegenden Berichterstellung wie runReport und batchRunReports dadurch, dass jede Zeile der Antwort für Pivot-Berichte eine einzelne Zelle der Tabelle darstellt, während in einem normalen Bericht eine einzelne Antwortzeile eine vollständige Tabellenzeile darstellt.
Unten sehen Sie ein Fragment einer Antwort für einen Pivot-Bericht 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
In der Schnellstartanleitung wird erläutert, wie Sie Clientbibliotheken installieren und konfigurieren.
In den folgenden Beispielen wird mit der Clientbibliothek eine Pivot-Abfrage ausgeführt, um einen Bericht mit Sitzungszahlen nach Land zu erstellen, der nach der Browserdimension gepivotet ist.
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 einen Pivot-Bericht mit JavaScript erstellen und anzeigen.