Entwicklerleitfaden

In diesem Dokument wird beschrieben, wie Sie mit der Real Time Reporting API Google Analytics-Daten abrufen.

Hinweis:Diese API unterstützt keine GA4-Properties. Verwenden Sie die Funktion für Echtzeitberichte der Google Analytics Data API, um auf GA4-Properties zuzugreifen.

Einleitung

Mit der Real Time Reporting API können Sie Berichte zu Aktivitäten erstellen, die auf Ihrer Property gerade stattfinden. Für den Zugriff auf die Echtzeitdaten erstellen Sie eine Abfrage, die eine Datenansicht (Profil) und mindestens einen Messwert angibt. Sie können auch zusätzliche Abfrageparameter wie Dimensionen und Filter angeben, um die Abfrage zu verfeinern. Diese Abfrage wird an die Real Time Reporting API gesendet, die die Daten in Form einer Tabelle zurückgibt.

Wenn Sie die API noch nicht kennen, finden Sie unter Real Time Reporting API – Übersicht eine Einführung in die Real Time Reporting API und die darin bereitgestellten Daten.

Vorbereitung

Bevor Sie die Real Time Reporting API zum Abrufen von Google Analytics-Daten verwenden, sollten Sie Folgendes beachten:

• Auf der Seite Clientbibliotheken finden Sie eine vollständige Liste der programmiersprachenspezifischen Clientbibliotheken, die mit der API funktionieren.
• Im Referenzhandbuch erfahren Sie, wie Sie Google Analytics-Daten mit der API allein (ohne Clientbibliothek) abrufen.

Jede Clientbibliothek stellt ein einzelnes Analysedienstobjekt für den Zugriff auf alle Daten der Real Time Reporting API bereit. So erstellen Sie ein Dienstobjekt:

1. Registrieren Sie Ihre Anwendung in der Google API Console.
2. Autorisieren Sie den Zugriff auf Google Analytics-Daten.
3. Erstellen Sie ein Analytics-Dienstobjekt.

Falls Sie diese Schritte noch nicht ausgeführt haben, beenden Sie bitte die Anleitung zur Hello Google Analytics API, die Sie durch die ersten Schritte zum Erstellen einer Google Analytics API-Anwendung führt. Anschließend wissen Sie, wie Sie mit der API Google Analytics-Daten abrufen.

Real Time Reporting API verwenden

Zur Verwendung der Real Time Reporting API muss eine Anwendung folgende Voraussetzungen erfüllen:

1. Fragt die Real Time Reporting API ab.
2. Verarbeitet die API-Antwort.

Real Time Reporting API abfragen

Das Analysedienstobjekt bietet eine Methode zum Erstellen einer Real Time Reporting API-Abfrage. Ausführliche Informationen zu den Abfrageparametern und Daten für die API finden Sie unter:

• Eine vollständige Liste aller Abfrageparameter für die get-Methode der Real Time Reporting API finden Sie in der Referenz zur Real Time Reporting API.
• Eine Liste von Abfrageparametern, die mit allen Methoden und Ressourcen verwendet werden können, finden Sie in der Referenz zu Standardabfrageparametern.
• Auf der Referenzseite zu Dimensionen und Messwerten finden Sie eine Liste der Daten, die über Google Analytics abgerufen werden können.

Nachdem Sie eine Abfrage definiert haben, rufen Sie ihre execute-Methode auf, um sie an die Google Analytics-Server zu senden.

API-Antwort verarbeiten

Wenn eine Abfrage an die Real Time Reporting API erfolgreich ist, gibt die API die angeforderten Daten als Teil einer Echtzeitdatenressource zurück. Weitere Informationen zu Struktur und Format der API-Antworten finden Sie in der Referenz zur Real Time Reporting API.

Wenn Fehler auftreten, gibt die API einen bestimmten Statuscode und eine Fehlermeldung zurück. Alle Anwendungen sollten Fehler erkennen und verarbeiten. Eine detaillierte Liste der Fehler und Empfehlungen für Wiederholungsversuche finden Sie unter Fehlerantworten .

Codebeispiele

Im Abschnitt Beispiele auf der Seite Real Time Data: get finden Sie Beispielcode in verschiedenen Programmiersprachen, um die Real Time Reporting API abzufragen und die API-Antwort zu verarbeiten.

Abfrageeinschränkungen

Für Real Time API-Abfragen gelten folgende Einschränkungen:

• Wenn der Messwert rt:activeUsers in einer Abfrage mit den folgenden Dimensionsfiltern enthalten ist, werden nur der Operator AND und der Übereinstimmungstyp (==) unterstützt.
  • rt:goalId
  • rt:eventAction
  • rt:eventCategory
  • rt:eventLabel

  Da mit dem Messwert rt:activeUsers nur die Anzahl der derzeit auf der Website aktiven Nutzer abruft, sollten Sie rt:minutesAgo nicht mit rt:activeUsers verwenden. Das heißt, rt:activeUsers impliziert, dass rt:minutesAgo 0 ist.

• Messwertfilter werden nicht unterstützt.
• Der Parameter fields wird nicht unterstützt.

Kontingentverwaltung

Wie unter Limits und Kontingente beschrieben, gelten für die Real Time Reporting API Tageskontingente, die auch für andere Google Analytics APIs genutzt werden. Wenn Sie die Real Time Reporting API in kurzen Intervallen abfragen, erreichen Sie die täglichen Kontingentlimits sehr schnell. In diesem Fall funktionieren auch Anfragen von anderen Google Analytics APIs nicht mehr, bis das Kontingent erneuert wird.

Hier einige Beispielimplementierungen, die das Kontingent sehr schnell aufbrauchen:

• Sie haben mehrere Echtzeit-Dashboards, die Daten für eine einzelne Google Analytics-Datenansicht (Profil) täglich in sehr kurzen Intervallen abfragen.
• Sie haben eine Property mit vielen Nutzern und haben ein Echtzeit-Widget implementiert. Jedes Mal, wenn das Widget einem Nutzer angezeigt wird, stellen Sie eine direkte Abfrage aus Google Analytics statt, anstatt einen Cache zu verwenden.

So minimieren Sie die Kontingentnutzung und verwalten sie effizient:

• Implementieren Sie das serverseitige Caching. Wenn mehrere Nutzer dieselben Echtzeitdaten anfragen, sollten Sie eine im Cache gespeicherte Antwort zurückgeben, anstatt die Real Time Reporting API direkt für jede einzelne Nutzeranfrage abzufragen. Aktualisieren Sie dann den Cache regelmäßig mit den neuesten Echtzeitdaten in einem angemessenen Aktualisierungsintervall, um eine Überschreitung der täglichen Kontingentlimits zu vermeiden.
• Kombinieren Sie mehrere Abfragen, indem Sie zusätzliche Dimensionen angeben, und parsen Sie die Antwort auf Server- oder Clientseite.
• Erhöhen Sie das Zeitintervall, in dem Sie Echtzeitdaten anfordern.

Mit dem Google Analytics-SuperProxy können viele Implementierungsdetails für die Arbeit mit der Real Time Reporting API für die Authentifizierung, das Caching und die Umwandlung von API-Antworten in Formate verarbeitet werden, die direkt mit Visualisierungs- und Diagrammbibliotheken verwendet werden können. Weitere Informationen finden Sie in der Übersicht zu Google Analytics-SuperProxy.

Beispiel: Aktualisierungsintervall berechnen

Wenn Sie regelmäßige Anfragen für Echtzeitdaten erwarten, sollten Sie ein angemessenes Aktualisierungsintervall basierend auf Ihrer erwarteten Nutzung auswählen.

Beispiel: Für eine einzelne Google Analytics-Datenansicht (Profil) gilt ein Kontingentlimit von 10.000 Anfragen pro Tag. Wenn Sie an einem Tag davon ausgehen, 6.000 Abfragen an die Core Reporting API für eine einzelne Datenansicht (ein Profil) zu senden, haben Sie ein Kontingent von 4.000 verbleibenden Anfragen für diese Datenansicht (Profil).

Angenommen, Sie möchten die Real Time Reporting API verwenden, um drei Echtzeit-Dashboards zu implementieren, in denen ganztägig Echtzeitdaten aus derselben Datenansicht (Profil) abgefragt werden. Jedes Dashboard kann etwa 1.333 Abfragen pro Tag ausführen (4.000 Abfragen / 3 Dashboards). Ein Tag hat 86.400 Sekunden. Daher muss das Aktualisierungsintervall für jedes Dashboard größer als 65 Sekunden (86.400 / 1.333) sein, damit die Gesamtzahl der täglichen Anfragen für die Ansicht (Profil) unter dem Tageslimit von 4.000 liegt.