In diesem Leitfaden finden Sie Richtlinien für die Migration der Core Reporting API v3 zur Analytics Reporting API v4.
Einführung
Wenn Sie die neuen Funktionen nutzen möchten, die in der Analytics Reporting API Version 4 eingeführt wurden, müssen Sie Ihren Code zur Verwendung der API migrieren. In diesem Leitfaden finden Sie Anfragen in der Core Reporting API v3 und die entsprechenden Anfragen in der Analytics Reporting API v4, um die Migration zu vereinfachen.
Python-Migration
Wenn Sie Python-Entwickler sind, verwenden Sie die GAV4-Hilfsbibliothek auf GitHub, um Anfragen der Google Analytics Core Reporting API v3 in Anfragen der Analytics Reporting API v4 zu konvertieren.
Endpunkte
Die Core Reporting API v3 und die Analytics Reporting API v4 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 v3 mit der entsprechenden Anfrage in v4 verglichen:
v3
Referenzdokumentation für Version 3
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
Referenzdokumentation für Version 4
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 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 vorgefertigte, Sie können sie aber mit dem Erkennungsdienst und dem Google APIs-Generator generieren.
Anfragen
In der API-Version 4-Referenz 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 Version 3 hat ein ids
-Parameter, der eine Tabellen-ID akzeptiert, das Format ga:XXXX
, wobei XXXX
die Ansichts- (Profil-)ID ist. In Version 4 ist im Feld viewId
des Anfragetexts eine Ansichts- (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
In der Analytics Reporting API v4 können Sie mehrere Zeiträume in einer einzelnen Anfrage angeben. Das Feld dateRanges
verwendet eine Liste von DateRange-Objekten.
In Version 3 geben Sie mit den Parametern start-date
und end-date
einen Zeitraum in einer Anfrage an.
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 Parameter metrics
von Version 3 entspricht dem Feld metrics
aus Version 4, das eine Liste von Messwertobjekten enthält.
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"
}],
...
}]
}
Dimensionen
Der Parameter dimensions
von Version 3 entspricht dem Feld dimensions
aus Version 4, das eine Liste von Dimension-Objekten 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 Parameter sort
von Version 3 entspricht dem Feld orderBys
aus Version 4, das eine Liste von OrderBy-Objekten enthält.
In v4 können Sie die Ergebnisse nach einer Dimension oder einem Messwert sortieren:
- Geben Sie den Namen oder Alias des Felds
fieldName
an. - Geben Sie die Sortierreihenfolge (
ASCENDING
oderDESCENDING
) über das 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 Quellen alphabetisch:
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"
}],
}]
}
Abtastebene
Der Parameter samplingLevel
von Version 3 entspricht dem Feld samplingLevel
aus Version 4. 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 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 Parameter segment
von Version 3 entspricht dem Feld segments
aus Version 4, das eine Liste von Segment-Objekten enthält.
Segment-IDs
Erstellen Sie in Version 4 ein Segment-Objekt und geben Sie seine ID über das Feld segmentId an.
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 v4 können Sie kompliziertere Segmentdefinitionen mit dem Feld segments
angeben, 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"]
}
}]
}]
}]
}
}]
}
}
}]
}]
Syntax von v3-Segmenten in v4
Das Feld segmentId in der v4 API unterstützt die Segmentsyntax in der v3 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
v4 verwendet dimensionFilterClauses
zum Filtern von Dimensionen und metricFilterClauses
zum Filtern von Messwerten. Ein dimensionFilterClauses
enthält eine Liste von DimensionFilter-Objekten und ein metricFilterClauses
eine Liste von MesswertFilter-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"]
}]
}]
}]
v3 Filtersyntax in v4
Obwohl das Feld filtersExpression in Version 4 die Syntax filters
in v3 unterstützt, können Sie Dimensionen und Messwerte mit dimensionFilterClauses
und metricFilterClauses
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 include-empty-rows
-Parameter von Version 3 entspricht dem Feld includeEmptyRows
in Version 4. Der Parameter V3 ist standardmäßig auf true und in Version 4 auf false gesetzt. 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
v4 verwendet die Felder pageToken
und pageSize
, um eine große Anzahl von Ergebnissen zu paginieren. Die pageToken
wird aus der Property 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
Version 4 der Analytics Reporting API unterstützt die meisten Standard-Abfrageparameter in der API Version 3 mit Ausnahme der Parameter userIp
und callback
.
In den folgenden Beispielen wird der Parameter quotaUser
in einer v3-Anfrage mit dem 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
Da Sie in Version 4 mehrere ReportRequest-Objekte in einer einzelnen HTTP-Anfrage senden können, erhalten Sie ein Array von Berichtsobjekten in der Antwort. Für jede eingereichte ReportRequest erhalten Sie einen entsprechenden Report in der Antwort.
Berichte
Ein Bericht v4 enthält drei Felder der obersten Ebene: columnHeader
, data
und nextPageToken
.
Da der Antworttext von Version 4 nicht auf alle Suchparameter Antworten enthält wie die Antwort von Version 3, muss die Clientanwendung diesen Parameter in die ReportRequest aufnehmen, um eine Antwort auf einen bestimmten Abfrageparameter zu erhalten.
Wir haben nextPageToken
bereits im Abschnitt Paginierung behandelt. Sehen wir uns also zuerst das Objekt columnHeader an.
Spaltenüberschrift
Die Spaltenüberschrift enthält eine Liste von benannten Dimensionen und einem MesswertHeader-Objekt, das eine Liste von MesswertHeaderEntry-Objekten enthält. Jedes MesswertHeaderEntry-Objekt gibt den Messwert name
und dessen type
(Währung, Prozentsatz usw.) an.
zum Formatieren der Ausgabe.
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
Die Core Reporting API v3 gibt die Berichtsdaten im rows-Array zurück, das die angeforderten Dimensionen und Messwerte enthält.
Version 4 der Analytics Reporting API 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
Bei Stichproben der Ergebnisse wird in der Core Reporting API Version 3 das boolesche Feld containsSampledData
zurückgegeben, für das der Wert true
festgelegt ist.
Die Analytics Reporting API v4 gibt keinen booleschen Wert zurück, wenn die Daten als Stichprobe verwendet werden. Stattdessen gibt die API die Felder samplesReadCounts
und samplingSpaceSizes
zurück.
Wenn keine Ergebnisse der Stichprobe vorliegen, sind diese Felder nicht definiert.
Das folgende Python-Beispiel zeigt, wie berechnet wird, ob ein Bericht Stichprobendaten 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 anhand von fast 500.000 Stichproben 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 v4 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 Fehlerantwortformat 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 v3 mit der entsprechenden Fehlerantwort in v4 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.\" }"
}
]
}
}