Bericht erstellen

Dies ist ein Entwicklerleitfaden für die Analytics Reporting API v4. Eine ausführliche Referenz zur API finden Sie in der API-Referenz.

Hinweis: Diese API unterstützt keine Google Analytics 4-Properties (GA4). Verwenden Sie die Google Analytics Data API, um auf die neuen Berichtsfunktionen für GA4-Properties zuzugreifen.

Berichte

Version 4 der Analytics Reporting API bietet die Methode batchGet, um auf die Ressource Reports zuzugreifen. In den folgenden Abschnitten wird die Struktur des Anfragetexts für batchGet und die Struktur des Antworttexts von batchGet beschrieben.

Anfragetext

Wenn Sie mit der Analytics Reporting API Version 4 Daten anfordern möchten, müssen Sie ein ReportRequest-Objekt erstellen, das die folgenden Mindestanforderungen erfüllt:

• Eine gültige Ansichts-ID für das Feld viewId.
• Mindestens ein gültiger Eintrag im Feld dateRanges.
• Mindestens ein gültiger Eintrag im Feld metrics.

Wenn Sie eine Datenansichts-ID ermitteln möchten, können Sie die Methode Kontozusammenfassungen abfragen oder den Konto-Explorer verwenden. Wenn kein Zeitraum angegeben ist, wird der Standardzeitraum verwendet: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Hier sehen Sie eine Beispielanfrage mit den erforderlichen Pflichtfeldern:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

Für die Methode batchGet sind maximal fünf ReportRequest-Objekte zulässig. Alle Anfragen sollten die gleichen dateRange, viewId, segments, samplingLevel und cohortGroup haben.

Antworttext

Der Antworttext der API-Anfrage ist ein Array von Report-Objekten. Die Berichtsstruktur ist im ColumnHeader-Objekt definiert, das die Dimensionen und Messwerte sowie die zugehörigen Datentypen im Bericht beschreibt. Die Werte der Dimensionen und Messwerte werden im Feld Daten angegeben.

Hier sehen Sie eine Beispielantwort für die obige Beispielanfrage:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

Hinweis:Wenn beim Parsen des Antworttexts ein boolesches Feld nicht vorhanden ist, können Sie davon ausgehen, dass der Wert false ist. In der Antwort werden nur boolesche Felder mit dem Wert true angezeigt. Beispiel: Das Feld isDataGolden ist in der Antwort enthalten, wenn der Wert true ist.

Messwerte

Messwerte sind quantitative Messungen. Für jede Anfrage ist mindestens ein Messwertobjekt erforderlich.

Im folgenden Beispiel wird der Messwert Sessions der Methode batchGet bereitgestellt, um die Gesamtzahl der Sitzungen im angegebenen Zeitraum abzurufen:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

Mit dem Explorer für Dimensionen und Messwerte oder der Metadata API können Sie eine Liste der verfügbaren Dimensionen und Messwerte abrufen.

Filtern

Wenn Sie eine batchGet-Anfrage senden, können Sie festlegen, dass nur Messwerte zurückgegeben werden sollen, die bestimmte Kriterien erfüllen. Um Messwerte zu filtern, geben Sie im Anfragetext einen oder mehrere MetrikFilterClauses an und definieren Sie in jedem MetricFilterClause einen oder mehrere MetrikFilters. Geben Sie in jedem MetricFilter die Werte für Folgendes an:

• metricName
• not
• operator
• comparisonValue

{metricName} steht für den Messwert {operator}, den operator und {comparisonValue} für den Messwert comparisonValue. Der Filter funktioniert dann so:

if {metricName} {operator} {comparisonValue}
   return the metric

Wenn Sie true für not angeben, funktioniert der Filter so:

if {metricName} {operator} {comparisonValue}
   do not return the metric

Im folgenden Beispiel gibt batchGet nur Seitenaufrufe zurück, deren Wert größer als 2 ist:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

Ausdrücke

Ein Messwertausdruck ist ein mathematischer Ausdruck, den Sie für vorhandene Messwerte definieren. Er funktioniert wie dynamische berechnete Messwerte. Sie können einen Alias für den Messwertausdruck definieren. Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

Hinweis: Sie können auch die Formatierungstypen für die von Ihnen definierten Messwertausdrücke festlegen.

Bestellung

So sortieren Sie die Ergebnisse nach einem Messwert:

• Geben Sie den Namen oder Alias im Feld fieldName ein.
• Geben Sie die Sortierreihenfolge (ASCENDING oder DESCENDING) über das Feld sortOrder an.

Im folgenden Beispiel gibt batchGet die Messwerte zuerst nach Sitzungen und dann in absteigender Reihenfolge nach Seitenaufrufen zurück:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

Dimensionen

Mit Dimensionen werden Eigenschaften von Ihren Nutzern sowie deren Sitzungen und Aktionen beschrieben. Mit der Dimension „Stadt“ wird beispielsweise ein Merkmal einer Sitzung beschrieben und die Stadt (&is; Paris) angegeben, aus der die jeweilige Sitzung stammt. In einer batchGet-Anfrage können Sie null oder mehr dimension-Objekte angeben. Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

Filtern

Wenn Sie eine batchGet-Anfrage senden, können Sie festlegen, dass nur Dimensionen zurückgegeben werden sollen, die bestimmte Kriterien erfüllen. Um Dimensionen zu filtern, geben Sie im Anfragetext eine oder mehrere DimensionsFilterClauses an und definieren Sie in jedem DimensionsFilterClause einen oder mehrere DimensionsFilters. Geben Sie in jedem DimensionsFilters die Werte für Folgendes an:

• dimensionName
• not
• operator
• expressions
• caseSensitive

Dabei steht {dimensionName} für die Dimension {operator}, operator und {expressions} für expressions. Der Filter funktioniert dann so:

if {dimensionName} {operator} {expressions}
    return the dimension

Wenn Sie true für not angeben, funktioniert der Filter so:

if {dimensionName} {operator} {expressions}
    do not return the dimension

Im folgenden Beispiel gibt batchGet Seitenaufrufe und Sitzungen in einem Chrome-Browser zurück:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

Bestellung

So sortieren Sie die Ergebnisse nach einem Dimensionswert:

• Geben Sie den Namen im Feld fieldName ein.
• Geben Sie die Sortierreihenfolge (ASCENDING oder DESCENDING) über das Feld sortOrder an.

Die folgende batchGet gibt beispielsweise die Dimensionen zurück, die nach Land und dann nach Browser sortiert sind:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

Histogramm-Buckets

Bei Dimensionen mit Ganzzahlwerten ist es einfacher, die Eigenschaften zu verstehen, indem die Werte in Bereiche zusammengefasst werden. Verwenden Sie das Feld histogramBuckets, um die Bereiche für die resultierenden Buckets zu definieren, und geben Sie HISTOGRAM_BUCKET als Bestelltyp an. Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

Hinweis: Unter Request Composer finden Sie eine Demoanwendung, in der einige dieser Funktionen verwendet werden.

Mehrere Zeiträume

Mit der Google Analytics Reporting API Version 4 können Sie Daten aus mehreren Zeiträumen in einer einzelnen Anfrage abrufen. Unabhängig davon, ob in Ihrer Anfrage ein oder zwei Zeiträume angegeben sind, werden die Daten im Objekt dateRangeValue zurückgegeben. Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

Deltareihenfolge

Wenn Sie Messwerte in zwei Zeiträumen anfordern, können Sie die Ergebnisse nach der Differenz zwischen den Messwerten in den Zeiträumen sortieren. Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

Verhalten der Datumsdimension

Wenn Sie eine mit Datum oder Uhrzeit verbundene Dimension anfordern, enthält das DateRangeValue-Objekt nur Werte für die Daten, die in die jeweiligen Zeiträume fallen. Alle anderen Werte, die nicht in den angegebenen Zeiträumen enthalten sind, sind 0.

Nehmen wir als Beispiel eine Anfrage für die Dimension ga:date und den Messwert ga:sessions in zwei Zeiträumen: Januar und Februar. In der Antwort auf die angeforderten Daten im Januar sind die Werte im Februar 0 und in der Antwort für die angeforderten Daten im Februar 0.

Bericht für Januar

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

Februar-Bericht

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

Segmente

Wenn Sie eine Teilmenge Ihrer Analytics-Daten anfordern möchten, können Sie Segmente verwenden. Sie können beispielsweise Nutzer aus einem bestimmten Land oder einer bestimmten Stadt in einem Segment definieren und Nutzer, die einen bestimmten Bereich Ihrer Website in einem anderen Segment besuchen. Filter geben nur Zeilen zurück, die eine Bedingung erfüllen, während Segmente eine Teilmenge von Nutzern, Sitzungen oder Ereignissen zurückgeben, die die Bedingungen erfüllen, die die Segmente enthalten.

Wenn Sie eine Anfrage mit Segmenten stellen, müssen folgende Voraussetzungen erfüllt sein:

• Alle ReportRequest innerhalb einer batchGet-Methode müssen identische Segmentdefinitionen enthalten.
• Fügen Sie der Liste der Dimensionen ga:segment hinzu.

Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

Weitere Beispielanfragen mit Segmenten finden Sie unter Beispiele.

Segment-ID

Verwenden Sie das Feld segmentId, um Segmente anzufordern. Segmente können nicht sowohl mit segmentId als auch mit dynamicSegment angefordert werden.

Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

Hinweis: Das Feld segmentId unterstützt auch die Syntax für Segmente in der Core Reporting API V3. Weitere Informationen finden Sie im Migrationsleitfaden.

Probenahme

Hinweis: Bei Analytics 360-Konten können Sie mithilfe der Funktion Ressourcenbasiertes Kontingent höhere Schwellenwerte für die Stichprobenerhebung verwenden, wenn Sie die Analytics Reporting API verwenden.

Stichproben können sich auf die Ergebnisse Ihrer Daten auswirken und sind ein häufiger Grund dafür, dass die von der API zurückgegebenen Werte nicht mit der Weboberfläche übereinstimmen. Legen Sie im Feld samplingLevel die gewünschte Stichprobengröße fest.

• Legen Sie den Wert auf SMALL fest, um eine schnelle Antwort mit kleinerer Stichprobengröße zu erhalten.
• Setzen Sie den Wert auf LARGE, um eine genauere, aber langsamere Antwort zu erhalten.
• Setzen Sie den Wert auf DEFAULT, um eine Antwort zu schaffen, bei der Geschwindigkeit und Genauigkeit berücksichtigt werden.

Beispiel:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

Hinweis:Jeder ReportRequest innerhalb einer batchGet-Methode muss dieselbe samplingLevel-Definition enthalten.

Wenn ein Bericht Stichprobendaten enthält, gibt die Analytics Reporting API Version 4 die Felder samplesReadCounts und samplingSpaceSizes zurück. Wenn keine Ergebnisse der Stichprobe vorliegen, sind diese Felder nicht definiert.

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"],
      }
    }
  ]
}

Seitenumbruch

Version 4 der Analytics Reporting API verwendet die Felder pageToken und pageSize, um durch Antwortergebnisse zu blättern, die mehrere Seiten umfassen. Sie erhalten pageToken aus dem Parameter nextPageToken in der Antwort auf die reports.batchGet-Anfrage:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

Hinweis: Theoretisch kann nextPageToken ein beliebiger String sein, aber in den meisten Fällen ist er ein nullbasierter Zeilenindex. Verwende den Wert nextPageToken für das Feld pageToken, um eine korrekte Paginierung sicherzustellen.

Weitere Informationen

Nachdem du dich mit den Grundlagen des Erstellens eines Berichts vertraut gemacht hast, kannst du dir die erweiterten Funktionen von API Version 4 ansehen.