Migrationsanleitung

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

Referenzdokumentation zu 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

Referenzdokumentation zu 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 oder DESCENDING) im Feld sortOrder 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:

Berichtszeilen

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.\" }"
   }
  ]
 }
}