Mit der Google Analytics Data API Version 1 können Sie Pivot-Tabellen generieren. Pivot-Tabellen sind ein Tool zur Datenzusammenfassung, mit dem die Informationen in der Tabelle durch Drehen (Drehen) einer oder mehrerer Dimensionen neu angeordnet werden.
Betrachten Sie als Beispiel die folgende Rohdatentabelle:
Mit diesen Daten kann eine Pivot-Tabelle erstellt werden, in der die Sitzungsdaten nach Browser aufgeschlüsselt werden. Dabei werden die Dimensionen „Land“ und „Sprache“ als zusätzliche Pivots ausgewählt.
Gemeinsame Funktionen mit Kernberichten
Anfragen für Pivot-Berichte haben für viele gemeinsam genutzte Funktionen dieselbe Semantik wie Anfragen für grundlegende Berichte. Beispielsweise funktionieren Seitenumbrüche, Dimensionsfilter und Nutzereigenschaften in Pivot-Berichten genauso wie grundlegende Berichte. In diesem Leitfaden geht es um Pivot-Berichtsfunktionen. Wenn Sie sich mit den wichtigsten Berichtsfunktionen der Data API Version 1 vertraut machen möchten, sollten Sie den Leitfaden Grundlagen zu Berichten und Erweiterte Anwendungsfälle lesen.
Pivot-Berichtsmethoden
Das Data API v1 unterstützt die Pivot-Funktion in den folgenden Berichtsmethoden:
runPivotReport: Diese Methode gibt einen benutzerdefinierten Pivot-Bericht Ihrer Google Analytics-Ereignisdaten zurück. Jeder Pivot beschreibt die sichtbaren Dimensionsspalten und -zeilen in der Berichtsantwort.
batchRunPivotReports Dies ist eine Batchversion der Methode
runPivotReport, mit der mehrere Berichte mit einem einzigen API-Aufruf generiert werden können.
Eine meldende Entität auswählen
Bei allen Methoden der Data API Version 1 muss die Google Analytics 4-Property-ID in einem URL-Anfragepfad im Format properties/GA4_PROPERTY_ID angegeben werden. Beispiel:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Der Bericht wird anhand der Google Analytics-Ereignisdaten generiert, die in der angegebenen Google Analytics 4-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, der einen String in Form von properties/GA4_PROPERTY_ID erwartet. Beispiele zur Verwendung der Clientbibliotheken finden Sie in der Kurzanleitung.
Pivot-Berichtanforderung
Verwenden Sie zum Erstellen einer Anfrage mit einer Pivot-Tabelle entweder die Methode runPivotReport oder die Methode 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 Dimensionen
- 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/GA4_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. 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.
Mit dem folgenden Snippet wird die Verwendung von pivots zum Erstellen eines Berichts über die Sitzungsanzahl nach Land veranschaulicht, wobei die Dimension browser verwendet wird. In der Abfrage werden das Feld orderBys zum Sortieren und die Felder limit und offset zum Implementieren 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, von der das jeweilige Ereignis stammt. In einer Berichtsanfrage können Sie keine
oder mehrere Dimensionen angeben.
Dimensionen müssen im Dimensionsfeld eines Anfragetexts definiert werden. Damit diese Dimensionen in einem Bericht sichtbar sind, müssen sie auch im Feld fieldNames eines Pivot-Objekts aufgeführt werden.
Dimensionen, die in keiner Pivot-Abfrage verwendet werden, sind in Berichten nicht sichtbar. Nicht jede Dimension muss in der fieldNames eines Pivots vorhanden sein. Dimensionen können ausschließlich in Filtern und nicht im fieldNames eines Pivots verwendet werden.
Das folgende Snippet veranschaulicht die Verwendung der Felder dimension und fieldNames für eine Tabelle mit 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 Namen von API-Messwerten, die in Anfragen angegeben werden können, finden Sie unter API-Messwerte.
In Pivot-Berichtsanfragen werden Messwerte über das Feld metrics des Anfragetexts definiert, das den Methoden für die Hauptdienste ähnelt.
Im folgenden Beispiel wird die Sitzungsanzahl angegeben, die als Messwert in einem Bericht verwendet werden soll:
"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 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 Zeilen mit aggregierten Messwerten 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 Core Reporting-Methoden können Sie bei Pivot-Anfragen die Felder limit und offset im Pivot-Objekt angeben, um die Paginierung zu implementieren.
Die Paginierungseinstellungen werden auf jeden Drehpunkt einzeln angewendet.
Das Feld limit ist für jedes Pivot-Objekt erforderlich, um die Berichtskardinalität 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 veranschaulicht die Verwendung der Felder offset und limit zum Abrufen der nächsten fünf language-Dimensionen mit einem Offset von 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Wird gefiltert
Ähnlich wie bei den Hauptdiensten muss ein Dimensionsfilter auf Anfrageebene verwendet werden, wenn in einer Pivot-Berichtsanfrage eine Dimensionsfilterung gewünscht wird.
Sortieren
Das Sortierverhalten von Pivot-Berichtsabfragen kann für jeden Pivot einzeln gesteuert werden. Verwenden Sie dazu das Feld orderBys eines Pivot-Objekts, das eine Liste von OrderBy-Objekten enthält.
Jedes OrderBy kann Folgendes enthalten:
- DimensionOrderBy die Ergebnisse nach den Werten einer Dimension.
- MetricOrderBy die Ergebnisse nach den Werten eines Messwerts.
- PivotOrderBy wird in Pivot-Abfragen verwendet und sortiert Ergebnisse nach den Werten eines Messwerts in einer Pivot-Spaltengruppe.
Dieses Beispiel zeigt ein Snippet für eine Pivot-Definition, das den Bericht mit der Dimension browser pivotiert, wobei die Ergebnisse nach dem Messwert sessions in absteigender Reihenfolge sortiert werden.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Antwort melden
Die Antwort auf einen Pivot-Bericht einer API-Anfrage für einen Pivot-Bericht besteht hauptsächlich aus einer Kopfzeile und Zeilen.
Antwortheader
Der Kopfzeilen des Pivot-Berichts besteht aus PivotHeaders, DimensionHeaders und MetricHeaders, in denen die Spalten des Pivot-Berichts aufgelistet sind.
Beispiel: Ein Bericht mit den Pivot-Dimensionen browser, country und language und dem Messwert sessions liefert folgende Header:
{
"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 jeder Komponente der Pivot-Berichtsantwort beim Rendern des Pivot-Berichts:
Antwortzeilen
Die Antwort zu Pivot-Berichten der Methoden runPivotReport und batchRunPivotReports unterscheidet sich von der Antwort für Core Reporting-Methoden wie runReport und batchRunReports darin, dass jede Antwortzeile zu Pivot-Berichten eine einzelne Zelle der Tabelle darstellt, während in einem regulären Bericht eine einzelne Antwortzeile eine vollständige Tabellenzeile darstellt.
Unten sehen Sie ein Fragment einer Pivot-Berichtantwort auf 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 in der folgenden Tabelle hervorgehobenen Zellen:
Clientbibliotheken
In der Kurzanleitung wird erläutert, wie Clientbibliotheken installiert und konfiguriert werden.
Im Folgenden finden Sie ein Beispiel für die Verwendung der Python-Clientbibliothek, die eine Pivot-Abfrage ausführt, um einen Bericht mit Sitzungszahlen nach Land, ausgerichtet auf die Browserdimension, zu erstellen.
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)
Demoanwendung
Ein Beispiel für das Erstellen und Anzeigen eines Pivot-Berichts mit JavaScript finden Sie in der Demoanwendung: Google Analytics API Version 1-Pivot-Bericht.