In diesem Leitfaden finden Sie Richtlinien für die Migration von Version 3 der Core Reporting API zur Analytics Reporting API Version 4.
Einführung
Damit Sie die neuen Funktionen der Analytics Reporting API Version 4 nutzen können, müssen Sie Ihren Code zur API migrieren. In diesem Leitfaden werden Anfragen in Version 3 der Core Reporting API und die entsprechenden Anfragen in Version 4 der Analytics Reporting API aufgeführt, um die Migration zu vereinfachen.
Python-Migration
Als Python-Entwickler können Sie die GAV4-Hilfsbibliothek auf GitHub verwenden, um Google Analytics Core Reporting API v3-Anfragen 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:
Endpunkt v3
GET https://www.googleapis.com/analytics/v3/data/ga
Endpunkt v4
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 Erkennungsdienst
Wenn Sie die 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 Discovery-Dienst und dem Google APIs-Generator generieren.
Anfragen
In der API v4-Referenz wird die Struktur des Anfragetexts detailliert beschrieben. In den folgenden Abschnitten wird die Migration von Anfrageparametern von Version 3 zu Anfrageparametern von Version 4 beschrieben.
IDs ansehen
In v3 hat ein ids
-Parameter, der eine „Tabellen-ID“ akzeptiert, das Format ga:XXXX
, wobei XXXX
die ID der Ansicht (Profil) ist. In Version 4 wird im Anfragetext im Feld viewId
eine Datenansichts-ID (Profil-ID) 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 einzigen 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 mit dem 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
, das eine Liste mit Messwertobjekten enthält.
In den folgenden Beispielen werden die metrics
-Parameter in einer V3-Anfrage mit dem 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 dimensions
-Parameter von Version 3 entspricht dem Feld dimensions
der Version 4 mit einer Liste von Dimensionsobjekten.
In den folgenden Beispielen werden die dimensions
-Parameter in einer V3-Anfrage mit dem 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 Parameter sort
von Version 3 entspricht dem Feld orderBys
in Version 4, für das eine Liste von OrderBy-Objekten angegeben wird.
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
) über das FeldsortOrder
an.
In den folgenden Beispielen werden der Parameter sort
in einer V3-Anfrage mit dem Feld orderBy
in einer V4-Anfrage verglichen. Die Nutzer werden in absteigender Reihenfolge sortiert und die Quellen alphabetisch sortiert:
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
. In Version 3 sind die zulässigen samplingLevel
-Werte FASTER
, HIGHER_PRECISION
und DEFAULT
. In Version 4 sind die zulässigen samplingLevel
-Werte SMALL
, LARGE
und DEFAULT
.
Beachten Sie, dass FASTER
in v3 zu SMALL
in v4 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 segment
-Parameter von Version 3 entspricht dem segments
-Feld von Version 4, das eine Liste von 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
Verwenden Sie in Version 4 für komplexere Segmentdefinitionen das Feld segments
, das ein DynamicSegment-Objekt enthält.
In den folgenden Beispielen wird der Parameter segment
in einer V3-Anfrage mit dem Feld segments
verglichen, das ein DynamicSegment
-Objekt in einer V4-Anfrage enthält:
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 Version 4
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
In Version 4 wird dimensionFilterClauses
zum Filtern von Dimensionen und metricFilterClauses
zum Filtern von Messwerten verwendet. Ein dimensionFilterClauses
enthält eine Liste von DimensionFilter-Objekten und ein 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 Version 3 in Version 4
Obwohl das Feld filtersExpression in Version 4 die Syntax filters
in Version 3 unterstützt, verwenden Sie dimensionFilterClauses
und metricFilterClauses
, um Dimensionen und Messwerte zu 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 Parameter v3 ist standardmäßig auf true gesetzt, in v4 der Wert false. Wenn Sie den Wert in v3 nicht festgelegt haben, müssen Sie ihn in v4 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 Version 4 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
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 mit Ausnahme der Parameter userIp
und callback
die meisten Standardsuchparameter in Version 3.
In den folgenden Beispielen wird der Parameter quotaUser
in einer V3-Anfrage mit dem Parameter in einer V4-Anfrage verglichen:
Endpunkt v3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
Endpunkt v4
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 wird in der Antwort ein Array mit Berichtsobjekten zurückgegeben. Für jede gesendete ReportRequest erhalten Sie in der Antwort einen entsprechenden Report.
Berichte
Ein v4-Bericht hat drei Felder auf oberster Ebene: columnHeader
, data
und nextPageToken
.
Da der Antworttext von Version 4 nicht im Gegensatz zur Antwort von Version 3 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 Objekt columnHeader an.
Spaltenüberschrift
Die Spaltenüberschrift enthält eine Liste benannter Dimensionen und ein MetricHeader-Objekt, das eine Liste von MetricHeaderEntry-Objekten enthält. 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
Version 3 der Core Reporting API gibt die Berichtsdaten im Array rows zurück, das die angeforderten Dimensionen und Messwerte enthält.
Die Analytics Reporting API Version 4 gibt die Berichtsdaten in einem ReportRow-Objekt zurück. Dieses Objekt enthält ein Array mit Dimensionen und ein Array von DateRangeValues-Objekten, die jeweils einen oder zwei Zeiträume enthalten, 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 Daten als Stichproben verwendet werden. Die API gibt stattdessen die Felder samplesReadCounts
und samplingSpaceSizes
zurück.
Wenn keine Stichproben der Ergebnisse vorliegen, werden diese Felder nicht definiert.
Im folgenden Python-Beispiel wird gezeigt, wie man berechnet, 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 ausgegeben:
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 V4 von dem in V3 unterscheidet, aktualisieren Sie Ihren Code so, dass v4-Fehlerantworten verarbeitet werden.
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.\" }"
}
]
}
}