Core Reporting API - 开发者指南

本文档将说明如何使用 Core Reporting API 访问 Google Analytics（分析）数据。

简介

Core Reporting API 可以访问 Google Analytics（分析）标准报告和自定义报告中的表格数据。要访问数据，您需要创建指定以下内容的查询：数据视图（配置文件）、开始日期和结束日期、构成表格列标题的维度和指标。此查询将会发送到 Core Reporting API，然后 Core Reporting API 会以表格形式返回所有数据。

如果这是您首次使用该 API，请参阅 Core Reporting API 概览，查看 Core Reporting API 的用途及其提供的数据。

开始之前

本指南将说明如何使用 Java、Python、PHP 以及 JavaScript 等编程语言访问 Google Analytics（分析）API。

  • 请参阅客户端库页面，查看与该 API 配合使用的编程语言专用客户端库的完整列表。
  • 请参阅 参考指南，了解如何在没有客户端库的情况下访问该 API。

每个客户端库均会提供一个可以访问所有 Core Reporting API 数据的分析服务对象。要创建服务对象，您通常需要完成以下步骤：

  1. 在 Google API 控制台中注册您的应用。
  2. 授予访问 Google Analytics（分析）数据的权限。
  3. 创建 Google Analytics（分析）服务对象。

如果您未能完成上述步骤，请停止操作，并阅读 Google Analytics（分析）API 入门教程。 本教程将为您详细介绍构建 Google Analytics（分析）API 应用的初始步骤。完成这些步骤后，您就可以使用本指南执行实际任务了。

以下代码段包含一个变量，用于存储已授权的服务对象。

Java

Analytics analytics = // Read Hello Analytics Tutorial for details.

Python

analytics = # Read Hello Analytics Tutorial for details.

PHP

$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.
$client->setUseObjects(true);

$analytics = new apiAnalyticsService($client);

PHP 库会将所有 API 结果作为一个关联数组来返回。如需改为返回实际对象，您可以调用客户端 useObject 方法，如上例所示。

JavaScript

<script src="https://apis.google.com/js/client.js?onload=loadLib"</script>
<script>
function loadLib() {
  // Handle all the authorization work.
  // Read Hello Analytics Tutorial for details.
  gapi.client.load('analytics', 'v3', makeApiCall);
}
</script>

第一个脚本代码用于加载 Google API JavaScript 库。加载完成后，系统会执行 loadLib 来加载分析服务类。 完成后，对象 gapi.client.analytics 应该会存在于 DOM 中，并可用于查询 Core Reporting API。

创建分析服务对象后，您就可以向 Core Reporting API 发出请求了。

注意：该分析服务对象也可用于访问管理 API。

概览

使用 Core Reporting API 的应用一般会遵循以下两个步骤：

  • 查询 Core Reporting API
  • 处理 API 结果

我们来看一下这两个步骤。

查询 Core Reporting API

创建 Core Reporting API 查询

分析服务对象中包含创建 Core Reporting API 查询的方法。

每个 Core Reporting API 查询都包含一组参数，用于指定要返回的数据。

最重要的查询参数之一是 ids 参数（即表 ID）。此参数用于指定要从哪个 Google Analytics（分析）数据视图（配置文件）提取数据。值的格式为 ga:xxx，其中 xxx 是数据视图（配置文件）ID。

Java

Get apiQuery = analytics.data().ga()
    .get(tableId,                  // Table Id.
        "2012-01-01",              // Start date.
        "2012-01-15",              // End date.
        "ga:sessions")               // Metrics.
    .setDimensions("ga:source,ga:keyword")
    .setSort("-ga:sessions,ga:source")
    .setFilters("ga:medium==organic")
    .setMaxResults(25);

Python

api_query = service.data().ga().get(
    ids=TABLE_ID,
    start_date='2012-01-01',
    end_date='2012-01-15',
    metrics='ga:sessions',
    dimensions='ga:source,ga:keyword',
    sort='-ga:sessions,ga:source',
    filters='ga:medium==organic',
    max_results='25')

PHP

private function queryCoreReportingApi() {
  $optParams = array(
      'dimensions' => 'ga:source,ga:keyword',
      'sort' => '-ga:sessions,ga:source',
      'filters' => 'ga:medium==organic',
      'max-results' => '25');

  return $service->data_ga->get(
      TABLE_ID,
      '2010-01-01',
      '2010-01-15',
      'ga:sessions',
      $optParams);
}

在此库中，get 方法不仅会创建 Core Reporting API 查询，还会执行对 API 的请求。

JavaScript

function makeApiCall() {
  var apiQuery = gapi.client.analytics.data.ga.get({
    'ids': TABLE_ID,
    'start-date': '2010-01-01',
    'end-date': '2010-01-15',
    'metrics': 'ga:sessions',
    'dimensions': 'ga:source,ga:keyword',
    'sort': '-ga:sessions,ga:source',
    'filters': 'ga:medium==organic',
    'max-results': 25
  });
  // ...
}

在此示例中，加载 JavaScript 客户端库后，系统会调用 makeApiCall 函数。函数会在函数内创建新的 Google Analytics（分析）API 查询，并将对象存储在 apiQuery 变量中。

在 Core Reporting API 参考指南中，您可以找到全部查询参数的完整列表，以及有关参数用途的介绍。此外，您还可以使用维度和指标参数指定从 Google Analytics（分析）中提取哪些数据。如需查看完整列表，请访问 维度和指标参考页面。

发出 Core Reporting API 数据请求

定义查询后，您可以调用其 execute 方法，将查询发送到 Google Analytics（分析）服务器。

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

如果您想改为访问原始 API 响应，请使用 executeUnparsed() 方法：

HttpResponse response = apiQuery.executeUnparsed();

Python

try:
  results = get_api_query(service).execute()
  print_results(results)

except TypeError, error:
  # Handle errors in constructing a query.
  print ('There was an error in constructing your query : %s' % error)

except HttpError, error:
  # Handle API service errors.
  print ('There was an API error : %s : %s' %
         (error.resp.status, error._get_reason()))

PHP

  try {
    $results = queryCoreReportingApi();
    // Success. Do something cool!

  } catch (apiServiceException $e) {
    // Handle API service exceptions.
    $error = $e->getMessage();
  }

JavaScript

function makeApiCall() {
  // ...

  apiQuery.execute(handleCoreReportingResults);
}

function handleCoreReportingResults(results) {
  if (!results.error) {
    // Success. Do something cool!
  } else {
    alert('There was an error: ' + results.message);
  }
}

这段示例代码紧接着前面介绍的创建 Core Reporting API 查询一步。在此步骤中，系统会执行查询。 execute 方法的参数是对回调函数的引用，该回调函数会在从 API 返回数据后执行。

API 返回结果后，回调函数就会执行并传递 API 中的数据。如果发生错误，结果将包含一个名为 error 的属性。

在此示例中，系统会检查 error 是否存在或 API 是否成功返回结果。

如果查询成功，则 API 会返回请求的数据。如果出现任何错误，该 API 将返回特定的状态代码和一条说明错误的消息。 所有应用都应正确捕获并处理错误。

处理 API 结果

如果 Core Reporting API 查询成功，则 API 会返回 Google Analytics（分析）报告数据以及与数据有关的其他信息。

Google Analytics（分析）报告数据

您可以将 API 返回的主数据视为包含两大类数据的表格：

  • 说明每列值类型的标题
  • 表格中的数据行

列标题数据

每个 API 响应均包含一个表示表格标题信息的列标题字段。该字段是一个对象列表（或数组），每个对象会描述该列中的数据类型。列的顺序与原始查询中指定的顺序相同，维度列排在指标列的前面。

Java

private void printColumnHeaders(GaData gaData) {
 System.out.println("Column Headers:");

 for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
   System.out.println("Column Name: " + header.getName());
   System.out.println("Column Type: " + header.getColumnType());
   System.out.println("Column Data Type: " + header.getDataType());
 }
}

Python

def print_column_headers():
  headers = results.get('columnHeaders')

  for header in headers:
    # Print Dimension or Metric name.
    print 'Column name = %s' % header.get('name'))
    print 'Column Type = %s' % header.get('columnType')
    print 'Column Data Type = %s' % header.get('dataType')

PHP

private function printColumnHeaders(&results) {
  $html = '';
  $headers = $results->getColumnHeaders();

  foreach ($headers as $header) {
    $html .= <<<HTML
Column Name = {$header->getName()}
Column Type = {$header->getColumnType()}
Column Data Type = {$header->getDataType()}
HTML;

  print $html;
}

JavaScript

function printColumnHeaders(results) {
  var output = [];

  for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
    output.push(
        'Name        = ', header.name, '\n',
        'Column Type = ', header.columnType, '\n',
        'Data Type   = ', header.dataType, '\n'
    );
  }

  alert(output.join(''));
}

行数据

API 返回的主数据采用二维字符串 List 的形式。外部列表表示所有数据行。 每个内部列表表示一行，其中一行中单元格的顺序与上述列标题对象中字段的顺序相同。

由于每个单元格中的数据都是以字符串的形式返回的，因此每个列标题对象中的 DataType 字段尤为有用，因为它可用于将字符串值解析为相应类型。如需了解所有可能的数据类型，请参阅 metadata API 响应。

以下示例会同时输出表格的标题和行。

Java

private void printDataTable(GaData gaData) {
 if (gaData.getTotalResults() > 0) {
   System.out.println("Data Table:");

   // Print the column names.
   for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
     System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')');
   }
   System.out.println();

   // Print the rows of data.
   for (List<String> rowValues : gaData.getRows()) {
     for (String value : rowValues) {
       System.out.format("%-32s", value);
     }
     System.out.println();
   }
 } else {
   System.out.println("No Results Found");
 }

Python

def print_data_table(results):
  # Print headers.
  output = []
  for header in results.get('columnHeaders'):
    output.append('%30s' % header.get('name'))
  print ''.join(output)

  # Print rows.
  if results.get('rows', []):
    for row in results.get('rows'):
      output = []
      for cell in row:
        output.append('%30s' % cell)
      print ''.join(output)
  else:
    print 'No Results Found'

PHP

private function printDataTable(&$results) {
  if (count($results->getRows()) > 0) {
    $table .= '<table>';

    // Print headers.
    $table .= '<tr>';

    foreach ($results->getColumnHeaders() as $header) {
      $table .= '<th>' . $header->name . '</th>';
    }
    $table .= '</tr>';

    // Print table rows.
    foreach ($results->getRows() as $row) {
      $table .= '<tr>';
        foreach ($row as $cell) {
          $table .= '<td>'
                 . htmlspecialchars($cell, ENT_NOQUOTES)
                 . '</td>';
        }
      $table .= '</tr>';
    }
    $table .= '</table>';

  } else {
    $table .= '<p>No Results Found.</p>';
  }
  print $table;
}

JavaScript

function printRows(results) {
  output = [];

  if (results.rows && results.rows.length) {
    var table = ['<table>'];

    // Put headers in table.
    table.push('<tr>');
    for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
      table.push('<th>', header.name, '</th>');
    }
    table.push('</tr>');

    // Put cells in table.
    for (var i = 0, row; row = results.rows[i]; ++i) {
      table.push('<tr><td>', row.join('</td><td>'), '</td></tr>');
    }
    table.push('</table>');

    output.push(table.join(''));
  } else {
    output.push('<p>No Results Found</p>');
  }

  alert(output.join(''));
}

报告信息

API 返回的数据不仅有主表格数据，还包含一些与响应有关的汇总信息。要输出此类信息，您可以使用下列方法：

Java

private void printResponseInfo(GaData gaData) {
  System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData());
  System.out.println("Kind: " + gaData.getKind());
  System.out.println("ID:" + gaData.getId());
  System.out.println("Self link: " + gaData.getSelfLink());
}

Python

def print_response_info(results):
  print 'Contains Sampled Data = %s' % results.get('containsSampledData')
  print 'Kind                  = %s' % results.get('kind')
  print 'ID                    = %s' % results.get('id')
  print 'Self Link             = %s' % results.get('selfLink')

PHP

private function printReportInfo(&$results) {
  $html = <<<HTML
  <pre>
Contains Sampled Data = {$results->getContainsSampledData()}
Kind                  = {$results->getKind()}
ID                    = {$results->getId()}
Self Link             = {$results->getSelfLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printReportInfo(results) {
  var output = [];

  output.push(
      'Contains Sampled Data  = ', results.containsSampledData, '\n',
      'Kind                   = ', results.kind, '\n',
      'ID                     = ', results.id, '\n',
      'Self Link              = ', results.selfLink, '\n');

  alert(output.join(''));
}

containsSampledData 字段非常重要，因为它可以说明 API 响应是否为抽样结果。抽样可能会影响数据的结果，以及 API 返回的值与网页界面不匹配的常见原因。有关详情，请参阅采样概念指南。

数据视图（配置文件）信息

每个响应均包含一组可指明此数据所属账户、网络媒体资源以及数据视图（配置文件）的参数。

Java

private void printProfileInfo(GaData gaData) {
  GaDataProfileInfo profileInfo = gaData.getProfileInfo();

  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Python

def print_profile_info(result):

  info = results.get('profileInfo')
  print 'Account Id          = %s' % info.get('accountId')
  print 'Web Property Id     = %s' % info.get('webPropertyId')
  print 'Web Property Id     = %s' % info.get('internalWebPropertyId')
  print 'View (Profile) Id   = %s' % info.get('profileId')
  print 'Table Id            = %s' % info.get('tableId')
  print 'View (Profile) Name = %s' % info.get('profileName')

PHP

private function printProfileInformation(&$results) {
  $profileInfo = $results->getProfileInfo();

  $html = <<<HTML
<pre>
Account ID               = {$profileInfo->getAccountId()}
Web Property ID          = {$profileInfo->getWebPropertyId()}
Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()}
Profile ID               = {$profileInfo->getProfileId()}
Table ID                 = {$profileInfo->getTableId()}
Profile Name             = {$profileInfo->getProfileName()}
</pre>
HTML;

  print $html;
}

JavaScript

function printProfileInfo(results) {
  var output = [];

  var info = results.profileInfo;
  output.push(

      'Account Id          = ', info.accountId, '\n',
      'Web Property Id     = ', info.webPropertyId, '\n',
      'View (Profile) Id   = ', info.profileId, '\n',
      'Table Id            = ', info.tableId, '\n',
      'View (Profile) Name = ', info.profileName);

  alert(output.join(''));
}

这些 ID 中的每一个都对应于 Management API 层次结构中的不同实体。 您可以使用这些 ID 构建管理 API 查询，以获取有关数据视图（配置文件）的其他配置信息。例如，您可以查询 管理 API 目标集合，了解哪些目标处于有效状态，以及这些目标已配置的目标名称。

查询信息

每个 Core Reporting API 响应均包含一个对象，该对象包含创建响应所需的全部查询参数值。

Java

private void printQueryInfo(GaData gaData) {
  GaDataQuery query = gaData.getQuery();

  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics()); // List
  System.out.println("Dimensions: " + query.getDimensions());
  System.out.println("Sort: " + query.getSort()); // List
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

Python

def print_query_info(results):
  query = results.get('query')
  for key, value in query.iteritems():
    print '%s = %s' % (key, value)

PHP

private function printQueryParameters(&$results) {
  $query = $results->getQuery();

  $html = '<pre>';
  foreach ($query as $paramName => $value) {
    $html .= "$paramName = $value\n";
  }
  $html .= '</pre>';

  print $html;
}

JavaScript

function printQuery(results) {
  output = [];

  for (var key in results.query) {
    output.push(key, ' = ', results.query[key], '\n');
  }

  alert(output.join(''));
}

metrics 和 sort 参数以值的形式在列表中返回，其他参数以字符串形式返回。

分页信息

任何 Core Reporting API 请求均可能与数万行 Google Analytics（分析）数据相匹配。在给定时间内，Core Reporting API 仅会返回一个子集，您可将其视为一页数据。您可以使用分页字段提取所有数据页。

Java

private void printPaginationInfo(GaData gaData) {
  System.out.println("Items Per Page: " + gaData.getItemsPerPage());
  System.out.println("Total Results: " + gaData.getTotalResults());
  System.out.println("Previous Link: " + gaData.getPreviousLink());
  System.out.println("Next Link: " + gaData.getNextLink());
}

Python

def print_pagination_info(results):
  print 'Items per page = %s' % results.get('itemsPerPage')
  print 'Total Results  = %s' % results.get('totalResults')
  print 'Previous Link  = %s' % results.get('previousLink')
  print 'Next Link      = %s' % results.get('nextLink')

PHP

private function getPaginationInfo(&$results) {
  $html = <<<HTML
<pre>
Items per page = {$results->getItemsPerPage()}
Total results  = {$results->getTotalResults()}
Previous Link  = {$results->getPreviousLink()}
Next Link      = {$results->getNextLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printPaginationInfo(results) {
  var output = [];

  output.push(
      'Items Per Page = ', results.itemsPerPage, '\n',
      'Total Results  = ', results.totalResults, '\n',
      'Previous Link  = ', results.previousLink, '\n',
      'Next Link      = ', results.nextLink, '\n');

  alert(output.join(''));
}

totalResults 字段表示您的查询在 Google Analytics（分析）中匹配的数据行总数。此值可能会大于单个响应页面中返回的实际行数。 itemsPerPage 字段表示此页面中返回的行数。

仅当存在上一页或下一页时，才会出现 previousLink 和 nextLink 参数。访问这些链接，看看是否可以从 Core Reporting API 中提取更多数据页。

所有结果的总值

如上文中的“分页信息”部分所述，一条 Core Reporting API 查询可能会匹配 Google Analytics（分析）中的多行数据，但只会返回部分数据。所有匹配行的指标总值都在 totalsForAllResults 对象中返回。这些数据对于计算平均值非常有用。

Java

private void printTotalsForAllResults(GaData gaData) {
  Map totalsMap = gaData.getTotalsForAllResults();

  for (Map.Entry entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Python

def print_totals_for_all_results(results):
  totals = results.get('totalsForAllResults')

  for metric_name, metric_total in totals.iteritems():
    print 'Metric Name  = %s' % metric_name
    print 'Metric Total = %s' % metric_total

PHP

private function printTotalsForAllResults(&$results) {
  $totals = $results->getTotalsForAllResults();

  foreach ($totals as $metricName => $metricTotal) {
    $html .= "Metric Name  = $metricName\n";
    $html .= "Metric Total = $metricTotal";
  }

  print $html;
}

JavaScript

function printTotalsForAllResults(results) {
  var output = [];

  var totals = results.totalsForAllResults;
  for (metricName in totals) {
    output.push(
        'Metric Name  = ', metricName, '\n',
        'Metric Total = ', totals[metricName], '\n');
  }

  alert(output.join(''));
}

工作示例

要查看完整的工作示例，请访问每个客户端库的示例目录中的 Core Reporting API 示例。

Java

Google API Java 客户端库 Core Reporting API 样本

Python

Google API Python 客户端库 Core Reporting API 示例

PHP

Google API PHP 客户端库 Core Reporting API 示例

JavaScript

Google API JavaScript 客户端库 Core Reporting API 示例

JavaScript 源代码