In diesem Dokument wird beschrieben, wie Sie vorhandenen Code von der Google Analytics Reporting API (Version 4) zur Google Analytics Data API (Version 1) migrieren. Außerdem erhalten Sie einen kurzen Überblick über die wichtigsten Unterschiede zwischen den beiden APIs.
Warum muss ich migrieren?
Wenn Ihre Anwendung auf Daten in einer Google Analytics 4-Property zugreifen muss, müssen Sie den Code so aktualisieren, dass die Data API Version 1 verwendet wird, da mit der Reporting API Version 4 nur auf Properties zugegriffen werden kann, die mit Universal Analytics erstellt wurden.
Voraussetzungen
Machen Sie sich in der Kurzanleitung mit den Grundlagen der Data API Version 1 vertraut.
Erste Schritte
Bereiten Sie zuerst eine Google Analytics 4-Property vor, aktivieren die Data API v1 und richten dann eine API-Clientbibliothek ein, die für Ihre Plattform geeignet ist.
Google Analytics 4-Property vorbereiten
Bevor Sie mit der Migration Ihres Codes zur Unterstützung der Data API v1 beginnen, müssen Sie Ihre Website für eine Google Analytics 4-Property migrieren. Es ist nicht möglich, Verlaufsdaten aus einer Universal Analytics-Property in eine Google Analytics 4-Property zu übertragen.
API aktivieren
Klicken Sie auf diese Schaltfläche, um die Data API v1 im ausgewählten Google Cloud-Projekt automatisch zu aktivieren.
Google Analytics Data API v1 aktivierenClientbibliothek verwenden
Clientbibliothek installieren
Wenn Sie eine Clientbibliothek verwenden, müssen Sie die Data API v1-Clientbibliothek für Ihre Programmiersprache installieren.
Java
Python
Node.js
.NET
PHP
Ok
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Clientbibliothek initialisieren
Die Data API v1-Clientbibliotheken wurden für einen schnellen Einstieg entwickelt. Standardmäßig versuchen Clientbibliotheken, die Anmeldedaten Ihres Dienstkontos automatisch zu finden.
Eine einfache Möglichkeit zur Bereitstellung von Dienstkonto-Anmeldedaten ist, die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festzulegen. Der API-Client verwendet den Wert dieser Variablen, um die JSON-Datei mit dem Dienstkontoschlüssel zu finden.
Sie können beispielsweise die Anmeldedaten für ein Dienstkonto festlegen, indem Sie den folgenden Befehl ausführen und den Pfad zur JSON-Datei des Dienstkontos verwenden:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Unten finden Sie die Code-Snippets, die häufig zum Initialisieren der Data API v1-Clientbibliotheken verwendet werden.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Anstatt eine Umgebungsvariable zu verwenden, ist es auch möglich, die Anmeldedaten während der Initialisierung explizit an eine API-Clientinstanz weiterzugeben. Unten finden Sie die Snippets, mit denen die Data API v1-Clientbibliotheken durch explizites Übergeben der Anmeldedaten im Code initialisiert werden.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Keine Clientbibliothek verwenden
Wenn Sie die Reporting API Version 4 ohne Clientbibliothek verwendet haben und dies weiterhin mit der Data API Version 1 tun möchten, können Sie weiterhin Ihre Anmeldedaten verwenden.
Sie müssen den neuen HTTP-Endpunkt und das Discovery-Dokument verwenden, die von der Data API bereitgestellt werden:
Wenn Ihr Code ein Discovery-Dokument nutzt, müssen Sie es auf das von der Data API Version 1 bereitgestellte Discovery-Dokument aktualisieren:
Nachdem Sie den Endpunkt aktualisiert haben, müssen Sie sich mit der neuen Anfragestruktur und den Konzepten der Data API vertraut machen, damit Sie Ihre JSON-Abfrage aktualisieren können.
Kernberichte
Verfügbare Berichtsmethoden
In Version 4 der Reporting API konnte mit einer einzigen Methode batchGet auf die grundlegenden Berichtsfunktionen zugegriffen werden. In Version 1 der Data API stehen mehrere Methoden für Kernberichte zur Auswahl:
- runReport: Diese Methode gibt einen benutzerdefinierten Bericht über Ihre Google Analytics-Ereignisdaten zurück. Es unterstützt keine Pivot-Funktionen und ist eine bevorzugte Methode für einfache Berichtsabfragen.
- runPivotReport: Diese Methode gibt einen angepassten Pivot-Bericht Ihrer Google Analytics-Ereignisdaten zurück. Ähnlich wie bei den Pivots in der Reporting API Version 4 beschreibt jeder Pivot die sichtbaren Dimensionsspalten und -zeilen in der Berichtsantwort.
- batchRunReports Dies ist eine Batchversion der Methode
runReport, mit der mehrere Berichte mit einem einzigen API-Aufruf generiert werden können. - batchRunPivotReports: Dies ist eine Batchversion der Methode
runPivotReport, mit der mehrere Berichte mit einem einzigen API-Aufruf generiert werden können.
Mehrere Methoden zur Berichterstellung dienen hauptsächlich der Komfort. Einige Methoden unterstützen komplexere Funktionen als andere (Pivots, Batching), nutzen aber ansonsten eine ähnliche Anfragestruktur.
Änderungen am API-Schema
Die Berichtsfunktionen der Reporting API und der Data API richten sich hauptsächlich nach ihrem Schema, d.h. den Dimensionen und Messwerten, die in Berichtsabfragen unterstützt werden. Die API-Schemas unterscheiden sich zwischen den beiden APIs aufgrund der konzeptionellen Unterschiede zwischen Universal Analytics und Google Analytics 4 erheblich.
- Machen Sie sich mit der aktuellen Liste der Dimensionen und Messwerte vertraut, die von der Data API unterstützt werden. Derzeit sind alle Dimensionen und Messwerte miteinander kompatibel. Sie müssen also nicht den Explorer für Dimensionen und Messwerte verwenden, um kompatible Kombinationen zu ermitteln. Dieses Verhalten wird sich in Zukunft ändern.
- Auf benutzerdefinierte Dimensionen in Google Analytics 4 kann über die Syntax für benutzerdefinierte Dimensionen der Data API Version 1 zugegriffen werden. Diese sollte anstelle der Dimensionsslots ga:dimensionXX der Reporting API Version 4 verwendet werden.
- Auf benutzerdefinierte Messwerte in Google Analytics 4 kann über die Syntax für benutzerdefinierte Messwerte der Data API Version 1 zugegriffen werden. Diese sollte anstelle der Messwertslots ga:metricXX der Reporting API Version 4 verwendet werden.
- Bestimmte Dimensionen und Messwerte aus Universal Analytics haben in Google Analytics 4 ein direktes Äquivalent. Weitere Informationen finden Sie im Diagramm zur UA/GA4 API-Schemaäquivalenz.
- Namen von Dimensionen und Messwerten haben in Google Analytics 4 nicht mehr das Präfix
ga:. - Bestimmte Universal Analytics-Funktionen (z.B. Campaign Manager-, DV360- oder Search Ads 360-Verknüpfung) sind in GA4 noch nicht verfügbar. Sobald diese Funktion in Google Analytics 4 implementiert ist, wird sie von der Data API unterstützt. Dem API-Schema werden neue Dimensionen und Messwerte hinzugefügt.
Entitäten
In Google Analytics 4 wurden in Universal Analytics keine Datenansichten (Profile) eingeführt. Daher gibt es in den Berichtsanfragen der Data API Version 1 keinen viewId-Parameter. Stattdessen sollte beim Aufrufen der Methoden der Data API Version 1 eine numerische Google Analytics 4-Property-ID in einem Anfrage-URL-Pfad angegeben werden.
Dieses Verhalten unterscheidet sich von der Reporting API Version 4, bei der zur Identifizierung der meldenden Entität Ansichts- bzw. Profil-IDs verwendet werden.
Daten-API v1
Bei der Data API Version 1 muss im URL-Pfad eine numerische Google Analytics 4-Property-ID angegeben werden.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API Version 4
Bei der Reporting API Version 4 muss im Text einer Berichtsabfrage die ID einer Universal Analytics-Datenansicht (Profil) angegeben werden.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
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.
Zeiträume
Sowohl die Reporting API v4 als auch die Data API v1 unterstützen mehrere Zeiträume, die mit dem Feld dateRanges in einer Berichtsanfrage angegeben werden. Beide APIs haben dasselbe Datumseingabeformat und akzeptieren absolute Datumswerte im Format YYYY-MM-DD oder relative Daten wie yesderday, today, 7daysAgo usw.
Anfragen an Data API V1 sind auf vier Zeiträume beschränkt, während die Reporting API Version 4 zwei Zeiträume in einer einzelnen Berichtsanfrage zulässt.
Jede dateRange in der Data API Version 1 kann ein optionales name-Feld haben, mit dem in einer Antwort auf den entsprechenden Zeitraum verwiesen werden kann.
Wenn name nicht angegeben ist, wird der Name für den Zeitraum automatisch generiert.
Wenn in einer Anfrage der Data API Version 1 mehrere Zeiträume angegeben sind, wird einer Antwort automatisch die neue Dimension dateRange hinzugefügt. Außerdem wird der Zeitraumname als Dimensionswert verwendet. Dieses Verhalten unterscheidet sich von der Reporting API Version 4, die Daten für einen Zeitraum als Gruppe von Messwerten in jeder Zeile zurückgibt.
Data API v1-Anfrage
Für jeden dateRange-Wert in einer Anfrage wird ein optionales Feld name verwendet.
Der Name des Zeitraums wird als Wert der Dimension dateRange in der Antwort verwendet.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Antwort des Data API v1
Die Antwort enthält automatisch die zusätzliche Dimension dateRange.
Der Dimensionswert dateRange enthält den Namen eines Zeitraums. Dieser stammt entweder aus dem Feld dateRange.name oder wird automatisch bewertet.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Anfrage an Reporting API Version 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Antwort der Reporting API Version 4
In der Reporting API Version 4 sind die Werte für jeden Zeitraum im Feld metrics gruppiert:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Sortieren
Das Sortierverhalten von Data API-Berichtsabfragen der Data API (Version 1) kann mit dem Feld orderBys gesteuert werden, ähnlich dem Feld orderBys der Reporting API Version 4.
Die OrderBy-Spezifikation hat sich in der Data API Version 1 geändert.
Jedes OrderBy kann Folgendes enthalten:
- Mit DimensionOrderBy werden die Ergebnisse nach den Werten einer Dimension sortiert.
- MetricOrderBy: Die Ergebnisse werden nach den Werten eines Messwerts sortiert.
- PivotOrderBy wird in Pivot-Abfragen verwendet und sortiert Ergebnisse nach den Werten eines Messwerts in einer Pivot-Spaltengruppe.
Die von der Reporting API Version 4 unterstützten Sortierungstypen DELTA, SMART und HISTOGRAM_BUCKET sind nicht in Version 1 der Data API implementiert.
Der Sortierungstyp OrderType.NUMERIC der Data API Version 1 entspricht dem Wert OrderType.DIMENSION_AS_INTEGER der Reporting API Version 4.
Data API v1-Anfrage
Dieses Beispiel zeigt eine Beispielabfrage, mit der die Sitzungsanzahl nach Land ausgegeben wird. Dabei werden die Zeilen nach dem Messwert sessions in absteigender Reihenfolge sortiert.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Antwort des Data API v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Anfrage an Reporting API Version 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Antwort der Reporting API Version 4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Wird gefiltert
Mit den Klauseln dimensionFilter und metricFilter der Data API Version 1 kann die API angewiesen werden, nur Daten für bestimmte Dimensions- oder Messwerte zurückzugeben. Dies ähnelt den dimensionFilterClauses und metricFilterClauses der Reporting API Version 4.
Die Data API (Version 1) unterstützt keine Filterausdrucksstrings wie die Klausel filtersExpression der Reporting API Version 4. Diese Ausdrücke sollten mit den Klauseln dimensionFilter und metricFilter umgeschrieben werden.
Data API v1-Anfrage
Diese Beispielanfrage gibt eine Liste der Sitzungsanzahlen für bestimmte Seitenpfade zurück, die von Nutzern besucht wurden.
Mit der Klausel dimensionFilter werden nur Zeilen zurückgegeben, deren pagePath-Dimensionswerte mit /webstore/ beginnen und den String action=a12345 enthalten.
Die Klausel metricFilter fordert die Methode runReport an, nur die Zeilen zurückzugeben, deren Messwerte sessions größer als 1.000 sind.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Anfrage an Reporting API Version 4
Diese Beispielanfrage ähnelt dem Beispiel der Data API Version 1. Sie gibt eine Liste der Sitzungsanzahlen für bestimmte Seitenpfade zurück, die von Nutzern besucht wurden.
Mit dem Feld dimensionFilterClauses werden nur Zeilen zurückgegeben, deren pagePath-Dimensionswerte mit /webstore/ beginnen und den String action=a12345 enthalten.
Mit dem Feld metricFilterClauses werden nur Zeilen mit einem ga:sessions-Messwert zurückgegeben,der größer als 1.000 ist.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Seitenumbruch
In Version 1 der Data API werden die Felder limit und offset für die Paginierung in Antwortergebnissen verwendet, die sich über mehrere Seiten erstrecken. In Version 4 der Reporting API werden pageToken und pageSize verwendet.
Bei Pivot-Anfragen der Data API Version 1 sollten die Felder limit und offset des Pivot-Objekts verwendet werden, um die Paginierung für jeden Pivot einzeln zu implementieren. Das Feld limit ist jetzt für jedes Pivot-Objekt erforderlich.
Standardmäßig gibt die Data API (Version 1) maximal die ersten 10.000 Zeilen mit Ereignisdaten zurück. Der Standardwert für die Reporting API Version 4 beträgt 1.000 Zeilen.
Die Gesamtzahl der Zeilen, die der Abfrage entsprechen, wird über das Feld rowCount in einer Antwort der Data API Version 1 zurückgegeben, die der Reporting API Version 4 ähnelt.
Data API v1-Anfrage
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Antwort des Data API v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Anfrage an Reporting API Version 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Antwort der Reporting API Version 4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Messwertaggregationen
Die Data API v1 berechnet Aggregationswerte nur dann, wenn das Feld metricAggregations in einer Anfrage angegeben ist. Die Reporting API Version 4 gibt dagegen standardmäßig die Gesamt-, Mindest- und Höchstwerte für jeden Messwert zurück, es sei denn, die Felder hideTotals und hideValueRanges sind auf true festgelegt.
Data API v1-Anfrage
Zusammenfassungen werden nur berechnet, wenn das Feld metricAggregations in einer Anfrage angegeben ist.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Antwort des Data API v1
Aggregierte Messwertzeilen werden in den Feldern totals, minimum und maximum einer Antwort zurückgegeben. Bei Zeilen mit aggregierten Messwerten enthält das Feld dimensionValues den speziellen Wert RESERVED_TOTAL, RESERVED_MAX oder RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Anfrage an Reporting API Version 4
Eine Beispielanfrage, um die Anzahl der Sitzungen nach Land zurückzugeben.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Antwort der Reporting API Version 4
Die Felder totals, minimums und maximums sind standardmäßig in einer Antwort der Reporting API Version 4 vorhanden.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Pivots
Die Data API Version 1 unterstützt die Pivot-Funktion in den Berichtsmethoden runPivotReport und batchRunPivotReports.
In Version 4 der Reporting API können Pivots mithilfe der batchGet-Methode in Berichtsabfragen aufgenommen werden.
Pivots werden in der Data API Version 1 anders implementiert als in Version 4 der Reporting API. Dabei stellt jede Antwortzeile eine einzelne Zelle der Tabelle dar, während in der Reporting API Version 4 eine einzelne Antwortzeile eine vollständige Tabellenzeile darstellt.
Daten-API v1
Unten sehen Sie ein Fragment einer Data API V1-Antwort auf die runPivotReport-Abfrage. Jede Zelle des Pivoting-Berichts wird einzeln zurückgegeben:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API Version 4
Unten finden Sie ein Fragment einer Antwort der Reporting API Version 4 auf die batchGet-Abfrage. Eine einzelne Antwortzeile stellt eine vollständige Tabellenzeile dar, die alle Messwerte für den Pivot in pivotValueRegions enthält:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
In der Data API Version 1 muss jede Dimension der runPivotReport- oder batchRunPivotReports-Abfrage in einem Pivot-Objekt definiert werden. Eine Dimension ist in Berichten nicht sichtbar, wenn sie in keinem Pivot einer Pivot-Abfrage verwendet wird.
Pivoting-Spalten der Data API Version 1 werden mit dem Feld fieldNames anstelle des Felds dimensions der Reporting API v4 angegeben.
Wenn in einer Berichtsanfrage der Data API Version 1 die Dimensionsfilterung gewünscht wird, muss ein Dimensionsfilter auf Anfrageebene verwendet werden. Dies unterscheidet sich von der Reporting API Version 4, die die Spezifikation dimensionFilterClauses in einem Pivot-Objekt akzeptiert.
Die Funktionsweise des Felds offset der Data API V1 ähnelt dem Feld startGroup der Reporting API Version 4.
Das Feld limit der Data API Version 1 ähnelt dem Feld maxGroupCount der Reporting API Version 4 und sollte verwendet werden, um die Kardinalität von Berichten zu begrenzen.
Die Data API v1 unterstützt mehrere Pivots,solange das Produkt des Parameters limit für jeden Pivot 100.000 nicht überschreitet. Die Reporting API Version 4 unterstützt
nur eine Pivot-Dimension.
Standardmäßig ordnet die Data API v1 Dimensionen innerhalb eines Pivot nach dem ersten Messwert im Bericht zu. Dieses Verhalten unterscheidet sich von der Reporting API Version 4, bei der die Pivot-Reihenfolge durch die absteigende Reihenfolge der "Gesamtzahl" der angeforderten Messwerte bestimmt wird. Verwenden Sie zum Angeben der Sortierreihenfolge in der Data API Version 1 das Feld orderBys einer Pivot-Spezifikation.
Data API v1-Anfrage
Mit dieser Pivot-Abfrage der Data API Version 1 wird ein Bericht zur Anzahl der Sitzungen nach Land erstellt, wobei die Dimension browser verwendet wird. Die Abfrage verwendet die Felder orderBys, limit und offset, um das Verhalten einer ähnlichen Abfrage der Reporting API Version 4 zu reproduzieren und die Sortier- und Paginierungseinstellungen beizubehalten.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"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"
}
]
}
Antwort des Data API v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Anfrage an Reporting API Version 4
Mit dieser Pivot-Abfrage der Reporting API Version 4 wird ein Bericht zur Sitzungsanzahl nach Land erstellt, wobei die Dimension ga:browser verwendet wird.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Antwort der Reporting API Version 4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Kohorten
In Version 1 der Data API wird die CohortSpec-Spezifikation verwendet, um Kohortenberichte zu konfigurieren. Dies ähnelt der Spezifikation CohortGroup der Reporting API Version 4.
Alle in der Data API (Version 1) verfügbaren Messwerte sind derzeit mit Kohortenabfragen kompatibel. Bei der Reporting API (Version 4) kann hingegen nur eine Teilmenge spezieller Messwerte in einer Kohortenabfrage verwendet werden.
In einer Data API v1-Kohortenanfrage ist der Messwert cohortActiveUsers erforderlich.
Sowohl mit der Data API v1 als auch mit der Reporting API v4 sind bis zu zwölf Kohorten in einer einzelnen Anfrage zulässig.
Messwerte zum Lifetime-Wert (LTV) werden derzeit in der Data API Version 1 nicht unterstützt.
Äquivalenz von Kohortenmesswerten
Die meisten in der Reporting API Version 4 definierten Kohortenmesswerte können durch einen Ausdruck ersetzt werden, um ein gleichwertiges Ergebnis in Version 1 der Data API zu erzielen (siehe Diagramm unten).
| Messwertname der Reporting API Version 4 | Messwertname oder -ausdruck der Data API v1 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers", zusätzlich zu einem Dimensionsfilter nach eventName, der dem gewünschten Zielvorhaben beim Abschluss entspricht. |
Data API v1-Anfrage
Eine Beispielabfrage, mit der eine Kohorte von Nutzern konfiguriert wird, deren erste Sitzung in einer Woche am 03.01.2021 stattfand. Die Anzahl der aktiven Nutzer und die Nutzerbindungsrate werden mit dem Detaillierungsgrad WÖCHENTLICH für die Kohorte über einen Zeitraum von 5 Wochen berechnet.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Antwort des Data API v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Anfrage an Reporting API Version 4
Eine Beispielabfrage, mit der eine Kohorte von Nutzern konfiguriert wird, deren erste Sitzung in einer Woche am 03.01.2021 stattfand. Die Anzahl der aktiven Nutzer und die Nutzerbindungsrate werden für die Kohorte über einen Zeitraum von 5 Wochen mit dem Detaillierungsgrad WEEKLY berechnet.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Antwort der Reporting API Version 4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Probenahme
Die Data API v1 verwendet automatisch Stichproben, wenn davon auszugehen ist, dass Kardinalitätsbeschränkungen die Datenqualität beeinträchtigen. Wenn für die Ergebnisse für einen Zeitraum Stichproben verwendet werden, enthält der metadata von RunReportResponse den entsprechenden Wert SamplingMetadata, ähnlich dem Feld samplingLevel, das in Version 4 der Reporting API vorhanden war.
Datenaktualität
Die Data API bietet keine Entsprechung für das Feld isDataGolden der Reporting API v4, mit dem angegeben wird, ob alle Treffer für einen Bericht die Verarbeitung abgeschlossen haben. Es ist auch möglich, dass derselbe Bericht bei einer späteren Abfrage aufgrund zusätzlicher Verarbeitung unterschiedliche Ergebnisse zurückgibt.
(Nicht unterstützt) Segmente
Segmente werden derzeit in der Data API Version 1 nicht unterstützt.
Echtzeitberichte
Mit der Methode properties.runRealtimeReport der Data API Version 1 können Sie Echtzeitberichte für Google Analytics 4-Properties erstellen. Die Echtzeitberichtsfunktion für Universal Analytics-Properties wurde über die Methode data.realtime.get der Google Analytics API Version 3 bereitgestellt.
Das Schema für Echtzeitberichte der Data API unterscheidet sich aufgrund von konzeptionellen Unterschieden zwischen Universal Analytics und Google Analytics 4 vom Schema für Echtzeitberichte der Analytics API Version 3.
Data API v1-Anfrage
Im folgenden Beispiel wurde der Data API-Beispielabfrage der Version 3 der Google Analytics API ein optionales orderBy-Element hinzugefügt, um das standardmäßige Sortierverhalten der Google Analytics API Version 3 beizubehalten.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Antwort des Data API v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Anfrage an Google Analytics API Version 3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Antwort von Google Analytics API v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Nicht unterstützt) Berichte zur Nutzeraktivität
In Version 1 der Data API wird derzeit keine Funktion zum Erfassen einzelner Nutzeraktivitäten unterstützt, die mit der Methode userActivity.search der Reporting API Version 4 vergleichbar ist.
Änderungen des API-Kontingents
Kern- und Echtzeit-Kontingentkategorien
Für das Kontingent hat die Data API zwei Anfragekategorien: Kern und Echtzeit. Bei API-Anfragen an Core-Berichtsmethoden (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) werden Core-Kontingente berechnet.
Bei API-Anfragen an die Methode runRealtimeReport werden Echtzeitkontingente berechnet.
Tokenkontingente
Zusätzlich zu den Projektkontingenten verbraucht jede Anfrage Attribut-Tokenkontingente, die je nach Komplexität der Abfrage berechnet werden. Eine ausführliche Beschreibung der API-Kontingente und -Limits finden Sie in der Dokumentation zu Kontingenten für die Data API Version 1.
Sie können den aktuellen Status aller Kontingente für eine Analytics-Property abrufen, indem Sie returnPropertyQuota in einer Kern- oder Echtzeitberichtsanfrage auf true festlegen. Der Kontingentstatus wird in PropertyQuota zurückgegeben.
(Nicht unterstützt) Ressourcenbasiertes Kontingent
Da alle grundlegenden Berichte in Google Analytics 4 auf Gesamtdaten basieren, ist das mit der Reporting API Version 4 eingeführte ressourcenbasierte Kontingent nicht mehr gültig. Außerdem gibt es in einer Berichtsanfrage der Data API Version 1 keine Entsprechung für das Feld useResourceQuotas.
(Nicht unterstützt) Kontingent für Anfragen pro Aufruf (Profil) pro Tag
Da es in Google Analytics 4 keine Datenansichten gibt, ist das requests per view (profile) per day-Kontingent in Version 1 der Data API nicht vorhanden und wird durch Tokenkontingente ersetzt.