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 durch Drehen der Daten um eine oder mehrere Dimensionen neu angeordnet werden.
Sehen Sie sich als Beispiel die folgende Rohdatentabelle an:
Anhand dieser Daten kann eine Pivot-Tabelle erstellt werden, in der die Sitzungsdaten nach Browser aufgeschlüsselt sind. Dabei werden die Dimensionen „Land“ und „Sprache“ als zusätzliche Pivots ausgewählt.
Gemeinsame Funktionen mit Core-Berichten
Pivot-Berichtsanfragen haben für viele gemeinsame Funktionen dieselbe Semantik wie Core-Berichtsanfragen. Beispielsweise verhalten sich die Paginierung, Dimensionsfilter und Nutzereigenschaften in Pivot-Berichten genauso wie in Core-Berichten. In diesem Leitfaden geht es um die Funktionen für Pivot-Berichte. Wenn Sie sich mit den grundlegenden Berichtsfunktionen der Data API v1 vertraut machen möchten, lesen Sie den Leitfaden zu den Grundlagen der Berichterstellung und den Leitfaden zu erweiterten Anwendungsfällen.
Pivot-Berichtsmethoden
Die Data API v1 unterstützt die Pivot-Funktion in den folgenden Berichterstellungsmethoden:
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 Berichtsantwort.
batchRunPivotReports: Dies ist eine Batchversion der Methode
runPivotReport, mit der mehrere Berichte über einen einzigen API-Aufruf generiert werden können.
Berichtsentität auswählen
Bei allen 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 Bericht wird auf Grundlage der Google Analytics-Ereignisdaten erstellt, die in der angegebenen Google Analytics-Property erhoben wurden.
Wenn Sie eine der Data API-Clientbibliotheken verwenden, müssen Sie den Anfrage-URL-Pfad nicht manuell bearbeiten. Die meisten API-Clients stellen einen property-Parameter bereit, 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 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 Bericht-Pivots zu definieren. Jedes Pivot beschreibt die sichtbaren Dimensionsspalten und -zeilen in der Berichtsantwort.
Die Data API v1 unterstützt mehrere Pivots,solange das Produkt des Parameters limit für jeden Pivot 100.000 nicht überschreitet.
Das folgende Snippet zeigt, wie Sie mit pivots einen Bericht über die Anzahl der Sitzungen nach Land erstellen, der nach der Dimension browser pivotiert wird. Beachten Sie, wie die Abfrage das Feld orderBys für die Sortierung und die Felder limit und offset für die Implementierung der Paginierung verwendet.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Abmessungen
Mit Dimensionen werden Ereignisdaten für Ihre Website oder App beschrieben und gruppiert. Die Dimension city gibt beispielsweise die Stadt („Paris“ oder „New York“) an, aus der das jeweilige Ereignis stammt. 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 im fieldNames eines Pivots vorhanden sein. Dimensionen können ausschließlich in Filtern und nicht im fieldNames einer Pivot-Tabelle 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-Messwertnamen, 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 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.
Aggregationen werden nur berechnet, wenn das Feld metricAggregations in einer Anfrage angegeben ist.
Das folgende Beispiel ist 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 RunPivotReportResponse-Objekts zurückgegeben. Bei aggregierten Messwertzeilen enthält das Feld dimensionValues den speziellen Wert 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 Core Reporting-Methoden können Sie bei 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 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 überschreitet.
Das folgende Snippet zeigt, wie die Felder offset und limit verwendet werden, 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 Core Reporting-Funktion muss ein anfragebezogener Dimensionsfilter verwendet werden, wenn Sie Dimensionen in einer Pivot-Berichtsanfrage filtern möchten.
Sortieren
Das Sortierverhalten von Pivot-Berichtsabfragen kann für jeden Pivot-Bericht einzeln über das Feld orderBys eines Pivot-Objekts gesteuert werden, das eine Liste von OrderBy-Objekten enthält.
Jeder OrderBy kann eines der folgenden Elemente enthalten:
- DimensionOrderBy: Sortiert die Ergebnisse nach den Werten einer Dimension.
- MetricOrderBy: Die Ergebnisse werden nach den Werten eines Messwerts sortiert.
- PivotOrderBy wird in Pivot-Abfragen verwendet und sortiert die Ergebnisse nach den Werten eines Messwerts innerhalb einer Pivot-Spaltengruppe.
In diesem Beispiel sehen Sie ein Snippet für eine Pivot-Definition, mit der der Bericht nach der Dimension browser pivotiert wird. Die Ergebnisse werden nach dem Messwert sessions in absteigender Reihenfolge sortiert.
{
"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
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 sowie dem Messwert sessions enthält beispielsweise folgende Ü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"
}
],
...
}
In der folgenden Abbildung wird die Rolle der einzelnen Komponenten der Pivot-Berichtsantwort beim Rendern des Pivot-Berichts dargestellt:
Antwortzeilen
Die Antwort des Pivot-Berichts der Methoden runPivotReport und batchRunPivotReports unterscheidet sich von einer Antwort für Core Reporting-Methoden wie runReport und batchRunReports. Jede Antwortzeile des Pivot-Berichts stellt eine einzelne Zelle der Tabelle dar, während in einem regulären Bericht eine einzelne Antwortzeile eine vollständige Tabellenzeile darstellt.
Das folgende Beispiel zeigt ein Fragment einer Pivot-Berichtsantwort 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 hervorgehobenen Zellen in der folgenden Tabelle:
Clientbibliotheken
In der Kurzanleitung finden Sie eine Erklärung zur Installation und Konfiguration von Clientbibliotheken.
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, 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 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.