Migrationsanleitung

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

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

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