Migrationsanleitung

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

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 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 oder DESCENDING) über das Feld sortOrder 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:

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