自动访问 Google 表格中的 Google Analytics（分析）数据

Nick Mihailovski，Google Analytics（分析）API 团队 - 2012 年 8 月

本教程介绍了如何使用 Apps 脚本在 Google 表格中访问 Management API 和 Core Reporting API。


简介

您可以使用 Google Analytics（分析）API 和 Google Apps 脚本访问您在 Google 表格中的 Google Analytics（分析）数据。通过这种方式访问数据具有很多优势，因为您可以充分利用 Google 表格的所有出色功能来处理 Google Analytics（分析）数据，如轻松共享和协作、使用各种绘图和可视化工具。

本教程详细介绍了使用 Google Apps 脚本访问 Google 表格中的 Google Analytics（分析）数据所需的代码。

概览

本教程将介绍如何注册和配置 Apps 脚本环境，以便使用 Google Analytics（分析）API。配置完成后，本教程将向您介绍如何使用 Management API 获取已获授权用户的数据视图（配置文件）ID。然后，了解如何使用数据视图（配置文件）ID 查询 Core Reporting API，从 Google 中获取前 250 个移动搜索关键字。最后，系统会将结果插入到 Google 电子表格中。在讲述了如何获取相应数据后，本教程还将讨论如何自动获取数据。

当您使用 Google Analytics（分析）API 和 Apps 脚本构建应用时，通常需要执行以下步骤：

  • 在 Google 表格中启用 Google Analytics（分析）API
  • 使用 Google Analytics（分析）API

让我们来详细了解每个步骤。

在 Apps 脚本中启用 Google Analytics（分析）API

要在 Google 表格中启用对 Google Analytics（分析）数据的访问权限，请按照以下步骤操作：

  1. 创建 Google 表格文件。为其指定一个独特的名称。
  2. 创建新的 Apps 脚本。
    1. 在菜单中，转到扩展程序 > Apps 脚本。
    2. 如果弹出一个菜单，只需点击空白项目即可。
    3. 为此项目指定一个名称。请务必为其指定一个独特的名称。

拥有新的脚本之后，您需要启用 Google Analytics（分析）服务。

  1. 在脚本编辑器中，选择资源 > 高级 Google 服务…
  2. 在出现的对话框中，点击 Google Analytics（分析）API 旁边的启用/停用开关。
  3. 在对话框的底部，点击 Google Developers Console 链接。
  4. 在新控制台中，再次点击 Google Analytics（分析）API 旁边的启用/停用开关。（启用后，会跳到页面顶部）。
  5. 返回到脚本编辑器，点击对话框中的确定。

此时，系统应该会弹出一个黄色的小对话框，告知您已成功地将新的 Google API 服务添加到您的脚本中。现在，您即可开始编写自己的第一个脚本。

使用 Google Analytics（分析）API

本教程中的 Apps 脚本将查询 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 脚本项目中：

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 方法查询“Accounts”集合。如果已获授权的用户拥有 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 脚本来查询此 API。

将以下代码添加到您的 Apps 脚本项目中：

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 对象写入电子表格中。

运行脚本

将所有代码添加到项目后，您可以立即运行脚本。

  • 在脚本编辑器工具栏中，从“选择函数”下拉菜单中选择 runDemo。
  • 接下来，点击 play 按钮。

如果您是第一次运行此脚本，系统会弹出一个对话框，要求您授权此脚本访问您的 Google Analytics（分析）账户数据。

点击“授权”。

点击后，系统会打开一个托管在 google.com 上的新网页，并提示您授权此脚本访问您的数据。点击“允许”后，系统会将您重定向到确认页面。此时，该脚本可以立即访问您的 Google Analytics（分析）数据并且可以继续执行。

脚本运行后，点击 Google 表格窗口。 您应该会看到从 API 返回的所有关键字数据，或者显示包含错误消息的消息框。

自动执行脚本

此时，您应该已经有一个用于查询 Google Analytics（分析）API 的脚本。您现在可能想要自动执行此脚本，以便每晚检索新数据。借助 triggers 功能，Apps 脚本可以轻松实现自动化操作。

要自动执行此脚本，请按以下步骤操作：

  • 在脚本编辑器工具栏中，点击 Resources -> All your triggers...
  • 点击 Add a new trigger。 系统会显示触发器对话框。
  • 将触发器配置为每晚执行 runDemo 方法
    • Run 下拉菜单应设置为：runDemo
    • Events 下拉菜单应设置为：Time-driven、Day timer 和 Midnight to 1am。

完成配置后，此脚本将在每天晚上运行，并在每天早上为您提供最新数据。

当晚上发生任何错误时，您希望能够获得通知。如果发生任何故障，Apps 脚本还允许您发送电子邮件提醒。要进行此项配置，请在触发器对话框中点击 notifications 链接。系统会弹出一个新的对话框，让您配置希望将错误发送到哪个电子邮件地址。

总结

您已成功注册脚本并授予脚本的访问权限。您已经多次查询 Management API 以获取数据视图（配置文件）ID。然后，您使用数据视图（配置文件）ID 查询 Core Reporting API，以获取数据并将其输出到 Google 表格。

利用本教程中介绍的方法，您可以执行更复杂的分析、获得更出色的洞见、构建自定义信息中心并减少手动生成报告花费的大量时间。

此外，我们还提供以下实用的教程，以帮助您充分利用 Google Analytics（分析）API 和 Google Apps 脚本：