Automatisierter Zugriff auf Google Analytics-Daten in Google Tabellen

Nick Mihailovski, Google Analytics-API-Team – August 2012

In dieser Anleitung wird beschrieben, wie Sie mit Apps Script in Google Tabellen auf die Management API und die Core Reporting API zugreifen.


Einführung

Sie können die Google Analytics API und Google Apps Script verwenden, um in Google Tabellen auf Ihre Google Analytics-Daten zuzugreifen. Das ist praktisch, weil Sie damit alle praktischen Funktionen von Google Tabellen zusammen mit Ihren Analysedaten nutzen können, z. B. einfache Freigabe, Zusammenarbeit, Diagramme und Visualisierungstools.

In dieser Anleitung wird der Code beschrieben, der erforderlich ist, um mit Google Apps Script auf Ihre Google Analytics-Daten in Google Tabellen zuzugreifen.

Überblick

In dieser Anleitung erfahren Sie, wie Sie sich registrieren und die Apps Script-Umgebung für die Verwendung der Google Analytics API konfigurieren. Nach der Konfiguration erfahren Sie in dieser Anleitung, wie Sie mit der Management API eine Datenansichts-ID (Profil-ID) für den autorisierten Nutzer abrufen. Anschließend erfahren Sie, wie Sie mithilfe der Datenansichts-ID (Profil-ID) die Core Reporting API abfragen, um die Top-250-Keywords für die mobile Suche von Google abzurufen. Schließlich werden die Ergebnisse in eine Google-Tabelle eingefügt. Sobald Sie Daten haben, wird in der Anleitung auch erläutert, wie Sie das Abrufen von Daten automatisieren.

Wenn Sie eine Anwendung mit der Google Analytics API und Apps Script erstellen, führen Sie in der Regel die folgenden Schritte aus:

  • Google Analytics APIs in Google Tabellen aktivieren
  • Mit den Google Analytics APIs arbeiten

Sehen wir uns die einzelnen Schritte im Detail an.

Google Analytics API in Apps Script aktivieren

So aktivieren Sie den Zugriff auf Ihre Google Analytics-Daten in Google Tabellen:

  1. Erstellen Sie eine Google Tabellen-Datei. Gib ihm einen coolen Namen.
  2. Erstellen Sie ein neues Apps Script.
    1. Klicken Sie im Menü auf Erweiterungen > Apps Script.
    2. Falls ein Menü angezeigt wird, klicken Sie einfach auf Leeres Projekt.
    3. Geben Sie dem Projekt einen Namen. Achte darauf, dass er einen coolen Namen hat.

Sobald ein neues Skript erstellt wurde, müssen Sie den Google Analytics Service aktivieren.

  1. Wählen Sie im Script-Editor Ressourcen > Erweiterte Google-Dienste... aus.
  2. Klicken Sie im angezeigten Dialogfeld neben der Google Analytics API auf den Schalter Ein/Aus.
  3. Klicken Sie unten im Dialogfeld auf den Link zur Google Developers Console.
  4. Klicken Sie in der neuen Konsole erneut auf den Schalter Ein/Aus neben der Google Analytics API. Nach der Aktivierung springt sie an den Anfang der Seite.
  5. Kehren Sie zum Skripteditor zurück und klicken Sie im Dialogfeld auf OK.

In einem kleinen gelben Dialogfeld sollte angezeigt werden, dass Ihrem Skript ein neuer Google APIs-Dienst hinzugefügt wurde. Jetzt können Sie mit dem Schreiben Ihres ersten Skripts beginnen.

Mit der Google Analytics API arbeiten

Mit dem Skript in dieser Anleitung wird die Google Analytics API nach den 250 wichtigsten Suchbegriffen für die mobile Google-Suche abgefragt und die Ergebnisse werden in Google Tabellen ausgegeben. Zu diesem Zweck durchläuft das Skript die folgenden Schritte:

  • Rufen Sie die erste Datenansicht (Profil) des autorisierten Nutzers ab.
  • Core Reporting API nach Daten abfragen
  • Fügen Sie Daten in eine Tabellenkalkulation ein.

Fügen Sie dem leeren Projekt die folgende Funktion hinzu.

function runDemo() {
  try {

    var firstProfile = getFirstProfile();
    var results = getReportDataForProfile(firstProfile);
    outputToSpreadsheet(results);

  } catch(error) {
    Browser.msgBox(error.message);
  }
}

Im obigen Code wird ein try...catch-Block verwendet, um API-Fehler zu verarbeiten. Wenn Fehler auftreten, wird die Programmausführung angehalten und der Fehler wird in einem Meldungsfeld angezeigt. Im try-Block wird eine Funktion verwendet, um jeden der Schritte auszuführen, die das Skript durchläuft. Fügen wir nun den Code für jede dieser Funktionen hinzu.

Erste Ansicht (Profil) des autorisierten Nutzers abrufen

In Google Analytics gehört jeder Bericht zu einer Datenansicht (Profil) und wird durch eine Datenansichts-ID (Profil) identifiziert. Wenn Sie eine Abfrage für Berichtsdaten angeben, müssen Sie also auch die ID der Datenansicht (Profil) der Datenansicht (des Profils) angeben, aus der Sie Daten abrufen möchten.

Die Google Analytics Management API bietet Zugriff auf alle Konten, Web-Properties und Datenansichtsentitäten (Profil), die einem Nutzer gehören. Jede dieser Entitäten gehört zu einer Hierarchie. Sie können diese Hierarchie programmatisch durchlaufen, um eine Datenansichts- bzw. Profil-ID für den autorisierten Nutzer abzurufen.

Die zweite Funktion, die wir schreiben, durchläuft die Management API-Hierarchie und gibt die erste Ansicht (Profil) des Nutzers zurück. Kopieren Sie den folgenden Code und fügen Sie ihn in Ihr Apps Script-Projekt ein:

function getFirstProfile() {
  var accounts = Analytics.Management.Accounts.list();
  if (accounts.getItems()) {
    var firstAccountId = accounts.getItems()[0].getId();

    var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
    if (webProperties.getItems()) {

      var firstWebPropertyId = webProperties.getItems()[0].getId();
      var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);

      if (profiles.getItems()) {
        var firstProfile = profiles.getItems()[0];
        return firstProfile;

      } else {
        throw new Error('No views (profiles) found.');
      }
    } else {
      throw new Error('No webproperties found.');
    }
  } else {
    throw new Error('No accounts found.');
  }
}

In dieser Funktion wird die Kontensammlung zuerst mit der Methode Analytics.Management.Accounts.list abgefragt. Wenn der autorisierte Nutzer Google Analytics-Konten hat, wird die ID des ersten Kontos abgerufen. Als Nächstes wird die Web-Property-Sammlung abgefragt, indem die Methode Analytics.Management.Webproperties.list aufgerufen und die im vorherigen Schritt abgerufene Konto-ID übergeben wird. Falls Web-Properties vorhanden sind, wird schließlich die Sammlung (Profil) mit der Methode Analytics.Management.Profiles.list abgefragt. Sowohl die Konto-ID als auch die ID einer Web-Property werden als Parameter an diese Methode übergeben. Falls Datenansichten vorhanden sind, wird die erste Datenansicht (Profil) zurückgegeben.

Wenn ein API-Fehler auftritt oder die API-Antwort keine Ergebnisse enthält, wird ein Fehler mit der Meldung ausgegeben, dass keine Ergebnisse gefunden wurden. Der catch-Block in der obigen runDemo-Funktion erfasst diesen Fehler und gibt die Nachricht an den Nutzer aus.

Sobald das Skript eine Abfrage zurückgegeben hat, kann es Berichtsdaten abfragen.

Core Reporting API nach Daten abfragen

Sobald Sie eine Datenansichts-ID (Profil-ID) haben, können Sie Google Analytics-Berichtsdaten über die Core Reporting API abfragen. In diesem Abschnitt erfahren Sie, wie Sie diese API mithilfe von Apps Script abfragen.

Fügen Sie Ihrem Apps Script-Projekt den folgenden Code hinzu:

function getReportDataForProfile(firstProfile) {

  var profileId = firstProfile.getId();
  var tableId = 'ga:' + profileId;
  var startDate = getLastNdays(14);   // 2 weeks (a fortnight) ago.
  var endDate = getLastNdays(0);      // Today.

  var optArgs = {
    'dimensions': 'ga:keyword',              // Comma separated list of dimensions.
    'sort': '-ga:sessions,ga:keyword',       // Sort by sessions descending, then keyword.
    'segment': 'dynamic::ga:isMobile==Yes',  // Process only mobile traffic.
    'filters': 'ga:source==google',          // Display only google traffic.
    'start-index': '1',
    'max-results': '250'                     // Display the first 250 results.
  };

  // Make a request to the API.
  var results = Analytics.Data.Ga.get(
      tableId,                    // Table id (format ga:xxxxxx).
      startDate,                  // Start-date (format yyyy-MM-dd).
      endDate,                    // End-date (format yyyy-MM-dd).
      'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
      optArgs);

  if (results.getRows()) {
    return results;

  } else {
    throw new Error('No views (profiles) found');
  }
}

function getLastNdays(nDaysAgo) {
  var today = new Date();
  var before = new Date();
  before.setDate(today.getDate() - nDaysAgo);
  return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}

Im ersten Teil des Codes wird eine Core Reporting API-Abfrage mithilfe der Methode Analytics.Data.Ga.get erstellt. Die Methode akzeptiert eine Reihe von Parametern, die den abzurufenden Berichtstyp angeben. Jede Core Reporting API-Abfrage besteht aus einer Reihe von erforderlichen und optionalen Parametern. Die erforderlichen Parameter werden als Parameter an die Methode übergeben. Die optionalen Parameter werden als Objekt übergeben.

Der Parameter table ID ist erforderlich und wird durch Kombination des Präfixes ga: mit der ID der Ansicht (Profil) gebildet. Der Code erstellt die Tabellen-ID anhand der Datenansichts-ID (Profil-ID), die im vorherigen Schritt abgerufen wurde. Das Start- und Enddatum sind ebenfalls erforderlich und geben den Zeitraum der abzurufenden Daten an. Beide werden anhand des heutigen Datums mit der Funktion getLastNdays berechnet. Schließlich werden alle optionalen Parameter mithilfe des optArgs-Objekts an die Funktion übergeben.

Wenn die Methode Analytics.Data.Ga.get ausgeführt wird, wird eine Anfrage an die Core Reporting API gesendet. Wenn ein Fehler auftritt, wird er in den try...catch-Block aufgenommen, der in der äußeren runDemo-Methode definiert ist. Wenn die Anfrage erfolgreich war, werden die Ergebnisse zurückgegeben.

Daten in eine Tabellenkalkulation einfügen

Der letzte Schritt in unserem Skript besteht darin, die Ergebnisse aus der Core Reporting API in Google Tabellen auszugeben. Dies wird mit der Methode outputToSpreadsheet erledigt. Fügen Sie Ihrem Projekt den folgenden Code hinzu:

function outputToSpreadsheet(results) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Print the headers.
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  sheet.getRange(1, 1, 1, headerNames.length)
      .setValues([headerNames]);

  // Print the rows of data.
  sheet.getRange(2, 1, results.getRows().length, headerNames.length)
      .setValues(results.getRows());
}

Diese Funktion fügt zuerst ein neues Tabellenblatt in die aktive Tabellenkalkulation ein. Anschließend werden alle Kopf- und Berichtsdaten in das Tabellenblatt eingefügt. Weitere Tipps zum Einfügen von Daten in Google Tabellen finden Sie in der Anleitung Daten in Tabellen speichern unter Daten aus JavaScript-Objekten in eine Tabelle schreiben.

Skript ausführen

Sobald Sie den gesamten Code zum Projekt hinzugefügt haben, können Sie es ausführen.

  • Wählen Sie in der Symbolleiste des Skripteditors im Drop-down-Menü „Funktion auswählen“ die Option runDemo aus.
  • Klicken Sie dann auf die Schaltfläche play.

Wenn Sie das Skript zum ersten Mal ausführen, wird ein Pop-up-Fenster eingeblendet, in dem Sie aufgefordert werden, das Skript für den Zugriff auf Ihre Google Analytics-Kontodaten zu autorisieren.

Klicken Sie auf „Autorisieren“.

Nach dem Anklicken wird eine neue, auf google.com gehostete Seite geöffnet und Sie werden aufgefordert, diesem Skript Zugriff auf Ihre Daten zu gewähren. Sobald Sie auf „Zulassen“ klicken, werden Sie zu einer Bestätigungsseite weitergeleitet. Jetzt kann das Skript auf Ihre Google Analytics-Daten zugreifen und es kann weiter ausgeführt werden.

Nachdem das Skript ausgeführt wurde, klicken Sie auf das Fenster mit Google Tabellen. Sie sollten alle von der API zurückgegebenen Keyword-Daten oder ein Nachrichtenfeld mit einer Fehlermeldung sehen.

Script automatisieren

Jetzt sollten Sie über ein Skript verfügen, mit dem die Google Analytics API abgefragt wird. Vielleicht möchten Sie dieses Skript jetzt automatisieren, um jede Nacht neue Daten abzurufen. Mit Apps Script ist die Automatisierung mithilfe der Funktion „triggers“ ein Kinderspiel.

Gehen Sie wie folgt vor, um dieses Skript zu automatisieren:

  • Klicken Sie in der Symbolleiste des Skripteditors auf Resources -> All your triggers....
  • Klicken Sie auf Add a new trigger. Das Dialogfeld „Trigger“ wird angezeigt.
  • Konfigurieren Sie den Trigger so, dass die Methode runDemo jede Nacht ausgeführt wird
    • Das Drop-down-Menü „Run“ muss auf „runDemo“ festgelegt sein
    • Das Drop-down-Menü Events muss auf Time-driven, Day timer und Midnight to 1am festgelegt sein.

Nach der Konfiguration wird dieses Skript jede Nacht ausgeführt. So erhalten Sie morgens aktuelle Daten.

Wenn Fehler nachts auftreten, sollten Sie benachrichtigt werden. Mit Apps Script können Sie außerdem eine E-Mail-Benachrichtigung senden, wenn Fehler auftreten. Klicken Sie dazu im Dialogfeld „Trigger“ auf den Link notifications. Ein neues Dialogfeld wird angezeigt, in dem Sie festlegen können, an welche E-Mail-Adresse Fehler gesendet werden sollen.

Fazit

Sie haben Ihr Skript erfolgreich registriert und autorisiert. Sie haben die Management API mehrmals abgefragt, um eine Datenansichts- bzw. Profil-ID abzurufen. Anschließend haben Sie mithilfe der Datenansichts-ID (Profil-ID) die Core Reporting API abgefragt, um Daten abzurufen und in Google Tabellen auszugeben.

Mit den in der Anleitung beschriebenen Techniken können Sie komplexere Analysen durchführen, detailliertere Informationen erhalten, benutzerdefinierte Dashboards erstellen und den Zeitaufwand für das Ausführen manueller Berichte reduzieren.

Hier einige weitere coole Anleitungen, die Ihnen dabei helfen können, die Google Analytics API und Google Apps Script noch besser zu nutzen: