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.


Einleitung

Mit der Google Analytics API und Google Apps Script können Sie in Google Tabellen auf Ihre Google Analytics-Daten zugreifen. Das ist so leistungsstark, weil Sie damit alle großartigen Funktionen von Google Tabellen zusammen mit Ihren Analysedaten nutzen können, z. B. einfache Freigabe-, Zusammenarbeits-, Diagramm- 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 die Apps Script-Umgebung für die Verwendung der Google Analytics API registrieren und konfigurieren. Nach der Konfiguration erfahren Sie, wie Sie mit der Management API eine Datenansichts- bzw. Profil-ID für den autorisierten Nutzer abrufen. Anschließend können Sie anhand der Datenansichts- bzw. Profil-ID die Core Reporting API abfragen, um die 250 wichtigsten Keywords für die mobile Suche von Google abzurufen. Abschließend 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 von Google Tabellen aus:

  1. Erstellen Sie eine Google Tabellen-Datei. Geben Sie ihm einen coolen Namen.
  2. Erstellen Sie ein neues Apps Script.
    1. Klicken Sie im Menü auf Erweiterungen > Apps Script.
    2. Wenn ein Menü eingeblendet wird, klicken Sie einfach auf Leeres Projekt.
    3. Geben Sie dem Projekt einen Namen. Achte darauf, dass der Name aussagekräftig ist.

Sobald Sie ein neues Skript haben, müssen Sie den Google Analytics-Dienst 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. Klicke unten im Dialogfeld auf den Link für die Google Developers Console.
  4. Klicken Sie in der neuen Console neben der Google Analytics API noch einmal auf den Schalter Ein/Aus. Nach der Aktivierung springt sie nach oben auf der Seite.
  5. Kehren Sie zum Skripteditor zurück und klicken Sie im Dialogfeld auf OK.

In einem kleinen gelben Dialogfeld sollte ein Pop-up eingeblendet werden, das Sie darüber informiert, dass ein neuer Google APIs-Dienst zu Ihrem Skript hinzugefügt wurde. Jetzt können Sie mit dem Schreiben Ihres ersten Skripts beginnen.

Mit der Google Analytics API arbeiten

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

  • Erste Ansicht (Profil) des autorisierten Nutzers abrufen
  • Fragen Sie die Core Reporting API nach Daten ab.
  • 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 also eine Abfrage für Berichtsdaten angeben, müssen Sie auch die ID der Datenansicht (des Profils) 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) eines Nutzers. Jede dieser Entitäten gehört zu einer Hierarchie. Sie können diese Hierarchie programmatisch durchlaufen, um eine Ansichts- 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 zuerst mit der Methode Analytics.Management.Accounts.list die Sammlung „Konten“ abgefragt. Wenn der autorisierte Nutzer Google Analytics-Konten hat, wird die ID des ersten Kontos abgerufen. Als Nächstes wird die Sammlung der Web-Properties abgefragt, indem die Methode Analytics.Management.Webproperties.list aufgerufen und die im vorherigen Schritt abgerufene Konto-ID an die Methode übergeben wird. Sind Web-Properties vorhanden, wird schließlich die Sammlung der Ansicht (Profil) mit der Methode Analytics.Management.Profiles.list abgefragt. Sowohl die Konto-ID als auch die Web-Property-ID werden als Parameter an diese Methode übergeben. Wenn Ansichten (Profile) vorhanden sind, wird die erste Ansicht (Profil) zurückgegeben.

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

Nachdem das Script zurückgegeben wurde, kann es Berichtsdaten abfragen.

Fragen Sie die Core Reporting API nach Daten ab.

Sobald Sie eine Datenansichts- bzw. Profil-ID haben, können Sie Google Analytics-Berichtsdaten mit der 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, während die optionalen Parameter als Objekt übergeben werden.

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 im vorherigen Schritt abgerufenen Ansichts- bzw. Profil-ID. 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.

Beim Ausführen der Methode Analytics.Data.Ga.get wird eine Anfrage an die Core Reporting API gesendet. Wenn ein Fehler auftritt, wird er im try...catch-Block abgefangen, 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 funktioniert mit der Methode outputToSpreadsheet. 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 angezeigt, in dem Sie aufgefordert werden, das Skript für den Zugriff auf Ihre Google Analytics-Kontodaten zu autorisieren.

Klicken Sie auf „Autorisieren“.

Wenn Sie darauf klicken, 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 können Sie das Skript auf Ihre Google Analytics-Daten zugreifen und es weiter ausführen.

Nachdem das Skript ausgeführt wurde, wechseln Sie zum 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 mit der Funktion „triggers“ ganz einfach.

Gehen Sie zum Automatisieren dieses Skripts wie folgt vor:

  • 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 so festgelegt werden: runDemo
    • Das Drop-down-Menü Events sollte auf Time-driven, Day timer und Midnight to 1am festgelegt sein.

Nach der Konfiguration wird dieses Skript jede Nacht ausgeführt und liefert Ihnen am Morgen aktuelle Daten.

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

Fazit

Sie haben den Zugriff auf Ihr Skript registriert und autorisiert. Sie haben die Management API mehrmals abgefragt, um eine Ansichts- bzw. Profil-ID abzurufen. Anschließend haben Sie mithilfe der Datenansichts- bzw. Profil-ID die Core Reporting API abgefragt, Daten abgerufen und in Google Tabellen ausgegeben.

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 manuelle Berichte reduzieren.

Hier finden Sie weitere hilfreiche Anleitungen, mit denen Sie die Google Analytics API und Google Apps Script optimal nutzen können: