Entwicklerleitfaden

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

Einführung

Mit der Real Time Reporting API können Sie Aktivitäten melden, die gerade auf Ihrer Property stattfinden. Um auf die Echtzeitdaten zuzugreifen, erstellen Sie eine Abfrage, die eine Ansicht (Profil) und mindestens einen Messwert angibt. Sie können auch zusätzliche Suchparameter wie Dimensionen und Filter hinzufügen, 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, sollten Sie sich mit der Real Time Reporting API vertraut machen. Dort finden Sie eine Einführung in die Real Time Reporting API und die darin enthaltenen Daten.

Voraussetzung

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

  • Eine vollständige Liste der Programmiersprachen-spezifischen Clientbibliotheken, die mit der API funktionieren, finden Sie auf der Seite Clientbibliotheken.
  • In der Referenzübersicht erfahren Sie, wie Sie die API allein (ohne Verwendung einer Clientbibliothek) verwenden, um Google Analytics-Daten abzurufen.

Jede Clientbibliothek stellt ein einzelnes Analysedienstobjekt bereit, um auf alle Daten der Real Time Reporting API zuzugreifen. So erstellen Sie ein Dienstobjekt:

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

Falls Sie diese Schritte noch nicht ausgeführt haben, lesen Sie bitte die Anleitung zur Hello Google Analytics API, in der die ersten Schritte zum Erstellen einer Google Analytics API-Anwendung beschrieben werden. Danach wissen Sie, wie Sie mit der API Google Analytics-Daten abrufen.

Real Time Reporting API verwenden

Eine Anwendung wird verwendet, um die Real Time Reporting API zu verwenden:

  1. Die Real Time Reporting API wird abgefragt.
  2. Verarbeitet die API-Antwort.

Real Time Reporting API abfragen

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

Nachdem Sie eine Abfrage definiert haben, rufen Sie die Methode execute auf, um die Abfrage an 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. Details zur Struktur und dem Format der API-Antwort finden Sie in der Real Time Reporting API-Referenz.

Wenn Fehler auftreten, gibt die API einen bestimmten Statuscode und eine Meldung zurück, in der der Fehler beschrieben wird. Alle Anwendungen sollten Fehler abfangen und verarbeiten. Eine detaillierte Liste der Fehler und Empfehlungen finden Sie unter Fehlerantworten.

Codebeispiele

Der Abschnitt Beispiele auf der Seite Echtzeitdaten: Abrufen enthält Beispielcode in verschiedenen Programmiersprachen, um die Real Time Reporting API abzufragen und die API-Antwort zu verarbeiten.

Abfrageeinschränkungen

Dies sind die Einschränkungen bei Real Time API-Abfragen:

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

    Da mit dem Messwert rt:activeUsers nur die Anzahl der Nutzer abgerufen wird, die aktuell auf der Website aktiv sind, solltest du rt:minutesAgo nicht zusammen mit rt:activeUsers verwenden. Das bedeutet, dass 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, gibt es Tageskontingente für die Real Time Reporting API, die von anderen Google Analytics APIs genutzt werden. Wenn Sie die Real Time Reporting API in kurzen Intervallen abfragen, erreichen Sie das Tageslimit sehr schnell. In diesem Fall funktionieren auch Anfragen von anderen Google Analytics APIs so lange, bis das Kontingent aktualisiert wird.

Hier sind einige Beispielimplementierungen, für die das Kontingent sehr schnell aufgebraucht werden kann:

  • Sie haben mehrere Echtzeit-Dashboards, die täglich Daten für eine einzelne Google Analytics-Datenansicht (Profil) in sehr kurzen Intervallen abfragen.
  • Sie haben eine Property mit vielen Nutzern und haben ein Echtzeit-Widget implementiert. Bei jeder Darstellung des Widgets durch einen Nutzer abfragen Sie Google Analytics direkt, anstatt einen Cache zu verwenden.

So minimieren Sie die Kontingentnutzung und verwalten sie effizient:

  • Serverseitiges Caching implementieren Wenn mehrere Nutzer eine Anfrage nach denselben Echtzeitdaten senden, sollten Sie eine im Cache gespeicherte Antwort zurückgeben, anstatt die Real Time Reporting API für jede Nutzeranfrage direkt abzufragen. Aktualisieren Sie dann im Cache regelmäßig die neuesten Echtzeitdaten, damit das Tageslimit nicht überschritten wird.
  • Kombinieren Sie mehrere Abfragen, indem Sie zusätzliche Dimensionen angeben und die Antwort server- oder clientseitig parsen.
  • Verlängern Sie das Zeitintervall, in dem Sie Echtzeitdaten anfordern.

Beispiel: Aktualisierungsintervall berechnen

Wenn Sie regelmäßig Anfragen für Echtzeitdaten stellen möchten, sollten Sie je nach erwarteter Nutzung ein angemessenes Aktualisierungsintervall auswählen.

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

Angenommen, Sie verwenden die Real Time Reporting API, um drei Echtzeit-Dashboards zu implementieren, die ganztägige Abfragen von Echtzeitdaten aus derselben Ansicht (Profil) ausführen. 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 länger als 65 Sekunden (86.400 / 1.333) sein, sodass die Gesamtzahl der täglichen Anfragen für die Ansicht (Profil) unter dem Tageslimit von 4.000 liegt.