自動在 Google 試算表中存取 Google Analytics (分析) 資料

Google Analytics (分析) API 團隊 Nick Mihailovski - 2012 年 8 月

本教學課程說明如何使用 Apps Script 在 Google 試算表中存取 Management 和 Core Reporting API。


簡介

您可以使用 Google Analytics API 和 Google Apps Script 從 Google 試算表存取 Google Analytics (分析) 資料。這個功能非常強大，可讓您透過 Google 試算表的所有強大功能與數據分析資料搭配使用，例如輕鬆共用、協作、製作圖表及製作圖表。

本教學課程將逐步介紹透過 Google Apps Script 在 Google 試算表中存取 Google Analytics (分析) 資料所需的程式碼。

總覽

本教學課程說明如何註冊及設定 Apps Script 環境，以便使用 Google Analytics API。設定完畢後，教學課程會逐步說明如何使用 Management API 擷取授權使用者的資料檢視 (設定檔) ID。接著瞭解如何使用資料檢視 (個人資料) ID 查詢 Core Reporting API，從 Google 擷取前 250 個行動搜尋關鍵字。結果則會插入到 Google 試算表中。取得資料後，教學課程也會討論如何自動擷取資料。

使用 Google Analytics API 和 Apps Script 建構應用程式時，一般會完成下列步驟：

  • 在 Google 試算表中啟用 Google Analytics (分析) API
  • 使用 Google Analytics (分析) API

接著我們將詳細說明各個步驟。

在 Apps Script 中啟用 Google Analytics API

如要在 Google 試算表中存取 Google Analytics (分析) 資料，請按照下列步驟操作：

  1. 建立 Google 試算表檔案。為它取個酷炫的名稱。
  2. 建立新的 Apps Script。
    1. 在選單中依序點選「擴充功能」>>「Apps Script」。
    2. 如果出現彈出式視窗，請按一下「Blank Project」。
    3. 為專案命名。請確定這個名稱很酷。

取得新的指令碼後，您必須啟用 Google Analytics (分析) 服務。

  1. 在指令碼編輯器中，依序選取「資源」>「進階 Google 服務...」。
  2. 在出現的對話方塊中，按一下 Google Analytics API 旁的「開啟/關閉」切換按鈕。
  3. 在對話方塊底部，按一下 Google Developers Console 連結。
  4. 在新版控制台中，再次點選 Google Analytics (分析) API 旁的「開啟/關閉」切換按鈕。(啟用後就會跳到頁面頂端)。
  5. 返回指令碼編輯器，然後按一下對話方塊中的「OK」。

畫面上會出現一個黃色對話方塊，指出您已成功在指令碼中加入新的 Google API 服務。您現在可以開始編寫第一個指令碼了。

使用 Google Analytics API

這個教學課程中的指令碼會查詢 Google Analytics API，找出前 250 大 Google 行動搜尋關鍵字，然後將結果輸出至 Google 試算表。為達成這個目的，這個指令碼將執行下列步驟：

  • 擷取授權使用者的第一個資料檢視 (個人資料)。
  • 透過 Core Reporting API 查詢資料。
  • 在試算表中插入資料。

將下列函式新增至空白專案。

function runDemo() {
  try {

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

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

在上述程式碼中，try...catch 區塊是用來處理任何 API 錯誤。如果發生任何錯誤，程式執行作業會停止，並在訊息方塊中顯示錯誤。在 try 區塊中，函式將用來執行指令碼經歷的每個步驟。現在，讓我們為每個函式新增程式碼。

擷取授權使用者的第一檢視畫面 (設定檔)

在 Google Analytics (分析) 中，每份報表都屬於某個資料檢視 (設定檔)，並以資料檢視 (設定檔) ID 識別。因此，指定報表資料查詢時，也必須指定要擷取資料的資料檢視 (設定檔) ID。

Google Analytics (分析) Management API 提供使用者所有帳戶、網站資源和資料檢視 (設定檔) 實體的存取權，這些實體都屬於階層中，您可以透過程式輔助方式掃遍這個階層，擷取授權使用者的資料檢視 (設定檔) ID。

我們編寫的第二個函式將會掃遍 Management API 階層，並傳回使用者的第一個檢視畫面 (設定檔)。複製下列程式碼並貼到 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.');
  }
}

在此函式中，系統會先使用 Analytics.Management.Accounts.list 方法查詢「帳戶」集合。如果授權使用者擁有 Google Analytics (分析) 帳戶，系統會擷取第一個帳戶的 ID。接下來，呼叫 Analytics.Management.Webproperties.list 方法並傳遞在上一步擷取的帳戶 ID 方法，即可查詢網站資源集合。如果網站資源存在，系統最終會使用 Analytics.Management.Profiles.list 方法查詢資料檢視 (設定檔) 集合。帳戶 ID 和網站資源 ID 都會以參數的形式傳送至這個方法。如果資料檢視 (設定檔) 存在，系統會傳回第一個檢視畫面 (設定檔)。

如果發生 API 錯誤，或 API 回應不含任何結果，系統會擲回錯誤，並附帶說明找不到任何結果的訊息。上述 runDemo 函式中的 catch 區塊會擷取這個錯誤，並向使用者顯示訊息。

指令碼傳回後，現在可以查詢報表資料。

透過 Core Reporting API 查詢資料。

取得資料檢視 (設定檔) ID 後，您可以使用 Core Reporting API 查詢 Google Analytics (分析) 報表資料。在本節中，您將學習如何使用 Apps Script 查詢這個 API。

將下列程式碼加入 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');
}

程式碼的第一個部分會使用 Analytics.Data.Ga.get 方法建構 Core Reporting API 查詢。這個方法可接受多個參數，用於指定要擷取的報表類型。每個 Core Reporting API 查詢都是由一組必要和選用的參數組成。必要參數會以參數的形式傳遞至方法，選用的參數則會以物件的形式傳遞。

table ID 是必要參數，結合 ga: 前置字串與檢視畫面 (設定檔) ID 的方式形成。程式碼會使用在上一個步驟中擷取的資料檢視 (設定檔) ID 建立資料表 ID。您也必須指定開始和結束日期，並指定擷取資料的日期範圍。這兩個項目都會使用 getLastNdays 函式計算今天的日期。最後，所有選用參數都會使用 optArgs 物件傳遞至函式。

Analytics.Data.Ga.get 方法執行時，系統會向 Core Reporting API 發出要求。如果發生錯誤，系統會在外部 runDemo 方法中定義的 try...catch 區塊中發現錯誤。如果要求成功，系統會傳回結果。

將資料插入試算表

指令碼的最後一個步驟是將 Core Reporting API 的結果輸出到 Google 試算表。outputToSpreadsheet 方法會執行這項作業。將下列程式碼加入專案中：

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

這個函式會先將新的工作表插入使用中的試算表。接著，就能在工作表中插入所有標題和報表資料。如需更多在 Google 試算表插入資料的提示，請參閱 在試算表儲存資料教學課程中的 從 JavaScript 物件將資料寫入試算表一文。

執行指令碼

將所有程式碼新增至專案後，即可開始執行。

  • 在指令碼編輯器工具列的「Select 函式」下拉式選單中，選取 runDemo。
  • 接下來，按一下 play 按鈕。

首次執行時，畫面上會顯示彈出式視窗，請您授權此指令碼存取您的 Google Analytics (分析) 帳戶資料。

按一下「授權」。

使用者點選後，系統會開啟 google.com 代管的新網頁，並提示您授權這個指令碼存取您的資料。點選「允許」之後，系統會將您重新導向至確認頁面。此時，指令碼現在可以存取您的 Google Analytics (分析) 資料，且可以繼續執行。

指令碼執行後，然後點選 Google 試算表視窗。 您應該會看到此 API 傳回的所有關鍵字資料，或是包含錯誤訊息的訊息方塊。

自動執行指令碼

此時，您應該會有一個查詢 Google Analytics (分析) API 的指令碼。您現在可以自動設定這個指令碼，每天晚上擷取新資料。 Apps Script 可讓您使用 triggers 功能輕鬆執行自動化作業。

如要自動執行這個指令碼，請按照下列步驟操作：

  • 在指令碼編輯器工具列中，按一下 Resources -> All your triggers...
  • 按一下 Add a new trigger，系統隨即會顯示觸發對話方塊。
  • 設定觸發條件，每晚執行 runDemo 方法
    • Run 下拉式選單應設為：runDemo
    • Events 下拉式選單應設為：Time-driven、Day timer 和 Midnight to 1am。

設定這個指令碼後，系統就會每晚執行，提供早晨的最新資料。

如果晚上發生任何錯誤，我們會建議您發出通知。另外，Apps Script 也可讓您傳送電子郵件快訊，以在發生任何失敗時傳送快訊。如要進行這項設定，請在觸發條件對話方塊中按一下 notifications 連結。畫面上會出現新的對話方塊，可讓您設定要接收錯誤的電子郵件。

結語

您已成功註冊並授權指令碼存取。您已經多次查詢 Management API 來擷取資料檢視 (設定檔) ID。接著，您會使用檢視表 (設定檔) ID 查詢 Core Reporting API，藉此擷取資料並輸出至 Google 試算表。

按照教學課程所述技巧，您可以執行更複雜的分析、取得更深入的分析資料、建立自訂資訊主頁，並且減少大量手動執行報表的時間。

以下提供其他實用的教學課程，有助您充分運用 Google Analytics (分析) API 和 Google Apps Script：