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。

每个客户端库提供单个 Analytics 服务对象来访问所有的 Core Reporting API 数据。要创建服务对象,您通常需要完成以下步骤:

  1. Google API 控制台中注册您的应用。
  2. 授予访问 Google Analytics(分析)数据的权限。
  3. 创建一个 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 会返回 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 的形式。外部 list 表示所有数据行。每个内部 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 均与管理 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(''));
}

metricssort 参数会以数值的形式返回到列表中,其他参数则以字符串的形式返回。

分页信息

任何 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 字段表示每个响应页返回的行数。

仅当存在上一个或下一个页面时,才会显示 previousLinknextLink 参数。访问这些链接,看看是否可以从 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 源代码