Dieser Leitfaden enthält Richtlinien für die Migration der Core Reporting API (Version 3) zur Analytics Reporting API (Version 4).
Einleitung
Damit Sie die Vorteile der neuen Funktionen in Version 4 der Analytics Reporting API nutzen können, müssen Sie Ihren Code zur API migrieren. In diesem Leitfaden werden Anfragen in der Core Reporting API (Version 3) und die entsprechenden Anfragen in der Analytics Reporting API (Version 4) aufgeführt, um die Migration zu vereinfachen.
Python-Migration
Wenn Sie ein Python-Entwickler sind, können Sie die GAV4-Hilfsbibliothek auf GitHub verwenden, um Anfragen der Google Analytics Core Reporting API v3 in Analytics Reporting API v4-Anfragen zu konvertieren.
Endpunkte
Die Core Reporting API (Version 3) und die Analytics Reporting API (Version 4) haben unterschiedliche Endpunkte und HTTP-Methoden:
v3-Endpunkt
GET https://www.googleapis.com/analytics/v3/data/ga
v4-Endpunkt
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
In den folgenden Beispielen wird eine Anfrage in Version 3 und die entsprechende Anfrage in Version 4 verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
Clientbibliotheken und Discovery-Dienst
Wenn Sie Python, JavaScript oder eine andere Clientbibliothek verwenden, die auf dem Google Discovery Service basiert, müssen Sie den Speicherort des Discovery-Dokuments für die Reporting API v4 angeben.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
Die Java- und PHP-Clientbibliotheken sind vorgefertigt. Sie können sie jedoch mit dem Erkennungsdienst und dem Google APIs-Generator generieren.
Anfragen
In der API-Referenz für Version 4 wird die Struktur des Anfragetexts ausführlich beschrieben. In den folgenden Abschnitten wird die Migration von V3-Anfrageparametern zu V4-Anfrageparametern beschrieben.
IDs ansehen
In v3 hat ein ids
-Parameter, der eine „Tabellen-ID“ akzeptiert, das Format ga:XXXX
, wobei XXXX
die ID der Datenansicht (des Profils) ist. In Version 4 wird eine Datenansichts- bzw. Profil-ID im Feld viewId
im Anfragetext angegeben.
In den folgenden Beispielen wird der Parameter ids
in einer V3-Anfrage mit dem Feld viewId
in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Zeiträume
Mit der Analytics Reporting API Version 4 können Sie mehrere Zeiträume in einer einzelnen Anfrage angeben. Das Feld dateRanges
enthält eine Liste von DateRange-Objekten.
In v3 verwenden Sie die Parameter start-date
und end-date
, um einen Zeitraum in einer Anfrage anzugeben.
In den folgenden Beispielen werden die Parameter start-date
und end-date
in einer V3-Anfrage und das Feld dateRanges
in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
Messwerte
Der V3-Parameter metrics
entspricht dem V4-Feld metrics
mit einer Liste von Messwertobjekten.
In den folgenden Beispielen werden die metrics
-Parameter in einer V3-Anfrage und das Feld metrics
in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
Abmessungen
Der V3-Parameter dimensions
entspricht dem V4-Feld dimensions
, das eine Liste von Dimensionsobjekten enthält.
In den folgenden Beispielen werden die dimensions
-Parameter in einer V3-Anfrage und das Feld dimensions
in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Sortieren
Der V3-Parameter sort
entspricht dem V4-Feld orderBys
, das eine Liste von OrderBy-Objekten enthält.
So sortieren Sie in Version 4 die Ergebnisse nach einer Dimension oder einem Messwert:
- Geben Sie den Namen oder Alias über das Feld
fieldName
an. - Geben Sie die Sortierreihenfolge (
ASCENDING
oderDESCENDING
) im FeldsortOrder
an.
In den folgenden Beispielen wird der Parameter sort
in einer V3-Anfrage mit dem Feld orderBy
in einer V4-Anfrage verglichen. Beide sortieren die Nutzer in absteigender Reihenfolge und in alphabetischer Reihenfolge:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
Stichprobenebene
Der V3-Parameter samplingLevel
entspricht dem V4-Feld samplingLevel
. Die akzeptierten samplingLevel
-Werte in v3 sind FASTER
, HIGHER_PRECISION
und DEFAULT
. In Version 4 sind die zulässigen samplingLevel
-Werte SMALL
, LARGE
und DEFAULT
.
Beachten Sie, dass FASTER
in Version 3 zu SMALL
in Version 4 und HIGHER_PRECISION
zu LARGE
geändert wurde.
In den folgenden Beispielen wird der Parameter samplingLevel
in einer V3-Anfrage mit dem Feld samplingLevel
in einer V4-Anfrage verglichen:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
Segmente
Der V3-Parameter segment
entspricht dem V4-Feld segments
, das eine Liste mit Segment-Objekten enthält.
Segment-IDs
Um in Version 4 ein Segment nach Segment-ID anzufordern, müssen Sie ein Segment-Objekt erstellen und seine ID über das Feld segmentId angeben.
In den folgenden Beispielen wird der Parameter segment
in einer V3-Anfrage mit dem Feld segments
in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
Dynamische Segmente
In Version 4 können Sie für komplexere Segmentdefinitionen das Feld segments
verwenden, das ein DynamicSegment-Objekt enthält.
In den folgenden Beispielen wird der Parameter segment
in einer V3-Anfrage mit dem Feld segments
mit einem DynamicSegment
-Objekt in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
Sie können Bedingungen und Sequenzen in einem Segment kombinieren:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
v3 Segmentsyntax in v4
Das Feld segmentId in Version 4 der API unterstützt die Segmentsyntax in Version 3 der API.
Die folgenden Beispiele zeigen, wie der Parameter segment
in einer V3-Anfrage vom Feld segmentId
in der entsprechenden Anfrage in V4 unterstützt wird:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filter
Version 4 verwendet dimensionFilterClauses
zum Filtern von Dimensionen und metricFilterClauses
zum Filtern von Messwerten. dimensionFilterClauses
enthält eine Liste mit DimensionFilter-Objekten und metricFilterClauses
eine Liste von MetricFilter-Objekten.
In den folgenden Beispielen wird der Parameter filters
in einer V3-Anfrage mit dem Feld dimensionFilterClauses
in einer V4-Anfrage verglichen:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
Filtersyntax von V3 in Version 4
Obwohl das Feld filtersExpression in Version 4 die Syntax filters
in Version 3 unterstützt, können Sie mit dimensionFilterClauses
und metricFilterClauses
nach Dimensionen und Messwerten filtern.
Die folgenden Beispiele zeigen, wie der Parameter filters
in einer V3-Anfrage vom Feld filtersExpression
in der entsprechenden Anfrage in V4 unterstützt wird:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
Leere Zeilen
Der v3-Parameter include-empty-rows
entspricht dem includeEmptyRows
-Feld in V4. Der v3-Parameter ist standardmäßig auf true gesetzt, während das Feld in v4 auf false gesetzt ist. Wenn Sie den Wert in Version 3 nicht festgelegt haben, müssen Sie ihn in Version 4 auf true setzen.
In den folgenden Beispielen wird der Parameter include-empty-rows
in einer V3-Anfrage mit dem Feld includeEmptyRows
in einer V4-Anfrage verglichen:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Seitenumbruch
In v4 werden die Felder pageToken
und pageSize
für die Paginierung durch eine große Anzahl von Ergebnissen verwendet. Der pageToken
wird aus dem Attribut nextPageToken
eines Antwortobjekts abgerufen.
In den folgenden Beispielen werden die Parameter start-index
und max-results
in einer V3-Anfrage mit den Feldern pageToken
und pageSize
in einer V4-Anfrage verglichen:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Standardparameter
Die Analytics Reporting API (Version 4) unterstützt die meisten Standardabfrageparameter in Version 3, mit Ausnahme der Parameter userIp
und callback
.
In den folgenden Beispielen wird der Parameter quotaUser
in einer V3-Anfrage mit dem Parameter in einer V4-Anfrage verglichen:
v3-Endpunkt
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4-Endpunkt
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Antworten
In Version 4 können mehrere ReportRequest-Objekte in einer einzelnen HTTP-Anfrage gesendet werden. Daher enthält die Antwort eine Reihe von Berichtsobjekten. Für jede gesendete ReportRequest erhalten Sie einen entsprechenden Report in der Antwort.
Berichte
Ein V4-Bericht enthält drei Felder auf oberster Ebene: columnHeader
, data
und nextPageToken
.
Da der Antworttext von V4 nicht im Gegensatz zur Antwort von V3 Antworten auf alle Abfrageparameter enthält, muss die Clientanwendung diesen Parameter der ReportRequest hinzufügen, um eine Antwort auf einen bestimmten Abfrageparameter zu erhalten.
nextPageToken
wurde bereits im Abschnitt Pagination behandelt. Sehen wir uns daher zuerst das columnHeader-Objekt an.
Spaltenüberschrift
Die Spaltenüberschrift enthält eine Liste benannter Dimensionen und ein MetricHeader-Objekt mit einer Liste von MetricHeaderEntry-Objekten. Jedes MetricHeaderEntry-Objekt gibt den Messwert name
und seinen type
(Währung, Prozentsatz usw.)
, womit Sie die Ausgabe formatieren können.
In den folgenden Beispielen wird das Feld columnHeaders
in einer V3-Antwort mit dem Feld columnHeader
in einer V4-Antwort verglichen:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Berichtszeilen
In Version 3 der Core Reporting API werden die Berichtsdaten im Array rows (Zeilen) zurückgegeben, das die angeforderten Dimensionen und Messwerte enthält.
Die Analytics Reporting API Version 4 gibt die Berichtsdaten in einem ReportRow-Objekt zurück, das ein Array von Dimensionen und ein Array von DateRangeValues-Objekten enthält, von denen jedes einen oder zwei Zeiträume enthält, wie im folgenden Diagramm dargestellt:
Zeilen
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
Stichproben
Wenn die Ergebnisse Stichproben sind, gibt die Core Reporting API Version 3 das boolesche Feld containsSampledData
zurück, das auf true
gesetzt ist.
Die Analytics Reporting API Version 4 gibt keinen booleschen Wert zurück, wenn die Daten auf Stichproben basieren. Stattdessen werden die Felder samplesReadCounts
und samplingSpaceSizes
zurückgegeben.
Wenn die Ergebnisse nicht auf Stichproben basieren, werden diese Felder nicht definiert.
Das folgende Python-Beispiel zeigt, wie berechnet wird, ob ein Bericht Stichproben enthält:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
Die folgende Beispielantwort enthält Stichprobendaten aus einer Anfrage mit zwei Zeiträumen. Die Ergebnisse wurden aus fast 500.000 Stichproben mit einer Stichprobengröße von etwa 15 Millionen Sitzungen berechnet:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
V4-Antwort parsen
Mit dem folgenden Beispielcode wird die Antwort der Analytics Reporting API Version 4 geparst und gedruckt:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
Fehlerbehandlung
Da sich das Format der Fehlerantwort in Version 4 von dem Format in Version 3 unterscheidet, aktualisieren Sie Ihren Code so, dass er Fehlerantworten der Version 4 verarbeitet.
In den folgenden Beispielen wird eine Fehlerantwort in Version 3 und die entsprechende Fehlerantwort in Version 4 verglichen:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}