Zautomatyzowany dostęp do danych Google Analytics w Arkuszach Google

Nick Mihailovski, zespół Google Analytics API – sierpień 2012 r.

Z tego samouczka dowiesz się, jak uzyskać dostęp do interfejsów API zarządzania i podstawowego raportowania w Arkuszach Google przy użyciu Apps Script.


Wstęp

Aby uzyskać dostęp do danych Google Analytics w Arkuszach Google, możesz użyć interfejsu Google Analytics API i Google Apps Script. Zapewnia to bardzo duże możliwości, ponieważ wraz z danymi analitycznymi można używać wszystkich wspaniałych funkcji Arkuszy Google, takich jak łatwe udostępnianie, współpraca, tworzenie wykresów i wizualizacja.

W tym samouczku omawiamy kod wymagany do uzyskiwania dostępu do danych Google Analytics w Arkuszach Google za pomocą Google Apps Script.

Przegląd

W tym samouczku pokazujemy, jak zarejestrować i skonfigurować środowisko Apps Script pod kątem interfejsu Google Analytics API. Po skonfigurowaniu tej czynności samouczek przeprowadzi Cię przez proces pobierania identyfikatora widoku (profilu) autoryzowanego użytkownika za pomocą interfejsu API zarządzania Google Analytics. Następnie jak użyć identyfikatora widoku (profilu) do wysłania zapytania do interfejsu API podstawowego raportowania, aby pobrać z Google 250 najczęstszych słów kluczowych w wyszukiwarce mobilnej. Na koniec wyniki zostaną wstawione do arkusza kalkulacyjnego Google. Gdy będziesz już mieć dane, z samouczka dowiesz się też, jak zautomatyzować ich pobieranie.

Gdy tworzysz aplikację za pomocą interfejsu Google Analytics API i Apps Script, musisz zwykle wykonać te czynności:

  • Włączanie interfejsów Google Analytics API w Arkuszach Google
  • Korzystanie z interfejsów API Google Analytics

Przeanalizujmy szczegółowo każdy krok.

Włączanie interfejsu Google Analytics API w Apps Script

Aby włączyć dostęp do danych Google Analytics z poziomu Arkuszy Google, wykonaj te czynności:

  1. Utwórz plik Arkuszy Google. Wymyśl jakąś fajną nazwę.
  2. Utwórz nowy skrypt Apps Script.
    1. W menu kliknij Rozszerzenia > Apps Script.
    2. Jeśli pojawi się menu, kliknij Pusty projekt.
    3. Nazwij projekt. Upewnij się, że ma ciekawą nazwę.

Gdy będziesz już mieć nowy skrypt, musisz włączyć usługę Google Analytics.

  1. W edytorze skryptów wybierz Zasoby > Zaawansowane usługi Google...
  2. W wyświetlonym oknie kliknij przełącznik wł./wył. obok interfejsu Google Analytics API.
  3. U dołu okna kliknij link do Google Developers Console.
  4. W nowej konsoli ponownie kliknij przełącznik wł./wył. obok interfejsu API Google Analytics. (Po włączeniu przeskoczy na górę strony).
  5. Wróć do edytora skryptów i w oknie kliknij OK.

Powinno pojawić się żółte okno z informacją, że do skryptu została dodana nowa usługa interfejsów API Google. Możesz teraz zacząć pisać swój pierwszy skrypt.

Korzystanie z interfejsu Google Analytics API

Ten skrypt z tego samouczka wysyła zapytanie do interfejsu Google Analytics API, aby znaleźć 250 najpopularniejszych słów kluczowych w wyszukiwarce Google na komórki, a następnie wyświetla wyniki do Arkuszy Google. W tym celu skrypt wykona te czynności:

  • Pobierz pierwszy widok (profil) autoryzowanego użytkownika.
  • Wysyłanie zapytań o dane do interfejsu API podstawowego raportowania.
  • Wstaw dane do arkusza kalkulacyjnego.

Dodaj poniższą funkcję do pustego projektu.

function runDemo() {
  try {

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

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

W powyższym kodzie blok try...catch służy do obsługi błędów interfejsu API. Jeśli wystąpią błędy, wykonanie programu zostanie zatrzymane, a błąd zostanie wyświetlony w polu komunikatu. W bloku try funkcja służy do wykonywania każdego z kroków, które przejdzie skrypt. Teraz dodajmy kod dla każdej z tych funkcji.

Pobieranie pierwszego widoku (profilu) autoryzowanego użytkownika

W Google Analytics każdy raport należy do widoku (profilu) i jest identyfikowany przez identyfikator widoku (profilu). Przy definiowaniu zapytania o dane raportu musisz też podać identyfikator widoku (profilu) widoku (profilu), z którego chcesz pobierać dane.

Interfejs Google Analytics Management API zapewnia dostęp do wszystkich kont, usług internetowych i elementów widoków (profili) należących do użytkownika. Każdy z tych elementów należy do hierarchii, z której można korzystać przy użyciu programu, aby pobrać identyfikator widoku (profilu) autoryzowanego użytkownika.

Druga funkcja, którą zapiszemy, przemierzy hierarchię interfejsu Management API i zwróci pierwszy widok (profil użytkownika) użytkownika. Skopiuj i wklej ten kod do projektu Apps Script:

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.');
  }
}

W tej funkcji najpierw wykonuje się zapytanie do kolekcji Konta przy użyciu metody Analytics.Management.Accounts.list. Jeśli autoryzowany użytkownik ma konta Google Analytics, pobierany jest identyfikator pierwszego konta. Kolejne zapytania dotyczące kolekcji usług internetowych są wykonywane przez wywołanie metody Analytics.Management.Webproperties.list i przekazywanie metody z identyfikatorem konta pobranym w poprzednim kroku. Jeśli istnieją usługi internetowe, zapytanie o kolekcję widoku (profil) jest ostatecznie wysyłane przy użyciu metody Analytics.Management.Profiles.list. Do tej metody przekazywane są zarówno identyfikator konta, jak i identyfikator usługi internetowej. Jeśli widoki danych (profile) istnieją, zwracany jest pierwszy widok (profil).

Jeśli w dowolnym momencie wystąpi błąd interfejsu API lub odpowiedź interfejsu API nie zwróci żadnych wyników, zostanie zgłoszony błąd z informacją, że nie znaleziono żadnych wyników. Blok catch w powyższej funkcji runDemo wychwyci ten błąd i wyświetli wiadomość użytkownikowi.

Po zwróceniu skryptu może wysyłać zapytania o dane raportowania.

Wysyłanie zapytań o dane do interfejsu API podstawowego raportowania.

Po utworzeniu identyfikatora widoku danych (profilu) możesz wysyłać zapytania o dane do raportu Google Analytics za pomocą interfejsu API podstawowego raportowania. Z tej sekcji dowiesz się, jak wysyłać zapytania do tego interfejsu API za pomocą Apps Script.

Dodaj ten kod do projektu Apps Script:

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');
}

Pierwsza część kodu tworzy zapytanie do interfejsu API podstawowego raportowania przy użyciu metody Analytics.Data.Ga.get. Metoda ta akceptuje kilka parametrów określających typ raportu do pobrania. Każde zapytanie interfejsu API podstawowego raportowania składa się z zestawu wymaganych i opcjonalnych parametrów. Wymagane parametry są przekazywane do metody jako parametry, a opcjonalne parametry – jako obiekt.

Parametr table ID jest wymagany i tworzy się przez połączenie prefiksu ga: z identyfikatorem widoku (profilu). Kod tworzy identyfikator tabeli przy użyciu identyfikatora widoku (profilu) pobranego w poprzednim kroku. Wymagana jest też data rozpoczęcia i zakończenia oraz określenie zakresu dat danych do pobrania. Oba są obliczane na podstawie dzisiejszej daty za pomocą funkcji getLastNdays. Na koniec wszystkie parametry opcjonalne są do niej przekazywane za pomocą obiektu optArgs.

Po uruchomieniu metody Analytics.Data.Ga.get do interfejsu API podstawowego raportowania wysyłane jest żądanie. Jeśli wystąpi błąd, jest on rejestrowany w bloku try...catch zdefiniowanym w zewnętrznej metodzie runDemo. Jeśli żądanie zostało wykonane, zwracane są wyniki.

Wstawianie danych do arkusza kalkulacyjnego

Ostatnim krokiem w skrypcie jest wyświetlenie wyników z interfejsu API podstawowego raportowania do Arkuszy Google. Działa metoda outputToSpreadsheet. Dodaj do projektu ten kod:

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());
}

Ta funkcja najpierw wstawia nowy arkusz do aktywnego arkusza kalkulacyjnego. Następnie wstawia do arkusza wszystkie nagłówki i dane raportowania. Więcej wskazówek dotyczących wstawiania danych do Arkuszy Google znajdziesz w artykule Zapisywanie danych z obiektów JavaScript w arkuszach kalkulacyjnych w samouczku dotyczącym przechowywania danych w arkuszach kalkulacyjnych.

Uruchamianie skryptu

Po dodaniu całego kodu do projektu możesz go uruchomić.

  • Na pasku narzędzi edytora skryptów w menu wyboru funkcji kliknij runDemo.
  • Następnie kliknij przycisk play.

Po pierwszym uruchomieniu pojawi się wyskakujące okienko z prośbą o autoryzację dostępu skryptu do danych konta Google Analytics.

Kliknij Autoryzuj.

Po kliknięciu otworzy się nowa strona hostowana w google.com i wyświetli się prośba o przyznanie temu skryptowi dostępu do Twoich danych. Gdy klikniesz „Zezwól”, przekierujemy Cię na stronę potwierdzenia. Od tego momentu skrypt będzie miał dostęp do danych Google Analytics i może nadal działać.

Po uruchomieniu skryptu kliknij okno Arkuszy Google. Powinny wyświetlić się wszystkie dane słów kluczowych zwrócone przez interfejs API lub pole komunikatu z komunikatem o błędzie.

Zautomatyzuj skrypt

Musisz mieć skrypt, który wysyła zapytanie do interfejsu Google Analytics API. Teraz możesz zautomatyzować ten skrypt, aby co noc pobierał nowe dane. Apps Script korzysta z funkcji triggers, która bardzo ułatwia automatyzację.

Aby zautomatyzować ten skrypt, wykonaj te czynności:

  • Na pasku narzędzi edytora skryptów kliknij Resources -> All your triggers...
  • Kliknij Add a new trigger. Pojawi się okno dialogowe wyzwalaczy.
  • Skonfiguruj aktywator do uruchamiania metody runDemo co noc
    • Menu Run powinno mieć wartość: runDemo
    • Menu Events powinno zawierać te opcje: Time-driven, Day timer i Midnight to 1am.

Po skonfigurowaniu ten skrypt będzie uruchamiał się codziennie w nocy, zapewniając dostęp do aktualnych danych rano.

Jeśli w nocy pojawią się jakieś błędy, będziesz otrzymywać powiadomienia. Apps Script umożliwia też wysyłanie e-maili z alertami w przypadku wystąpienia błędów. Aby to skonfigurować, w oknie dialogowym wyzwalaczy kliknij link notifications. Pojawi się nowe okno dialogowe, w którym możesz wybrać e-maile, na które mają być wysyłane błędy.

Podsumowanie

Udało Ci się zarejestrować i autoryzować dostęp do skryptu. Do interfejsu Management API zostało wysłane wiele zapytań w celu pobrania identyfikatora widoku (profilu). Następnie za pomocą identyfikatora widoku (profilu) możesz przesłać zapytanie do interfejsu Core Reporting API, aby pobrać dane i umieścić je w Arkuszach Google.

Korzystając z technik opisanych w samouczku, możesz przeprowadzać bardziej złożone analizy, uzyskać dokładniejsze statystyki, tworzyć niestandardowe panele informacyjne i skrócić czas potrzebny na ręczne generowanie raportów.

Oto kilka innych ciekawych samouczków, które pomogą Ci lepiej wykorzystać interfejs API Google Analytics i Google Apps Script: